Merge pull request #975 from rd4398/resolver-return-multiple-values

refactor(resolver): return lists of matching versions

Author: LalatenduMohanty

docs/customization.md

@@ -90,7 +90,7 @@ source url can be provided directly in settings.yaml. Optionally the
 downloaded sdist can be renamed. Both the url and the destination filename
 support templating. The only supported template variable are:
 
-- `version` - it is replaced by the version returned by the `resolve_source`
+- `version` - it is replaced by the resolved version of the package
 - `canonicalized_name` - it is replaced by the canonicalized name of the
   package specified in the requirement, specifically it applies `canonicalize_name(req.nam)`
 

docs/reference/hooks.rst

@@ -191,27 +191,13 @@ Source hooks
 
 .. currentmodule:: fromager.sources
 
-.. autofromagerhook:: default_resolve_source
-
-    The ``resolve_source()`` function is responsible for resolving a
-    requirement and acquiring the source for that version of a
-    package. The default is to use pypi.org to resolve the requirement.
-
-    The arguments are the ``WorkContext``, the ``Requirement`` being
-    evaluated, and the URL to the sdist index.
-
-    The return value is ``Tuple[str, Version]`` where the first member is
-    the url from which the source can be downloaded and the second member
-    is the version of the resolved package.
-
 .. autofromagerhook:: default_download_source
 
     The ``download_source()`` function is responsible for downloading the
     source from a URL.
 
     The arguments are the ``WorkContext``, the ``Requirement`` being
-    evaluated, version of the package being downloaded, the URL
-    from which the source can be downloaded as returned by ``resolve_source``,
+    evaluated, version of the package being downloaded, the download URL,
     and the output directory in which the source should be downloaded.
 
     The return value should be a ``pathlib.Path`` file path to the downloaded source.

pyproject.toml

@@ -101,7 +101,6 @@ get_build_backend_dependencies = "fromager.dependencies:default_get_build_backen
 get_build_sdist_dependencies = "fromager.dependencies:default_get_build_sdist_dependencies"
 resolver_provider = "fromager.resolver:default_resolver_provider"
 download_source = "fromager.sources:default_download_source"
-resolve_source = "fromager.sources:default_resolve_source"
 build_sdist = "fromager.sources:default_build_sdist"
 build_wheel = "fromager.wheels:default_build_wheel"
 

src/fromager/requirement_resolver.py …omager/bootstrap_requirement_resolver.pysrc/fromager/requirement_resolver.py renamed to src/fromager/bootstrap_requirement_resolver.py src/fromager/requirement_resolver.py renamed to src/fromager/bootstrap_requirement_resolver.py

@@ -22,10 +22,10 @@
 logger = logging.getLogger(__name__)
 
 
-class RequirementResolver:
-    """Resolve package requirements from PyPI or dependency graph.
+class BootstrapRequirementResolver:
+    """Resolve package requirements from PyPI or dependency graph during bootstrap.
 
-    Single Responsibility: Coordinate resolution strategies.
+    Single Responsibility: Coordinate resolution strategies for bootstrap process.
     Reason to Change: Resolution algorithm or provider priorities change.
 
     Resolution strategies (in order):
