1class AbstractProvider(object): 2 """Delegate class to provide requirement interface for the resolver.""" 3 4 def identify(self, requirement_or_candidate): 5 """Given a requirement, return an identifier for it. 6 7 This is used to identify a requirement, e.g. whether two requirements 8 should have their specifier parts merged. 9 """ 10 raise NotImplementedError 11 12 def get_preference(self, identifier, resolutions, candidates, information): 13 """Produce a sort key for given requirement based on preference. 14 15 The preference is defined as "I think this requirement should be 16 resolved first". The lower the return value is, the more preferred 17 this group of arguments is. 18 19 :param identifier: An identifier as returned by ``identify()``. This 20 identifies the dependency matches of which should be returned. 21 :param resolutions: Mapping of candidates currently pinned by the 22 resolver. Each key is an identifier, and the value a candidate. 23 The candidate may conflict with requirements from ``information``. 24 :param candidates: Mapping of each dependency's possible candidates. 25 Each value is an iterator of candidates. 26 :param information: Mapping of requirement information of each package. 27 Each value is an iterator of *requirement information*. 28 29 A *requirement information* instance is a named tuple with two members: 30 31 * ``requirement`` specifies a requirement contributing to the current 32 list of candidates. 33 * ``parent`` specifies the candidate that provides (dependend on) the 34 requirement, or ``None`` to indicate a root requirement. 35 36 The preference could depend on a various of issues, including (not 37 necessarily in this order): 38 39 * Is this package pinned in the current resolution result? 40 * How relaxed is the requirement? Stricter ones should probably be 41 worked on first? (I don't know, actually.) 42 * How many possibilities are there to satisfy this requirement? Those 43 with few left should likely be worked on first, I guess? 44 * Are there any known conflicts for this requirement? We should 45 probably work on those with the most known conflicts. 46 47 A sortable value should be returned (this will be used as the ``key`` 48 parameter of the built-in sorting function). The smaller the value is, 49 the more preferred this requirement is (i.e. the sorting function 50 is called with ``reverse=False``). 51 """ 52 raise NotImplementedError 53 54 def find_matches(self, identifier, requirements, incompatibilities): 55 """Find all possible candidates that satisfy given constraints. 56 57 :param identifier: An identifier as returned by ``identify()``. This 58 identifies the dependency matches of which should be returned. 59 :param requirements: A mapping of requirements that all returned 60 candidates must satisfy. Each key is an identifier, and the value 61 an iterator of requirements for that dependency. 62 :param incompatibilities: A mapping of known incompatibilities of 63 each dependency. Each key is an identifier, and the value an 64 iterator of incompatibilities known to the resolver. All 65 incompatibilities *must* be excluded from the return value. 66 67 This should try to get candidates based on the requirements' types. 68 For VCS, local, and archive requirements, the one-and-only match is 69 returned, and for a "named" requirement, the index(es) should be 70 consulted to find concrete candidates for this requirement. 71 72 The return value should produce candidates ordered by preference; the 73 most preferred candidate should come first. The return type may be one 74 of the following: 75 76 * A callable that returns an iterator that yields candidates. 77 * An collection of candidates. 78 * An iterable of candidates. This will be consumed immediately into a 79 list of candidates. 80 """ 81 raise NotImplementedError 82 83 def is_satisfied_by(self, requirement, candidate): 84 """Whether the given requirement can be satisfied by a candidate. 85 86 The candidate is guarenteed to have been generated from the 87 requirement. 88 89 A boolean should be returned to indicate whether ``candidate`` is a 90 viable solution to the requirement. 91 """ 92 raise NotImplementedError 93 94 def get_dependencies(self, candidate): 95 """Get dependencies of a candidate. 96 97 This should return a collection of requirements that `candidate` 98 specifies as its dependencies. 99 """ 100 raise NotImplementedError 101 102 103class AbstractResolver(object): 104 """The thing that performs the actual resolution work.""" 105 106 base_exception = Exception 107 108 def __init__(self, provider, reporter): 109 self.provider = provider 110 self.reporter = reporter 111 112 def resolve(self, requirements, **kwargs): 113 """Take a collection of constraints, spit out the resolution result. 114 115 This returns a representation of the final resolution state, with one 116 guarenteed attribute ``mapping`` that contains resolved candidates as 117 values. The keys are their respective identifiers. 118 119 :param requirements: A collection of constraints. 120 :param kwargs: Additional keyword arguments that subclasses may accept. 121 122 :raises: ``self.base_exception`` or its subclass. 123 """ 124 raise NotImplementedError 125