refactor(bootstrapper): apply review follow-ups to _cache module

Add docstring to `Bootstrapper` class describing it as an iterative DFS
engine to be used as a context manager.

Rename private `_cache` functions that cross module boundaries to drop
the leading underscore, reflecting their role as internal-but-public
APIs within the bootstrapper package:

- `_find_cached_wheel` → `find_cached_wheel`
- `_bg_prepare_prebuilt` → `bg_prepare_prebuilt`

Update all call sites in `_bootstrapper.py`, `_prepare_source.py`,
`_resolve.py`, and tests.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Doug Hellmann <dhellmann@redhat.com>

Author: dhellmann

src/fromager/bootstrapper/_bootstrapper.py

@@ -49,6 +49,12 @@
 
 
 class Bootstrapper:
+    """Iterative DFS bootstrap engine for resolving and building packages.
+
+    Use as a context manager. Call ``bootstrap(requirements)`` to process
+    the dependency tree, then ``finalize()`` for cleanup and exit code.
+    """
+
     def __init__(
         self,
         ctx: context.WorkContext,
@@ -555,7 +561,7 @@ def _download_prebuilt(
         resolved_version: Version,
         wheel_url: str,
     ) -> tuple[pathlib.Path, pathlib.Path]:
-        result = _cache._bg_prepare_prebuilt(
+        result = _cache.bg_prepare_prebuilt(
             self.ctx, req, req_type, resolved_version, wheel_url
         )
         assert result.wheel_filename is not None

src/fromager/bootstrapper/_cache.py

@@ -171,7 +171,7 @@ def _download_wheel_from_cache(
         return None, None
 
 
-def _find_cached_wheel(
+def find_cached_wheel(
     ctx: context.WorkContext,
     cache_wheel_server_url: str | None,
     req: Requirement,
@@ -209,7 +209,7 @@ def _find_cached_wheel(
     return None, None
 
 
-def _bg_prepare_prebuilt(
+def bg_prepare_prebuilt(
     ctx: context.WorkContext,
     req: Requirement,
     req_type: RequirementType,

src/fromager/bootstrapper/_prepare_source.py

@@ -35,7 +35,7 @@ def _bg_prepare_source(
     # Paths from download_source() and prepare_source() include {name}-{version},
     # making them unique across concurrent threads processing different packages.
     logger.info("preparing source")
-    cached_wheel, unpacked = _cache._find_cached_wheel(
+    cached_wheel, unpacked = _cache.find_cached_wheel(
         ctx, cache_wheel_server_url, req, resolved_version
     )
     if unpacked is not None:
@@ -87,7 +87,7 @@ def background_work(
 
             def do_prepare_prebuilt() -> PreparedSourceData:
                 with req_ctxvar_context(req, resolved_version):
-                    return _cache._bg_prepare_prebuilt(
+                    return _cache.bg_prepare_prebuilt(
                         ctx, req, req_type, resolved_version, source_url
                     )
 

src/fromager/bootstrapper/_resolve.py

@@ -112,7 +112,7 @@ def run(self, bt: Bootstrapper) -> list[Phase]:
             )
             filtered: list[tuple[str, Version]] = []
             for source_url, version in resolved_versions:
-                cached_wheel, _ = _cache._find_cached_wheel(
+                cached_wheel, _ = _cache.find_cached_wheel(
                     bt.ctx, bt.cache_wheel_server_url, self.work_item.req, version
                 )
                 if cached_wheel:

tests/test_bootstrapper.py

@@ -14,9 +14,9 @@
 from fromager import bootstrapper, log
 from fromager.bootstrapper._build import Build
 from fromager.bootstrapper._cache import (
-    _bg_prepare_prebuilt,
     _download_wheel_from_cache,
-    _find_cached_wheel,
+    bg_prepare_prebuilt,
+    find_cached_wheel,
 )
 from fromager.bootstrapper._phase import Phase
 from fromager.bootstrapper._prepare_source import (
@@ -292,11 +292,11 @@ def test_is_build_requirement(tmp_context: WorkContext) -> None:
 
 
 def test_find_cached_wheel_returns_tuple(tmp_context: WorkContext) -> None:
-    """Verify _find_cached_wheel returns tuple of (Path|None, Path|None)."""
+    """Verify `find_cached_wheel` returns tuple of (Path|None, Path|None)."""
     bt = bootstrapper.Bootstrapper(tmp_context)
 
     # Call method (will return None, None since no wheels exist)
-    result = _find_cached_wheel(
+    result = find_cached_wheel(
         bt.ctx,
         bt.cache_wheel_server_url,
         req=Requirement("test-package"),
@@ -897,7 +897,7 @@ def test_bg_prepare_source_log_prefix_includes_version(
         with (
             caplog.at_level(logging.INFO, logger="fromager.bootstrapper"),
             patch(
-                "fromager.bootstrapper._cache._find_cached_wheel",
+                "fromager.bootstrapper._cache.find_cached_wheel",
                 return_value=(None, None),
             ),
             patch(
@@ -937,7 +937,7 @@ def test_bg_prepare_prebuilt_log_prefix_includes_version(
     tmp_context: WorkContext,
     caplog: pytest.LogCaptureFixture,
 ) -> None:
-    """_bg_prepare_prebuilt log message includes name-version prefix when called with context."""
+    """`bg_prepare_prebuilt` log message includes name-version prefix when called with context."""
     old_factory = logging.getLogRecordFactory()
     logging.setLogRecordFactory(log.FromagerLogRecord)
     req = Requirement("mypkg==1.2.3")
@@ -954,7 +954,7 @@ def test_bg_prepare_prebuilt_log_prefix_includes_version(
             patch("fromager.server.update_wheel_mirror"),
             log.req_ctxvar_context(req, version),
         ):
-            _bg_prepare_prebuilt(
+            bg_prepare_prebuilt(
                 ctx=tmp_context,
                 req=req,
                 req_type=RequirementType.INSTALL,

tests/test_bootstrapper_iterative.py

@@ -425,7 +425,7 @@ def mock_cache(
             return (None, None)
 
         with patch(
-            "fromager.bootstrapper._cache._find_cached_wheel", side_effect=mock_cache
+            "fromager.bootstrapper._cache.find_cached_wheel", side_effect=mock_cache
         ):
             result = item.run(bt)
 
@@ -446,7 +446,7 @@ def test_all_cached_keeps_highest_version(self, tmp_context: WorkContext) -> Non
         )
 
         with patch(
-            "fromager.bootstrapper._cache._find_cached_wheel",
+            "fromager.bootstrapper._cache.find_cached_wheel",
             return_value=(tmp_context.work_dir / "cached.whl", None),
         ):
             result = item.run(bt)
@@ -462,7 +462,7 @@ def test_no_filtering_in_single_version_mode(
         item = _make_resolve_item()
         item.bg_future = _make_resolved_future([("url-1.0", Version("1.0"))])
 
-        with patch("fromager.bootstrapper._cache._find_cached_wheel") as mock_cache:
+        with patch("fromager.bootstrapper._cache.find_cached_wheel") as mock_cache:
             result = item.run(bt)
 
         assert len(result) == 1
@@ -499,7 +499,7 @@ def test_filters_failed_versions_in_multiple_versions_mode(
         )
 
         with patch(
-            "fromager.bootstrapper._cache._find_cached_wheel", return_value=(None, None)
+            "fromager.bootstrapper._cache.find_cached_wheel", return_value=(None, None)
         ):
             result = item.run(bt)