+ 2ji,Rt^RIHt^RIHt^RIHtHtHt^RI H t H t ^RI H t HtHtHt^RIHtHtHtHt^RIHt^RIHt^R IHt^R IHt^R IHt^R I H!t!H"t"H#t#H$t$H%t%H&t&H't'H(t(H)t)] 'd^R I*H+t+.R"Ot,Rt-] !RR7!RR]]$])3,44t.!RR]]$])3,4t/!RR]]$])3,4t0] !RR]]$,44t1!RR]]$])3,4t2RRlt3RRlt4!R R]]$])3,4t5R!#)#aPubGrub dependency resolver. Implements unit propagation, conflict resolution with clause learning, and non-chronological backjumping. PubGrub was designed by Natalie Weizenbaum for Dart's pub, adapting CDCL (conflict-driven clause learning) from SAT solving to version resolution. The phase functions live in :mod:`nab_resolver.propagate`, :mod:`nab_resolver.conflict`, :mod:`nab_resolver.decide`, and :mod:`nab_resolver.incompat_index`. ``Resolver`` is a thin coordinator that holds shared state and delegates to those modules. State attributes are named without leading underscores so the phase modules can read and mutate them directly; the supported public API is ``__init__``, ``resolve``, ``solve``, and ``stats``. Specification: https://github.com/dart-lang/pub/blob/master/doc/solver.md Original blog post: https://nex3.medium.com/pubgrub-2fb6470504f Rust implementation: https://github.com/pubgrub-rs/pubgrub ) annotations) defaultdict)CallableMappingSequence) dataclassfield) TYPE_CHECKINGAnyGenericProtocol)conflictdecideincompat_index propagate)ResolutionError)PartialSolution)Range)build_solution_data)ROOT) IncompatibilityIncompatibilityCauseIncompatibilityState PackageType RangeProtocolRootRequirement SetRelationTerm VersionType)TypeIs BaseProviderResolverResolverObserverResolverProvider ResolverStatsSolutioni@ T)frozenc:]tRt^Et$RtR]R&R]R&R]R&RtR #) r%afPins and dependency relationships from a finished resolution. ``pins`` maps every transitively reachable package to its decided version. ``edges`` are distinct ``(parent, child)`` pairs in breadth-first order from ``roots``. Both endpoints of each edge are keys of ``pins``. ``roots`` are the packages the caller required directly, in requirement order. dict[PackageType, VersionType]pinsz+tuple[tuple[PackageType, PackageType], ...]edgesztuple[PackageType, ...]rootsN)__name__ __module__ __qualname____firstlineno____doc____annotations____static_attributes__r,`/home/user/billing-ledger-validation/.venv/lib/python3.14/site-packages/nab_resolver/resolver.pyr%r%Es )( 66 ""r4c]tRt^UtRtRRltRRltRRltRR ltRR R llt R Rlt RRlt RRlt RRlt RRltRRltRtR #)r#zInterface for supplying version and dependency information. Modeled after pubgrub-rs v0.3+ ``DependencyProvider``: https://docs.rs/pubgrub/latest/pubgrub/trait.DependencyProvider.html c$V^8dQhRRRRRR/#)packager version_rangeRangeProtocol[VersionType]returnzVersionType | Noner,)formats"r5 __annotate__ResolverProvider.__annotate__\s$  " 3M  r4c R#)z9Pick a version for package within version_range, or None.Nr,selfr9r:s&&&r5choose_versionResolverProvider.choose_version\ r4c$V^8dQhRRRRRR/#)r8r9rr:r;r<boolr,)r=s"r5r>r?bs$   "  3M    r4c R#)aReturn whether ``choose_version`` would pick a version in ``version_range``. A diagnostic query with no lasting side effect: it is used to attribute a ``NO_VERSIONS`` failure to a user constraint only when the un-narrowed range still offers a version the constraint clipped away. Providers that queue clauses or record state during ``choose_version`` must not let any of that escape here. Nr,rAs&&&r5has_satisfying_version'ResolverProvider.has_satisfying_versionb r4c$V^8dQhRRRRRR/#)r8r9rversionrr<0Mapping[PackageType, RangeProtocol[VersionType]]r,)r=s"r5r>r?os$  " -8 9 r4c R#)zAReturn ``{dependency_package: required_range}`` for this version.Nr,rBr9rMs&&&r5get_dependencies!ResolverProvider.get_dependenciesorEr4cV^8dQhRR/#r8r<Noner,)r=s"r5r>r?us   T  r4c R#)aZAnnounce the start of one decision scan. ``choose_package_to_decide`` builds every undecided package's sort key from ``prioritize`` and ``is_ready``, so both must answer from state that does not move until the next call. Providers whose answers depend on another thread freeze that state here; for providers with no such state this is a no-op. Nr,rBs&r5begin_decision_scan$ResolverProvider.begin_decision_scanus r4Nc ,V^8dQhRRRRRRRRR R /#) r8r9rr:r;conflict_countszMapping[PackageType, int]culprit_countsz Mapping[PackageType, int] | Noner<r r,)r=s"r5r>r?s<   2 3  9   r4c R#)aReturn a sort key for deciding which package to resolve next. Lower values resolve first. ``conflict_counts`` tracks how often a decision on this package was discarded; ``culprit_counts`` tracks how often this package was decided earlier and caused another's decision to be discarded. Nr,)rBr9r:r[r\s&&&&&r5 prioritizeResolverProvider.prioritizes r4c V^8dQhRRRR/#r8r9rr<rGr,)r=s"r5r>r?s    r4c R#)zReturn True when the provider can answer cheaply for ``package``. Lets the resolver prefer ready packages while async fetches are still in flight. Providers without an async layer should return True. Nr,rBr9s&&r5is_readyResolverProvider.is_readys r4c$V^8dQhRRRRRR/#r8positive_rangesrN decisionsz!Mapping[PackageType, VersionType]r<rUr,)r=s"r5r>r?s(   I  5     r4c R#)aaAccept a snapshot of positive ranges and decisions. Called before ``choose_version`` so providers can forward-check the candidate's dependencies against accumulated constraints. ``decisions`` is the subset with concrete versions (not derivations); decision-based reasoning is safer because decisions cannot be undone in isolation. Default is a no-op. Nr,rBrhris&&&r5receive_partial_solution_hint.ResolverProvider.receive_partial_solution_hints r4cV^8dQhRR/#r8r<z/list[Incompatibility[PackageType, VersionType]]r,)r=s"r5r>r?s   8  r4c R#)aRReturn incompatibilities the provider queued during ``choose_version``. Drained after every ``choose_version`` call. When non-empty AND ``choose_version`` returned None, the resolver suppresses the default ``NO_VERSIONS`` clause (which would persist across backjumps) so the provider's context-aware clauses become the source of truth. Nr,rWs&r5consume_pending_clauses(ResolverProvider.consume_pending_clausess r4cV^8dQhRR/#r8r<zlist[PackageType]r,)r=s"r5r>r?s   1B  r4c R#)agReturn packages the provider wants force-backtracked. Drained after every ``choose_version`` call. When non-empty, the resolver bumps each package's culprit count past the demote threshold, queues it, and fires ``apply_targeted_backtrack`` without waiting for the normal conflict-count gate. Providers without a force-backtrack signal return an empty list. Nr,rWs&r5consume_force_backtrack_targets0ResolverProvider.consume_force_backtrack_targetsrKr4c$V^8dQhRRRRRR/#)r8r9rrMrr<z!RangeProtocol[VersionType] | Noner,)r=s"r5r>r?s$  " -8 * r4c R#)aReturn a widened stand-in for ``version`` in dependency clauses, or None. Called at most once per decision, after ``get_dependencies`` returned a non-empty mapping for ``version``, so a provider may answer from what that call cached. Soundness contract: the returned range must contain ``version``, and every version inside it that could ever be chosen for ``package`` in this resolution must have exactly the dependencies being recorded for ``version``; versions inside it that can never be selected are harmless. ``None`` keeps the exact singleton. Widening merges dependency clauses for adjacent rejected versions into contiguous ranges instead of one hole per version, and lets a single clause reject a whole run of same-dependency versions. Nr,rPs&&&r5widen_decisionResolverProvider.widen_decisions$ r4c$V^8dQhRRRRRR/#r8r9r constraintr;r<r,)r=s"r5r>r?s$  " 0J # r4c R#)aKMap a possibly-widened ``constraint`` back onto known versions. Applied at error-render time only; the derivation state is never mutated. The renderer narrows every originally-positive term, so ``package`` may be the virtual root sentinel or another package outside the provider's namespace; return such constraints unchanged, as providers that do not widen do for all input. Soundness contract: the result must hold the same known versions as ``constraint``. The renderer reports what a narrowing drops as a range holding no version, so dropping one that exists states a falsehood. Nr,rBr9r~s&&&r5narrow_for_display#ResolverProvider.narrow_for_displays r4r,N)r-r.r/r0r1rCrIrQrXr^rdrlrqrvrzrr3r,r4r5r#r#UsC              (  r4cb]tRt^tRtRRltRRltRRltRR ltR R lt R R lt Rt R#)r aDefaults for the six provider methods a synchronous provider does not need. Supplies ``begin_decision_scan``, ``is_ready``, ``receive_partial_solution_hint``, ``consume_pending_clauses``, ``consume_force_backtrack_targets`` and ``narrow_for_display``, the six :class:`ResolverProvider` methods with nothing to do when there is no async layer, no queued clauses and no widening. A subclass still owes ``choose_version``, ``has_satisfying_version``, ``get_dependencies``, ``prioritize`` and ``widen_decision``. Subclassing is optional; the resolver accepts anything that satisfies the protocol. Nothing re-exports this, so import it as ``from nab_resolver.resolver import BaseProvider``. cV^8dQhRR/#rTr,)r=s"r5r>BaseProvider.__annotate__s<rs r4c ?R#)zAReport every package ready, since answers do not wait on a fetch.Tr,rcs&&r5rdBaseProvider.is_readys r4c$V^8dQhRRRRRR/#rgr,)r=s"r5r>rs(''I'5'  'r4c ??R#)z:Drop the snapshot: nothing here forward-checks against it.Nr,rks&&&r5rl*BaseProvider.receive_partial_solution_hints Yr4cV^8dQhRR/#ror,)r=s"r5r>rs 8r4c .#)z2Return no clauses: ``choose_version`` queues none.r,rWs&r5rq$BaseProvider.consume_pending_clausess  r4cV^8dQhRR/#rtr,)r=s"r5r>r s1Br4c .#)z>Return no targets: there is no force-backtrack signal to give.r,rWs&r5rv,BaseProvider.consume_force_backtrack_targets s r4c$V^8dQhRRRRRR/#r}r,)r=s"r5r>rs$  " 0J  # r4c ?V#)zReturn the constraint unchanged, as a provider that never widens does. A subclass whose ``widen_decision`` widens overrides this as well, or its error text carries widened ranges instead of known versions. r,rs&&&r5rBaseProvider.narrow_for_displays  r4r,N) r-r.r/r0r1rXrdrlrqrvrr3r,r4r5r r s* < '   r4c]tRtRt$Rt^tR]R&^tR]R&^tR]R&^t R]R&^t R]R&^t R]R &^t R]R &^t R]R &]!R R 7tR]R&]!RR 7tR]R&RtR#)r$izRunning statistics for resolution observability. Inspired by SAT solver statistics (MiniSat, CaDiCaL) which track decisions, conflicts, propagations, and restarts as standard metrics. See: https://minisat.se/MiniSat.html introundsri conflicts derivations backjumpsrestartstargeted_backtracksincompatibilities_learnedc \\4#rrrr,r4r5ResolverStats.. C 0r4)default_factoryzdefaultdict[PackageType, int]package_conflict_countsc \\4#rrr,r4r5rr1rr4package_culprit_countsr,N)r-r.r/r0r1rr2rirrrrrrrrrr3r,r4r5r$r$sFCOIsIsKIsHc  %&s&=B0>:=B0=9r4cn]tRtRtRtRRltRRltRRltR R ltR R lt R Rlt RRlt Rt R#)r"i5z.Override methods to observe resolution events.c(V^8dQhRRRRRRRR/#) r8r9rrMrlevelrr<rUr,)r=s"r5r>ResolverObserver.__annotate__8s,//"/-8/AD/ /r4c R#)z Handle a version decision event.Nr,)rBr9rMrs&&&&r5 on_decisionResolverObserver.on_decision8rr4c(V^8dQhRRRRRRRR/#) r8r9rpositiverGcause)Incompatibility[PackageType, VersionType]r<rUr,)r=s"r5r>r=s2999 9 9 9  9r4c R#)z*Handle a derivation from unit propagation.Nr,)rBr9rrs&&$$r5 on_derivationResolverObserver.on_derivation=rr4c V^8dQhRRRR/#r8incompatibilityrr<rUr,)r=s"r5r>rFs11H1 1r4c R#)z"Handle a conflict detection event.Nr,rBrs&&r5 on_conflictResolverObserver.on_conflictFrr4c V^8dQhRRRR/#rr,)r=s"r5r>rKs66H6 6r4c R#)z'Handle a learned incompatibility event.Nr,rs&&r5 on_learnedResolverObserver.on_learnedKrr4c$V^8dQhRRRRRR/#)r8 from_levelrto_levelr<rUr,)r=s"r5r>rPs!''c'S'T'r4c R#)zHandle a backjump event.Nr,)rBrrs&&&r5 on_backjumpResolverObserver.on_backjumpPrr4c$V^8dQhRRRRRR/#)r8r9rr:r;r<rUr,)r=s"r5r>rSs$44"43M4 4r4c R#)z%Handle a no-versions-available event.Nr,rAs&&&r5on_no_versionsResolverObserver.on_no_versionsSrr4c4V^8dQhRRRRRRRRR RR RR R /#) r8rrsatisfier_packagersatisfier_is_decisionrGsatisfier_levelrprevious_level can_backjumpr<rUr,)r=s"r5r>rXsY D DB D' D $ D  D D D  Dr4c R#)z5Handle one iteration of the conflict resolution loop.Nr,)rBrrrrrrs&&$$$$$r5on_conflict_step!ResolverObserver.on_conflict_stepXrr4r,N) r-r.r/r0r1rrrrrrrr3r,r4r5r"r"5s/8/ 91 6 '4 D Dr4c V^8dQhRRRR/#)r8 requirementsfMapping[PackageType, RangeProtocol[VersionType]] | Sequence[RootRequirement[PackageType, VersionType]]r<z;TypeIs[Sequence[RootRequirement[PackageType, VersionType]]]r,)r=s"r5r>r>es! 1 1: 1A 1r4c,\V\4'*#)aReturn whether the caller passed the one-clause-per-requirement form. A ``TypeIs`` rather than a bare ``isinstance``: one type can satisfy both members of the union, so plain narrowing can leave an intersection that has lost the mapping's value type. ty needs the sequence rather than the mapping as the narrowed side to keep those parameters, while the test itself stays on ``Mapping`` so every non-mapping iterable is still taken as the sequence form. ) isinstancer)rs&r5_is_root_sequenceres,0 00r4c V^8dQhRRRR/#)r8rrr<3Sequence[RootRequirement[PackageType, VersionType]]r,)r=s"r5r>r>us  : 9 r4c\V4'dV#VP4UUu.uF"wr\\\3,!W4NK$ upp#uuppi)zGAccept either shape ``Resolver.resolve`` takes and return the sequence.)ritemsrrr)rr9required_ranges& r5_as_root_requirementsrusW && (4'9'9'; '; #G  [01'J';  s(Ac]tRtRtRt^t^t^t^t^@t R] ] ^] 3RRllt RRRlltRRR lltR R ltR R ltRRltRRltRRltRtR#)r!iaaPubGrub dependency resolver. The main loop follows the PubGrub specification: 1. Unit propagation: derive constraints from incompatibilities 2. Conflict resolution: learn new incompatibilities and backjump 3. Decision making: pick the next package and version to try Reference: https://github.com/dart-lang/pub/blob/master/doc/solver.md#the-algorithm Nc4V^8dQhRRRRRRRRR R R R R R/#)r8providerz*ResolverProvider[PackageType, VersionType]observerz1ResolverObserver[PackageType, VersionType] | Nonemax_iterationsr range_typeztype[RangeProtocol[Any]] root_versionr format_rangezCallable[[Any], str]r<rUr,)r=s"r5r>Resolver.__annotate__sQ99<9D9 9 - 9  9+9 9r4c >WnT;'g \4VnW0nW@nWPnW`n.Vn\\4Vn /Vn \VR7Vn \4Vn/Vn/Vn.Vn/Vn/VnR#)aCreate a resolver with the given provider and optional observer. The ``root_version`` is a sentinel passed to ``range_type.singleton()`` to build the virtual root package's range. The default ``1`` works for :class:`~nab_resolver.ranges.Range` (which accepts any comparable type) but a PEP 440 range type such as :class:`packaging.ranges.VersionRange` requires a parseable version string or :class:`~packaging.version.Version` here. ``format_range`` renders a constraint in a failure report. It travels with ``range_type``: the default ``str`` reads well for :class:`~nab_resolver.ranges.Range`, while a range type whose ``str`` is a debug representation needs its own. rN)rr"rrrrrincompatibilitiesrlistpackage_to_incompatibilitiesdependency_indexrsolutionr$stats constraintsroot_package_orderpending_targeted_backtracktiebreak_cacherelation_cache)rBrrrrrrs&&&&&&&r5__init__Resolver.__init__s.!  * *(* -$((BDIT J ) 133B!4  2? MOKM=?'HJ  r4c$V^8dQhRRRRRR/#)r8rrr7Mapping[PackageType, RangeProtocol[VersionType]] | Noner<r(r,)r=s"r5r>rs+ : :> :M : ( :r4c 8VPW4P#)zResolve requirements and return ``{package: version}``. The pins of :meth:`solve`, for a caller that has no use for the dependency graph. )solver))rBrrs&&&r5resolveResolver.resolveszz,4999r4c$V^8dQhRRRRRR/#)r8rrrrr<"Solution[PackageType, VersionType]r,)r=s"r5r>rs+9090>90M 90 , 90r4c &VPV4VP\V44VPpVPp\ p\ VP4FpVP;P^, un \P!W4pVeVPVVV4wrSpKX\P!V4pVfVP4u#VP!V4pK RVP R2p \#V 4h)a-Resolve requirements and return the pins, roots, and edges. ``requirements`` is either one range per package, or a sequence of :class:`~nab_resolver.types.RootRequirement` when the caller has more than one requirement on a package and wants each named as written in the failure report. Constraints restrict a package's version range but do not cause it to be installed. They are injected lazily: only when the resolver is about to decide a constrained package (meaning something already depends on it). Raises ``ResolutionError`` if no solution exists. zResolution exceeded z iterations)_reset_add_root_requirementsr_RESTART_THRESHOLD _MAX_RESTARTSrrangerrrrunit_propagation_handle_conflictrchoose_package_to_decide _build_result _decide_nextr) rBrrrestart_thresholdrestarts_remainingchanged_package_conflicting_incompatibility next_packageexceeded_messages &&& r5rResolver.solves( K  ##$9,$GH!33!//#t**+A JJ   " +4*D*D+ '+6))3)*G4F"::4@L#))++"// =O3,62$2E2E1FkR.//r4c(V^8dQhRRRRRRRR/#)r8rzIncompatibility[Any, Any]rrrr<ztuple[Any, int, int]r,)r=s"r5r>rs8FF%>FF F  Fr4c tVP;P^, unVPPV4\P !W4pVP ^,Pp\P!V4pVeTp\P!WV4wr#pV'd\pWRV3#)z@Run conflict resolution, targeted backtrack, and restart phases.) rrrrr conflict_resolutiontermsr9maybe_targeted_backtrack maybe_restartr)rBrrrlearnedr triggering restarteds&&&& r5r Resolver._handle_conflicts ! !!"=>..tQ&}}Q/7766t<  !(O;C;Q;Q %7< 8y "O3EEEr4c V^8dQhRRRR/#)r8rr r<r,)r=s"r5r>r4s7777r4c \P!W4p\P!V4p\VPP 44pV'd\ P!W4pVeV#Vf\P!WVR7V#VPPW4VP;P^, un VPPWVPP4VPPW4pV'gV#VP P#V4pVPP%W4pVfTMTp VP'4FwrW8gp V 'gW+9dK\)WRR7.p M\)WRR7\)WRR7.p \+V \,P.R7p\0P2!W4V 'gK}\P4!W W4K V#)zIRun the decision phase for ``next_package``. Return next changed package.) had_pendingTrF)r)rrCabsorb_pending_clausesrrrvr force_targeted_backtrackrecord_no_versionsrrrirrdecision_levelrQr singletonrzrrrr DEPENDENCYradd_incompatibilityabsorb_redundant_requirement)rBrchosen_versionr" force_targetsr dependencies exact_rangewidened parent_rangedependency_packagedependency_range cross_packagerrs&& r5r Resolver._decide_next4s..tB33D9 T]]JJLM !::4OJ%!!  !  % %dk R  \: ! !! $--*F*F }}55lS  oo//? --..|L&-o{7 4@4F4F4H 0 .>M "5l$GHdC+N.1<<O  . .t E}33.>-5I2r4cV^8dQhRR/#)r8r<rr,)r=s"r5r>rms = =A =r4c \VPP4VPVPP \ R7wrp\WVR7#)zBuild the final result, including only reachable packages. Per the PubGrub spec, the solution must not contain extra packages: "all selected packages are transitively reachable from the root." ) root_sentinel)r)r*r+)rrrirrrQrr%)rBr)r*r+s& r5r Resolver._build_resultmsK 1 MM # # %  " " MM * *  U Te<r{s$$L$ $r4c VPP4VPP4VPP4\ VP R7Vn\4VnT;'g/Vn VPP4VPP4VPP4VPP4R#)z(Reset solver state for a new resolution.rN)rclearrrrrrr$rrrrrr)rBrs&&r5rResolver._reset{s $$& ))//1 ##%'4??C "_ &,," %%' ''--/ !!# !!#r4c V^8dQhRRRR/#)r8rrr<rUr,)r=s"r5r>rs""O" "r4c  >\V4Fwr#\\VPP VP 4RR7p\ P!V\V\VPVPRR7.\PVPR74VPPVP^VR34K VPP!\VP 4VP";P$^, unR#)zACreate one root incompatibility per requirement, and decide root.Tr#F)roriginN) enumeraterrrr(rrr*rr9r~rr@r setdefaultrrrri)rBridxroot root_terms&& r5rResolver._add_root_requirementss#<0IC(,doo//0A0ABT)I  . .T\\4??U ST.33;;   # # . .t||ab\ J1 T4#4#45 !r4)rrrrrrrrrrrrrrrrr)r-r.r/r0r1rrCULPRIT_THRESHOLDTARGETED_BT_MIN_CONFLICTSMAX_TARGETED_BACKTRACKSDEFAULT_MAX_ITERATIONSrstrrrrr r r rrr3r,r4r5r!r!slM  "  GK4/4-09v :90vF07r =$"""r4N)rKr rrrrr!r"r#r$rrr%r)6r1 __future__r collectionsrcollections.abcrrr dataclassesrrtypingr r r r rAr rrrerrorsrpartial_solutionrrangesrresultrrErtypesrrrrrrrrrtyping_extensionsr__all__rKr%r#r r$r"rrr!r,r4r5rYs(##77(8899#-'   ( "! $ #w{K/0 # #N x [ 89N b37; 343l GK( 0-Dw{K78-D` 1 \"w{K/0\"r4