@@ -51,7 +51,10 @@ def __init__(
         self.prev_graph = prev_graph
         # Session-level resolution cache to avoid re-resolving same requirements
         # Key: (requirement_string, pre_built) to distinguish source vs prebuilt
-        self._resolved_requirements: dict[tuple[str, bool], tuple[str, Version]] = {}
+        # Value: list of (url, version) tuples sorted by version (highest first)
+        self._resolved_requirements: dict[
+            tuple[str, bool], list[tuple[str, Version]]
+        ] = {}
 
     def resolve(
         self,
@@ -60,7 +63,7 @@ def resolve(
         parent_req: Requirement | None = None,
         pre_built: bool | None = None,
     ) -> tuple[str, Version]:
-        """Resolve package requirement.
+        """Resolve package requirement to the best matching version.
 
         Tries resolution strategies in order:
         1. Session cache (if previously resolved)
@@ -75,7 +78,7 @@ def resolve(
                 If None (default), uses package build info to determine.
 
         Returns:
-            Tuple of (url, resolved_version)
+            (url, version) tuple for the highest matching version
 
         Raises:
             ValueError: If req contains a git URL and pre_built is False
@@ -98,23 +101,22 @@ def resolve(
         cached_result = self.get_cached_resolution(req, pre_built)
         if cached_result is not None:
             logger.debug(f"resolved {req} from cache")
-            return cached_result
+            return cached_result[0]
 
         # Resolve using strategies
-        url, resolved_version = self._resolve(req, req_type, parent_req, pre_built)
+        results = self._resolve(req, req_type, parent_req, pre_built)
 
         # Cache the result
-        result = (url, resolved_version)
-        self.cache_resolution(req, pre_built, result)
-        return url, resolved_version
+        self.cache_resolution(req, pre_built, results)
+        return results[0]
 
     def _resolve(
         self,
         req: Requirement,
         req_type: RequirementType,
         parent_req: Requirement | None,
         pre_built: bool,
-    ) -> tuple[str, Version]:
+    ) -> list[tuple[str, Version]]:
         """Internal resolution logic without caching.
 
         Tries resolution strategies in order:
@@ -128,7 +130,7 @@ def _resolve(
             pre_built: Whether to resolve prebuilt (True) or source (False)
 
         Returns:
-            Tuple of (url, resolved_version)
+            List of (url, version) tuples sorted by version (highest first)
         """
         # Try graph
         cached_resolution = self._resolve_from_graph(
@@ -139,43 +141,48 @@ def _resolve(
         )
 
         if cached_resolution and not req.url:
-            url, resolved_version = cached_resolution
-            logger.debug(f"resolved from previous bootstrap to {resolved_version}")
-            return url, resolved_version
+            logger.debug(
+                f"resolved from previous bootstrap: {len(cached_resolution)} version(s)"
+            )
+            return cached_resolution
 
-        # Fallback to PyPI
+        # Fallback to PyPI using provider pattern
         if pre_built:
             # Resolve prebuilt wheel
-            servers = wheels.get_wheel_server_urls(
+            # Get wheel server URLs (use PyPI as cache/fallback server)
+            wheel_server_urls = wheels.get_wheel_server_urls(
                 self.ctx, req, cache_wheel_server_url=resolver.PYPI_SERVER_URL
             )
-            url, resolved_version = wheels.resolve_prebuilt_wheel(
-                ctx=self.ctx, req=req, wheel_server_urls=servers, req_type=req_type
+            # Use shared retry loop logic from wheels module
+            return wheels.resolve_all_prebuilt_wheels(
+                ctx=self.ctx,
+                req=req,
+                wheel_server_urls=wheel_server_urls,
+                req_type=req_type,
             )
         else:
             # Resolve source (sdist)
-            url, resolved_version = sources.resolve_source(
+            provider = sources.get_source_provider(
                 ctx=self.ctx,
                 req=req,
                 sdist_server_url=resolver.PYPI_SERVER_URL,
                 req_type=req_type,
             )
-
-        return url, resolved_version
+            return resolver.find_all_matching_from_provider(provider, req)
 
     def get_cached_resolution(
         self,
         req: Requirement,
         pre_built: bool,
-    ) -> tuple[str, Version] | None:
+    ) -> list[tuple[str, Version]] | None:
         """Get a cached resolution result if it exists.
 
         Args:
             req: Package requirement to look up in cache
             pre_built: Whether looking for prebuilt or source resolution
 
         Returns:
-            Tuple of (source_url, resolved_version) if cached, None otherwise
+            List of (url, version) tuples if cached, None otherwise
         """
         cache_key = (str(req), pre_built)
         return self._resolved_requirements.get(cache_key)
@@ -184,7 +191,7 @@ def cache_resolution(
         self,
         req: Requirement,
         pre_built: bool,
-        result: tuple[str, Version],
+        result: list[tuple[str, Version]],
     ) -> None:
         """Cache a resolution result.
 
@@ -194,7 +201,7 @@ def cache_resolution(
         Args:
             req: Package requirement to cache
             pre_built: Whether this is a prebuilt or source resolution
-            result: Tuple of (source_url, resolved_version)
+            result: List of (url, version) tuples
         """
         cache_key = (str(req), pre_built)
         self._resolved_requirements[cache_key] = result
@@ -205,7 +212,7 @@ def _resolve_from_graph(
         req_type: RequirementType,
         pre_built: bool,
         parent_req: Requirement | None,
-    ) -> tuple[str, Version] | None:
+    ) -> list[tuple[str, Version]] | None:
         """Resolve from previous dependency graph.
 
         Extracted from Bootstrapper._resolve_from_graph().
@@ -217,7 +224,7 @@ def _resolve_from_graph(
             parent_req: Parent requirement for graph traversal
 
         Returns:
-            Tuple of (url, version) if found in graph, None otherwise
+            List of (url, version) tuples if found in graph, None otherwise
         """
         if not self.prev_graph:
             return None
@@ -307,8 +314,8 @@ def _resolve_from_version_source(
         self,
         version_source: list[tuple[str, Version]],
         req: Requirement,
-    ) -> tuple[str, Version] | None:
-        """Select best version from candidates.
+    ) -> list[tuple[str, Version]] | None:
+        """Filter and return all matching versions from candidates.
 
         Extracted from Bootstrapper._resolve_from_version_source().
 
@@ -317,7 +324,7 @@ def _resolve_from_version_source(
             req: Package requirement with version specifier
 
         Returns:
-            Tuple of (url, version) for best match, None if no match
+            List of (url, version) tuples for all matches, None if no matches
         """
         if not version_source:
             return None
@@ -329,7 +336,8 @@ def _resolve_from_version_source(
                 constraints=self.ctx.constraints,
                 use_resolver_cache=False,
             )
-            return resolver.resolve_from_provider(provider, req)
+            # find_all_matching_from_provider now returns all matching candidates
+            return resolver.find_all_matching_from_provider(provider, req)
         except Exception as err:
             logger.debug(f"could not resolve {req} from {version_source}: {err}")
             return None

src/fromager/bootstrapper.py

@@ -19,12 +19,12 @@
 from packaging.version import Version
 
 from . import (
+    bootstrap_requirement_resolver,
     build_environment,
     dependencies,
     finders,
     hooks,
     progress,
-    requirement_resolver,
     resolver,
     server,
     sources,
@@ -103,8 +103,8 @@ def __init__(
         self.test_mode = test_mode
         self.why: list[tuple[RequirementType, Requirement, Version]] = []
 
-        # Delegate resolution to RequirementResolver
-        self._resolver = requirement_resolver.RequirementResolver(
+        # Delegate resolution to BootstrapRequirementResolver
+        self._resolver = bootstrap_requirement_resolver.BootstrapRequirementResolver(
             ctx=ctx,
             prev_graph=prev_graph,
         )
@@ -176,11 +176,11 @@ def resolve_version(
     ) -> tuple[str, Version]:
         """Resolve the version of a requirement.
 
-        Returns the source URL and the version of the requirement.
+        Returns the source URL and the version of the requirement (highest matching version).
 
         Git URL resolution stays in Bootstrapper because it requires
         build orchestration (BuildEnvironment, build dependencies).
-        Delegates PyPI/graph resolution to RequirementResolver.
+        Delegates PyPI/graph resolution to BootstrapRequirementResolver.
         """
         if req.url:
             if req_type != RequirementType.TOP_LEVEL:
@@ -193,19 +193,22 @@ def resolve_version(
             cached_result = self._resolver.get_cached_resolution(req, pre_built=False)
             if cached_result is not None:
                 logger.debug(f"resolved {req} from cache")
-                return cached_result
+                # Pick highest version from cached list
+                return cached_result[0]
 
             logger.info("resolving source via URL, ignoring any plugins")
             source_url, resolved_version = self._resolve_version_from_git_url(req=req)
             # Cache the git URL resolution (always source, not prebuilt)
+            # Store as list for consistency with cache structure
             self._resolver.cache_resolution(
-                req, pre_built=False, result=(source_url, resolved_version)
+                req, pre_built=False, result=[(source_url, resolved_version)]
             )
             return source_url, resolved_version
 
         # Delegate to RequirementResolver
         parent_req = self.why[-1][1] if self.why else None
 
+        # Returns the highest matching version
         return self._resolver.resolve(
             req=req,
             req_type=req_type,

src/fromager/commands/list_overrides.py

@@ -77,7 +77,6 @@ def list_overrides(
                 "prebuilt_wheel",
                 # from overrides.py, found by searching for find_override_method
                 "download_source",
-                "resolve_source",
                 "get_resolver_provider",
                 "prepare_source",
                 "build_sdist",