feat(finders): add PyPICacheProvider for cache server lookups

Add a dedicated PyPICacheProvider that wraps PyPIProvider with a
simplified interface for Fromager's local PyPI-compatible cache server.
This makes it explicit that packages are coming from a cache server
rather than an upstream index, and eliminates cache-irrelevant options
like ignore_platform, override_download_url, cooldown, and
supports_upload_time.

The provider enforces that include_wheels and include_sdists are
mutually exclusive and defaults to wheels only.

Use PyPICacheProvider in _download_wheel_from_cache to replace the
direct PyPIProvider instantiation.

Co-Authored-By: Claude <claude@anthropic.com>
Signed-off-by: Christian Heimes <cheimes@redhat.com>

Author: tiran

src/fromager/bootstrapper.py

@@ -907,13 +907,9 @@ def _download_wheel_from_cache(
             f"checking if wheel was already uploaded to {self.cache_wheel_server_url}"
         )
         try:
-            # Use PyPIProvider directly for cache lookups, bypassing resolver
-            # hooks. Cache servers are always simple PyPI index servers.
             pinned_req = Requirement(f"{req.name}=={resolved_version}")
-            provider = resolver.PyPIProvider(
-                sdist_server_url=self.cache_wheel_server_url,
-                include_sdists=False,
-                include_wheels=True,
+            provider = finders.PyPICacheProvider(
+                cache_server_url=self.cache_wheel_server_url,
                 constraints=self.ctx.constraints,
             )
             results = resolver.find_all_matching_from_provider(provider, pinned_req)

src/fromager/finders.py

@@ -8,14 +8,64 @@
 from packaging.requirements import Requirement
 from packaging.utils import BuildTag, canonicalize_name
 
-from . import overrides
+from . import overrides, resolver
+from .constraints import Constraints
+from .requirements_file import RequirementType
 
 if typing.TYPE_CHECKING:
     from . import context
 
 logger = logging.getLogger(__name__)
 
 
+class PyPICacheProvider(resolver.PyPIProvider):
+    """Provider for Fromager's PyPI-compatible cache server.
+
+    Wraps ``PyPIProvider`` with a simplified interface tailored for cache
+    usage: no ``ignore_platform``, no ``override_download_url``, no
+    ``supports_upload_time``, and ``cooldown`` is always ``None``.
+
+    ``include_wheels`` and ``include_sdists`` are mutually exclusive;
+    exactly one must be ``True``.  Defaults to wheels only.
+
+    .. caution::
+       Only use the ``PyPICacheProvider`` with an internal and fully-trusted
+       cache index. Packages are not subject to cooldown or other checks.
+    """
+
+    provider_description: typing.ClassVar[str] = (
+        "PyPI cache resolver (searching at {self.sdist_server_url})"
+    )
+
+    def __init__(
+        self,
+        *,
+        cache_server_url: str,
+        include_sdists: bool = False,
+        include_wheels: bool = True,
+        constraints: Constraints | None = None,
+        req_type: RequirementType | None = None,
+        use_resolver_cache: bool = True,
+    ):
+        if include_sdists == include_wheels:
+            raise ValueError(
+                "include_sdists and include_wheels are mutually exclusive, "
+                "exactly one must be True"
+            )
+        super().__init__(
+            include_sdists=include_sdists,
+            include_wheels=include_wheels,
+            sdist_server_url=cache_server_url,
+            constraints=constraints,
+            req_type=req_type,
+            ignore_platform=False,
+            use_resolver_cache=use_resolver_cache,
+            override_download_url=None,
+            cooldown=None,
+            supports_upload_time=False,
+        )
+
+
 def _dist_name_to_filename(dist_name: str) -> str:
     """Transform the dist name into a prefix for a filename.
 

tests/test_bootstrapper.py

@@ -376,18 +376,18 @@ def mock_dispatch(item: bootstrapper.WorkItem) -> list[bootstrapper.WorkItem]:
 
 
 @patch("fromager.resolver.find_all_matching_from_provider")
-@patch("fromager.resolver.PyPIProvider")
+@patch("fromager.finders.PyPICacheProvider")
 def test_download_wheel_from_cache_bypasses_hooks(
-    mock_pypi_provider: Mock,
+    mock_cache_provider: Mock,
     mock_find_all: Mock,
     tmp_context: WorkContext,
 ) -> None:
-    """Verify _download_wheel_from_cache uses PyPIProvider directly, not hooks."""
+    """Verify _download_wheel_from_cache uses PyPICacheProvider, not hooks."""
     bt = bootstrapper.Bootstrapper(tmp_context)
-    bt.cache_wheel_server_url = "https://cache.example.com/simple/"
+    bt.cache_wheel_server_url = "https://cache.test/simple/"
 
     mock_provider = Mock()
-    mock_pypi_provider.return_value = mock_provider
+    mock_cache_provider.return_value = mock_provider
     # Raise so the except clause returns (None, None) before hitting
     # network calls later in the function.
     mock_find_all.side_effect = RuntimeError("no match")
@@ -403,11 +403,9 @@ def test_download_wheel_from_cache_bypasses_hooks(
     # Hook system must NOT be called for cache lookups
     mock_override.assert_not_called()
 
-    # PyPIProvider must be instantiated directly
-    mock_pypi_provider.assert_called_once_with(
-        sdist_server_url="https://cache.example.com/simple/",
-        include_sdists=False,
-        include_wheels=True,
+    # PyPICacheProvider must be instantiated directly
+    mock_cache_provider.assert_called_once_with(
+        cache_server_url="https://cache.test/simple/",
         constraints=tmp_context.constraints,
     )
     mock_find_all.assert_called_once_with(mock_provider, Requirement("test-pkg==1.0.0"))

tests/test_finders.py

@@ -4,6 +4,7 @@
 from packaging.requirements import Requirement
 
 from fromager import context, finders
+from fromager.requirements_file import RequirementType
 
 
 @pytest.mark.parametrize(
@@ -110,3 +111,38 @@ def test_find_source_dir(
     req = Requirement(dist_name)
     actual = finders.find_source_dir(tmp_context, work_dir, req, version_string)
     assert str(source_dir) == str(actual)
+
+
+def test_pypi_cache_provider() -> None:
+    url = "https://cache.test/simple/"
+
+    # defaults: wheels only, hardcoded attributes
+    provider = finders.PyPICacheProvider(cache_server_url=url)
+    assert provider.sdist_server_url == url
+    assert provider.include_sdists is False
+    assert provider.include_wheels is True
+    assert provider.ignore_platform is False
+    assert provider.override_download_url is None
+    assert provider.cooldown is None
+    assert provider.supports_upload_time is False
+
+    # sdists only with req_type
+    provider = finders.PyPICacheProvider(
+        cache_server_url=url,
+        include_sdists=True,
+        include_wheels=False,
+        req_type=RequirementType.TOP_LEVEL,
+    )
+    assert provider.include_sdists is True
+    assert provider.include_wheels is False
+    assert provider.req_type == RequirementType.TOP_LEVEL
+
+    # mutually exclusive: both True or both False
+    with pytest.raises(ValueError, match="mutually exclusive"):
+        finders.PyPICacheProvider(
+            cache_server_url=url, include_sdists=True, include_wheels=True
+        )
+    with pytest.raises(ValueError, match="mutually exclusive"):
+        finders.PyPICacheProvider(
+            cache_server_url=url, include_sdists=False, include_wheels=False
+        )