Skip to main content

load_mappings

Function load_mappings 

Source
pub fn load_mappings(
    request: &LoadRequest<'_>,
    fetcher: &dyn InventoryFetcher,
) -> Result<LoadOutcome>
Expand description

Read every configured inventory (load_mappings, _load.py:139-208).

Cache design. Sphinx keeps env.intersphinx_cache — a pickled {uri: (name, expiry, inventory)} — on the environment, so a warm incremental build can skip both the download and the parse. This port keeps only the on-disk half: __intersphinx_cache__/{name}_objects.inv holds the raw bytes, and the file’s mtime is the expiry basis, exactly as Sphinx’s disk short-circuit uses it (_load.py:274-287). A warm rebuild therefore still skips the download and only re-parses, which costs milliseconds — while keeping BuildEnvironment free of a non-serde-shaped field that would have to version-lock with env.bin. The in-memory map below is per-call, and exists so the merge order and the cache-hit checks stay byte-faithful to Sphinx’s.

Two things Sphinx’s memory cache does that this one cannot:

  1. Pruning. Sphinx drops a cached entry whose project changed target URI (_load.py:164-173), where a disk file keyed by project name alone would otherwise serve bytes fetched from somewhere else. Covered a layer up here: changing a target URI changes intersphinx_mapping, changes the configuration fingerprint, and wipes the whole cache directory this file lives in.
  2. Graceful degradation, which is genuinely lost. In Sphinx the previous inventory stays in env.intersphinx_cache across builds, so when an expired remote’s refresh fails the old data is still there and references still resolve — an offline or flaky-network build keeps working. Here a failed refresh leaves nothing behind: the project contributes no inventory, and every reference into it becomes a dangling warning (and fails -W). The stale bytes are still on disk; falling back to them on fetch failure is the obvious remedy and is deliberately not implemented here — it is a behaviour change from Sphinx, not a port of it, and belongs to T13/post-wave with its own decision about how stale is too stale.