fix(bootstrapper): log specific error types in wheel cache lookup

Replace bare `except Exception` in `_download_wheel_from_cache()` with
three handlers so logs distinguish why a cache lookup failed:
- ResolverException → INFO (wheel not found)
- RequestException → WARNING (network error)
- Exception → WARNING (unexpected error, e.g. bad wheel file, I/O)

All three still return (None, None) to preserve existing behavior.

Closes: #1025
Co-Authored-By: Claude <claude@anthropic.com>
Signed-off-by: Lalatendu Mohanty <lmohanty@redhat.com>

Author: LalatenduMohanty

src/fromager/bootstrapper.py

@@ -14,9 +14,11 @@
 import zipfile
 from urllib.parse import urlparse
 
+import requests.exceptions
 from packaging.requirements import Requirement
 from packaging.utils import NormalizedName, canonicalize_name
 from packaging.version import Version
+from resolvelib.resolvers import ResolverException
 
 from . import (
     bootstrap_requirement_resolver,
@@ -1051,11 +1053,23 @@ def _download_wheel_from_cache(
                 req, resolved_version, cached_wheel
             )
             return cached_wheel, unpack_dir
-        except Exception:
+        except ResolverException:
             logger.info(
                 f"did not find wheel for {resolved_version} in {self.cache_wheel_server_url}"
             )
             return None, None
+        except requests.exceptions.RequestException as err:
+            logger.warning(
+                f"network error checking wheel cache for {resolved_version} "
+                f"at {self.cache_wheel_server_url}: {err}"
+            )
+            return None, None
+        except Exception as err:
+            logger.warning(
+                f"unexpected error checking wheel cache for {resolved_version} "
+                f"at {self.cache_wheel_server_url}: {err}"
+            )
+            return None, None
 
     def _unpack_metadata_from_wheel(
         self, req: Requirement, resolved_version: Version, wheel_filename: pathlib.Path

tests/test_bootstrapper.py

@@ -1,9 +1,13 @@
 import json
+import logging
 import pathlib
 from unittest.mock import Mock, patch
 
+import pytest
+import requests.exceptions
 from packaging.requirements import Requirement
 from packaging.version import Version
+from resolvelib.resolvers import ResolverException
 
 from fromager import bootstrapper, requirements_file
 from fromager.context import WorkContext
@@ -293,3 +297,175 @@ def test_build_from_source_returns_dataclass(tmp_context: WorkContext) -> None:
         assert result.sdist_root_dir == mock_sdist_root
         assert result.build_env is not None
         assert result.source_type == SourceType.SDIST
+
+
+class TestDownloadWheelFromCacheErrorHandling:
+    """Tests for _download_wheel_from_cache exception differentiation."""
+
+    def test_resolver_exception_returns_none(
+        self, tmp_context: WorkContext, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        """ResolverException (wheel not found) returns (None, None) and logs info."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        bt.cache_wheel_server_url = "https://cache.example.com/simple"
+
+        with patch(
+            "fromager.resolver.resolve",
+            side_effect=ResolverException("no matching version"),
+        ):
+            result = bt._download_wheel_from_cache(
+                req=Requirement("test-package"),
+                resolved_version=Version("1.0.0"),
+            )
+
+        assert result == (None, None)
+        log_record = next(
+            r for r in caplog.records if "did not find wheel for" in r.message
+        )
+        assert log_record.levelno == logging.INFO
+
+    @pytest.mark.parametrize(
+        "exc_class,exc_msg",
+        [
+            (requests.exceptions.ConnectionError, "DNS failure"),
+            (requests.exceptions.Timeout, "timed out"),
+            (requests.exceptions.HTTPError, "401 Unauthorized"),
+        ],
+    )
+    def test_request_exception_returns_none_with_warning(
+        self,
+        tmp_context: WorkContext,
+        caplog: pytest.LogCaptureFixture,
+        exc_class: type[Exception],
+        exc_msg: str,
+    ) -> None:
+        """RequestException subtypes return (None, None) and log warning."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        bt.cache_wheel_server_url = "https://cache.example.com/simple"
+
+        with patch(
+            "fromager.resolver.resolve",
+            side_effect=exc_class(exc_msg),
+        ):
+            result = bt._download_wheel_from_cache(
+                req=Requirement("test-package"),
+                resolved_version=Version("1.0.0"),
+            )
+
+        assert result == (None, None)
+        log_record = next(
+            r
+            for r in caplog.records
+            if "network error checking wheel cache" in r.message
+        )
+        assert log_record.levelno == logging.WARNING
+
+    def test_unexpected_exception_returns_none_with_warning(
+        self, tmp_context: WorkContext, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        """Unexpected exceptions (e.g. ValueError, OSError) return (None, None) and log warning."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        bt.cache_wheel_server_url = "https://cache.example.com/simple"
+
+        with patch(
+            "fromager.resolver.resolve",
+            side_effect=ValueError("unexpected parsing error"),
+        ):
+            result = bt._download_wheel_from_cache(
+                req=Requirement("test-package"),
+                resolved_version=Version("1.0.0"),
+            )
+
+        assert result == (None, None)
+        log_record = next(
+            r
+            for r in caplog.records
+            if "unexpected error checking wheel cache" in r.message
+        )
+        assert log_record.levelno == logging.WARNING
+
+    def test_download_wheel_network_error_returns_none_with_warning(
+        self, tmp_context: WorkContext, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        """RequestException from download_wheel (after resolve succeeds) is caught."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        bt.cache_wheel_server_url = "https://cache.example.com/simple"
+
+        with (
+            patch(
+                "fromager.resolver.resolve",
+                return_value=(
+                    "https://cache.example.com/simple/test-package/test_package-1.0.0-py3-none-any.whl",
+                    "1.0.0",
+                ),
+            ),
+            patch(
+                "fromager.bootstrapper.wheels.extract_info_from_wheel_file",
+                return_value=("test_package", "1.0.0", None, None),
+            ),
+            patch(
+                "fromager.bootstrapper.wheels.download_wheel",
+                side_effect=requests.exceptions.ConnectionError("connection reset"),
+            ),
+        ):
+            result = bt._download_wheel_from_cache(
+                req=Requirement("test-package"),
+                resolved_version=Version("1.0.0"),
+            )
+
+        assert result == (None, None)
+        log_record = next(
+            r
+            for r in caplog.records
+            if "network error checking wheel cache" in r.message
+        )
+        assert log_record.levelno == logging.WARNING
+
+    def test_download_wheel_unexpected_error_returns_none_with_warning(
+        self, tmp_context: WorkContext, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        """Unexpected exception from download_wheel (after resolve succeeds) is caught."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        bt.cache_wheel_server_url = "https://cache.example.com/simple"
+
+        with (
+            patch(
+                "fromager.resolver.resolve",
+                return_value=(
+                    "https://cache.example.com/simple/test-package/test_package-1.0.0-py3-none-any.whl",
+                    "1.0.0",
+                ),
+            ),
+            patch(
+                "fromager.bootstrapper.wheels.extract_info_from_wheel_file",
+                return_value=("test_package", "1.0.0", None, None),
+            ),
+            patch(
+                "fromager.bootstrapper.wheels.download_wheel",
+                side_effect=OSError("disk full"),
+            ),
+        ):
+            result = bt._download_wheel_from_cache(
+                req=Requirement("test-package"),
+                resolved_version=Version("1.0.0"),
+            )
+
+        assert result == (None, None)
+        log_record = next(
+            r
+            for r in caplog.records
+            if "unexpected error checking wheel cache" in r.message
+        )
+        assert log_record.levelno == logging.WARNING
+
+    def test_no_cache_url_returns_none(self, tmp_context: WorkContext) -> None:
+        """When no cache URL is configured, returns (None, None) immediately."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        bt.cache_wheel_server_url = ""
+
+        result = bt._download_wheel_from_cache(
+            req=Requirement("test-package"),
+            resolved_version=Version("1.0.0"),
+        )
+
+        assert result == (None, None)