[proposal] Multiple cache wheel servers

[tiran]

Pull Request Description

What

Propose support for multiple --cache-wheel-server-url values so fromager can pull wheels from several caches in order, e.g. a variant-wide Pulp cache followed by an arch-specific GitLab PyPI registry.

Why

See: #1064

• PR follows CONTRIBUTING.md guidelines

[coderabbitai]

📝 Walkthrough

Walkthrough

This change adds documentation for a new proposal named "Multiple cache wheel servers." The pull request introduces a new proposal document (multiple-cache-wheel-servers.md) that outlines an implementation plan for supporting multiple cache wheel server URLs via a repeatable CLI option. The proposal document is integrated into the documentation structure by adding it to the Sphinx toctree in docs/proposals/index.rst. Additionally, three new words are added to the spelling word list for documentation validation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and directly summarizes the main change: a proposal to support multiple cache wheel servers.
Description check	✅ Passed	The description is directly related to the changeset, explaining the rationale (multiple cache URLs) and reference to the tracking issue.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/proposals/multiple-cache-wheel-servers.md`:
- Around line 10-12: Update the proposal text to correct the wrong comparison to
pip: remove the claim that `--extra-index-url` uses first-match semantics and
state that pip performs best-candidate selection across all indexes; then
clearly state whether Fromager's `--cache-wheel-server-url` lookup uses
first-match (first cache hit wins) or best-candidate selection, and make the
comparison consistent with uv's `unsafe-best-match` wording used later.
Reference and edit the sections mentioning `--cache-wheel-server-url`,
`--extra-index-url`, `unsafe-best-match`, and the Fromager cache lookup
description so the behavior is unambiguous and consistent across lines 10–12,
82–83, and 90–93.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 109bb325-3f40-449f-9ee7-a2d469128081

📥 Commits

Reviewing files that changed from the base of the PR and between 297ed76 and 91f6bf0.

📒 Files selected for processing (3)

• docs/proposals/index.rst
• docs/proposals/multiple-cache-wheel-servers.md
• docs/spelling_wordlist.txt

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

`Using official documentation, what are the exact selection semantics for:

1. pip with --index-url + multiple --extra-index-url
2. uv with UV_INDEX_STRATEGY=unsafe-best-match
   Specifically, do they use first-index-hit ordering or best-candidate selection across all indexes?`

💡 Result:

1. pip with --index-url + multiple --extra-index-url: best-candidate selection across all indexes. Pip collects package files/links from all specified indexes (including the primary --index-url and all --extra-index-urls), evaluates them together as a unified set of candidates, and selects the best match based on version, compatibility, and preferences (e.g., wheels over sdists). There is no strict first-index-hit ordering; indexes are merged before resolution. 2) uv with UV_INDEX_STRATEGY=unsafe-best-match: best-candidate selection across all indexes. Unlike uv's default first-index (which uses first-index-hit), unsafe-best-match searches all indexes for a package, considers all versions from all indexes as candidates, and selects the "best" (typically highest compatible) version. If the same version appears in multiple indexes, it uses the one from the first index.

Citations:

• 1: https://pip.pypa.io/en/latest/cli/pip_install/
• 2: https://pip.pypa.io/en/stable/development/architecture/package-finding/
• 3: https://peps.python.org/pep-0766/
• 4: https://docs.astral.sh/uv/configuration/indexes/
• 5: https://docs.astral.sh/uv/reference/settings/
• 6: Implement --index-strategy unsafe-best-match astral-sh/uv#3138

---

Fix factual claim about pip's index selection behavior.

Lines 10–12 and 82–83 incorrectly state that the proposal uses "first-match semantics, same as --extra-index-url". In reality, pip's --extra-index-url performs best-candidate selection across all indexes, not first-match ordering. This contradicts the accurate description in lines 90–93, which correctly states that uv's unsafe-best-match chooses the best match across all indexes.

Clarify whether fromager's cache lookup uses first-match (first cache hit wins) or best-candidate selection (evaluate candidates from all caches), and correct the comparison to pip's actual behavior.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/proposals/multiple-cache-wheel-servers.md` around lines 10 - 12, Update
the proposal text to correct the wrong comparison to pip: remove the claim that
`--extra-index-url` uses first-match semantics and state that pip performs
best-candidate selection across all indexes; then clearly state whether
Fromager's `--cache-wheel-server-url` lookup uses first-match (first cache hit
wins) or best-candidate selection, and make the comparison consistent with uv's
`unsafe-best-match` wording used later. Reference and edit the sections
mentioning `--cache-wheel-server-url`, `--extra-index-url`, `unsafe-best-match`,
and the Fromager cache lookup description so the behavior is unambiguous and
consistent across lines 10–12, 82–83, and 90–93.