Remove stubs and update docs now narrow_requirement_selection is op…

…tional and provides a default resolution

examples/extras_provider.py

@@ -52,13 +52,3 @@ def get_dependencies(self, candidate):
             req = self.get_base_requirement(candidate)
             deps.append(req)
         return deps
-
-    def narrow_requirement_selection(
-        self,
-        identifiers,
-        resolutions,
-        candidates,
-        information,
-        backtrack_causes,
-    ):
-        return identifiers

examples/reporter_demo.py

@@ -101,16 +101,6 @@ def is_satisfied_by(self, requirement, candidate):
     def get_dependencies(self, candidate):
         return self.candidates[candidate]
 
-    def narrow_requirement_selection(
-        self,
-        identifiers,
-        resolutions,
-        candidates,
-        information,
-        backtrack_causes,
-    ):
-        return identifiers
-
 
 class Reporter(resolvelib.BaseReporter):
     def starting(self):

src/resolvelib/providers.py

@@ -146,48 +146,48 @@ def narrow_requirement_selection(
         backtrack_causes: Sequence[RequirementInformation[RT, CT]],
     ) -> Iterable[KT]:
         """
-        Narrows the selection of requirements being considered during
-        resolution.
+        An optional method to narrow the selection of requirements being
+        considered during resolution.
 
         The requirement selection is defined as "The possible requirements
-        that will be resolved next." If a requirement isn't part of the returned
+        that will be resolved next." If a requirement is not part of the returned
         iterable, it will not be considered during the next step of resolution.
 
-        :param identifiers: An iterable of `identifier` as returned by
+        :param identifiers: An iterable of `identifiers` as returned by
             ``identify()``. These identify all requirements currently being
             considered.
-        :param resolutions: Mapping of candidates currently pinned by the
-            resolver. Each key is an identifier, and the value is a candidate.
-            The candidate may conflict with requirements from ``information``.
-        :param candidates: Mapping of each dependency's possible candidates.
+        :param resolutions: A mapping of candidates currently pinned by the
+            resolver. Each key is an identifier, and the value is a candidate
+            that may conflict with requirements from ``information``.
+        :param candidates: A mapping of each dependency's possible candidates.
             Each value is an iterator of candidates.
-        :param information: Mapping of requirement information of each package.
+        :param information: A mapping of requirement information for each package.
             Each value is an iterator of *requirement information*.
-        :param backtrack_causes: Sequence of *requirement information* that are
-            the requirements that caused the resolver to most recently
+        :param backtrack_causes: A sequence of *requirement information* that are
+            the requirements causing the resolver to most recently
             backtrack.
 
         A *requirement information* instance is a named tuple with two members:
 
         * ``requirement`` specifies a requirement contributing to the current
           list of candidates.
-        * ``parent`` specifies the candidate that provides (depended on) the
-          requirement, or ``None`` to indicate a root requirement.
+        * ``parent`` specifies the candidate that provides (is depended on for)
+          the requirement, or ``None`` to indicate a root requirement.
 
-        Must return a non-empty subset of `identifiers`, with the simplest
+        Must return a non-empty subset of `identifiers`, with the default
         implementation being to return `identifiers` unchanged.
 
         Can be used by the provider to optimize the dependency resolution
-        process. `get_preference` will only be called on the identifiers
+        process. `get_preference` will only be called for the identifiers
         returned. If there is only one identifier returned, then `get_preference`
         won't be called at all.
 
         Serving a similar purpose as `get_preference`, this method allows the
         provider to guide resolvelib through the resolution process. It should
-        be used instead of `get_preference` when the provider needs to consider
-        multiple identifiers simultaneously, or when the provider wants to skip
-        checking all identifiers, e.g., because the checks are prohibitively
-        expensive.
+        be used instead of `get_preference` for logic when the provider needs
+        to consider multiple identifiers simultaneously, or when the provider
+        wants to skip checking all identifiers, e.g., because the checks are
+        prohibitively expensive.
 
         Returns:
             Iterable[KT]: A non-empty subset of `identifiers`.

tests/functional/cocoapods/test_resolvers_cocoapods.py

@@ -222,16 +222,6 @@ def is_satisfied_by(self, requirement, candidate):
     def get_dependencies(self, candidate):
         return candidate.deps
 
-    def narrow_requirement_selection(
-        self,
-        identifiers,
-        resolutions,
-        candidates,
-        information,
-        backtrack_causes,
-    ):
-        return identifiers
-
 
 XFAIL_CASES = {
     # ResolveLib does not complain about cycles, so these will be different.

tests/functional/python/test_resolvers_python.py

@@ -119,15 +119,6 @@ def _iter_dependencies(self, candidate):
     def get_dependencies(self, candidate):
         return list(self._iter_dependencies(candidate))
 
-    def narrow_requirement_selection(
-        self,
-        identifiers,
-        resolutions,
-        candidates,
-        information,
-        backtrack_causes,
-    ):
-        return identifiers
 
 
 INPUTS_DIR = os.path.abspath(os.path.join(__file__, "..", "inputs"))

tests/functional/swift-package-manager/test_resolvers_swift.py

@@ -132,17 +132,6 @@ def _iter_dependencies(self, candidate):
     def get_dependencies(self, candidate):
         return list(self._iter_dependencies(candidate))
 
-    def narrow_requirement_selection(
-        self,
-        identifiers,
-        resolutions,
-        candidates,
-        information,
-        backtrack_causes,
-    ):
-        return identifiers
-
-
 @pytest.fixture(
     params=[os.path.join(INPUTS_DIR, n) for n in INPUT_NAMES],
     ids=[n[:-5] for n in INPUT_NAMES],

tests/test_resolvers.py

@@ -58,9 +58,6 @@ def is_satisfied_by(self, requirement, candidate):
             assert candidate is self.candidate
             return False
 
-        def narrow_requirement_selection(self, identifiers, **_):
-            return identifiers
-
     resolver = Resolver(Provider(requirement, candidate), BaseReporter())
 
     with pytest.raises(InconsistentCandidate) as ctx:
@@ -107,9 +104,6 @@ def find_matches(self, identifier, requirements, incompatibilities):
         def is_satisfied_by(self, requirement, candidate):
             return candidate[1] in requirement[1]
 
-        def narrow_requirement_selection(self, identifiers, **_):
-            return identifiers
-
     # Now when resolved, both requirements to child specified by parent should
     # be pulled, and the resolver should choose v1, not v2 (happens if the
     # v1-only requirement is dropped).
@@ -170,9 +164,6 @@ def find_matches(self, identifier, requirements, incompatibilities):
         def is_satisfied_by(self, requirement, candidate):
             return candidate.version in requirement.versions
 
-        def narrow_requirement_selection(self, identifiers, **_):
-            return identifiers
-
     def run_resolver(*args):
         reporter = Reporter()
         resolver = Resolver(Provider(), reporter)
@@ -252,9 +243,6 @@ def is_satisfied_by(
         ) -> bool:
             return candidate[1] in Requirement(requirement).specifier
 
-        def narrow_requirement_selection(self, identifiers, **_):
-            return identifiers
-
     # patch Resolution._get_updated_criteria to collect rejected states
     rejected_criteria: list[Criterion] = []
     get_updated_criteria_orig = (