docs(mirrors): the -py install fetches a backend

[michen00]

What changes, and why

mirrors/py/pyproject.toml.in:21 offered the empty dependency list as "what lets a hook environment build from this clone with no network at all", and two hook manifests carried the same claim — mirrors/py/pre-commit-hooks.yaml:9 asserting the ids "resolve from this tree alone and reach no registry", and mirrors/rs/pre-commit-hooks.yaml:10 resting a comparison on it ("That one fetch is the difference from the -py mirror, which needs no network").

Empty dependencies removes every fetch the tool makes when it runs, not every fetch its install makes. The generated -py tree is eight files and vendors no backend:

$ uv run --no-project python scripts/generate_mirrors.py out && find out/py -type f
out/py/.pre-commit-hooks.yaml   out/py/pyproject.toml
out/py/CONTRIBUTING.md          out/py/src/markdown_prose_hooks/__init__.py
out/py/LICENSE                  out/py/src/markdown_prose_hooks/__main__.py
out/py/README.md                out/py/src/markdown_prose_hooks/unwrap.py

$ grep -A2 build-system out/py/pyproject.toml
[build-system]
requires = ['hatchling']
build-backend = 'hatchling.build'

pre-commit installs a language: python hook with a plain pip install ., which builds in isolation. Tried offline in a fresh venv, both ways:

$ pip install --no-cache-dir --no-index out/py
ERROR: Could not find a version that satisfies the requirement hatchling (from versions: none)
× pip subprocess to install build dependencies did not run successfully.

$ pip install --no-cache-dir --no-index --no-build-isolation out/py
BackendUnavailable: Cannot import 'hatchling.build'

So the install needs an index either way. What separates the two mirrors is what each fetches and whether a compiler is wanted — the -rs one takes the implementation crate from crates.io and needs a Rust toolchain; the -py one takes its build backend and what that requires, and needs no compiler — rather than network against no network.

The correction goes to all three sites because the -rs manifest draws its conclusion from the -py claim, so fixing one would leave the other stating the old premise. Someone choosing the -py mirror for an isolated machine on the strength of the original sentence would get a failed hook install.

Note for the release

All three files are mirror templates, so make mirror-diff will disagree until a release regenerates the mirrors. No CI job runs that target.

Corpus

The corpus is the specification, and both implementations answer to it. Tick what applies.

• This changes no behavior the corpus specifies.
• This changes what gets joined, and a case in corpus/ pins the new behavior. The case was written first and failed first.
• The change makes the tool join more than it did. The section above says what it will not eat.

Comments only — no generated file's content changes except the comments that ship inside it.

Checks

• make check passes, or make test does and this touches no Rust.

make tidy — prettier, yamllint, check-toml and both spell gates reach the changed files. No Rust, no Python.

Follow-up correction

The first wording of the -py manifest said the build backend was the one thing fetched, which overstates in the same direction as the sentence it replaced: build isolation installs hatchling's own requirements too.

$ python -m pip install --dry-run hatchling      # 3.13.7
Would install hatchling-1.32.0 packaging-26.3 pathspec-1.1.1 pluggy-1.6.0
              tomlkit-0.15.1 trove-classifiers-2026.6.1.19

The 3.10 floor adds tomli, per hatchling's tomli>=1.2.2; python_version < "3.11". Both comments now name the fetch without counting it, so neither goes stale when that list moves. The same commit drops the clause in pyproject.toml.in that explained why the point was worth stating.

[qodo-code-review]

PR Summary by Qodo

Clarify mirror installation network requirements

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Correct Python mirror documentation to distinguish install-time backend fetching from
 dependency-free runtime.
• Clarify Rust mirror differences: implementation fetch and compiler requirement, not network
 availability.
• Preserve behavior; generated mirrors will synchronize during the next release.

Diagram

sequenceDiagram
  actor Consumer
  participant PC as pre-commit
  participant Pip as pip
  participant Py as Python mirror
  participant Index as Package index
  participant Cargo as cargo
  participant Rs as Rust mirror
  Consumer->>PC: Install hook
  alt Python hook
    PC->>Pip: pip install
    Pip->>Py: Build local code
    Pip->>Index: Fetch hatchling
  else Rust hook
    PC->>Cargo: cargo install
    Cargo->>Rs: Build wrapper
    Cargo->>Index: Fetch implementation
  end

Loading

High-Level Assessment

Correcting all three related template comments is the appropriate approach because the inaccurate no-network premise appears directly in the Python files and indirectly in the Rust comparison. Vendoring Hatchling or changing the build process would alter packaging behavior and is unnecessary for this documentation correction.

Files changed (3) +12 / -5

Documentation (3) +12 / -5

pre-commit-hooks.yamlCorrect Python hook installation network guidance +4/-1

Correct Python hook installation network guidance

• Clarifies that hook code comes from the cloned mirror without runtime registry access, while installation still fetches Hatchling from an index for the isolated build.

mirrors/py/pre-commit-hooks.yaml

pyproject.toml.inDocument Hatchling as an install-time dependency +5/-2

Document Hatchling as an install-time dependency

• Reframes the empty dependency list as preventing additional runtime fetches rather than enabling a fully offline installation. Explicitly documents pip build isolation and its need to obtain Hatchling.

mirrors/py/pyproject.toml.in

pre-commit-hooks.yamlCorrect the Rust-to-Python mirror comparison +3/-2

Correct the Rust-to-Python mirror comparison

• Explains that both mirrors need network access during installation. The Rust mirror differs by fetching its implementation crate and requiring a Rust toolchain, while Python fetches its build backend.

mirrors/rs/pre-commit-hooks.yaml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.40%. Comparing base (97d51a6) to head (c4c099e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #34   +/-   ##
=======================================
  Coverage   87.40%   87.40%           
=======================================
  Files           3        3           
  Lines         691      691           
=======================================
  Hits          604      604           
  Misses         87       87           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟢 Approval recommended

The changes are comment-only documentation corrections and appear internally consistent and technically accurate.

Pull request overview

This PR corrects documentation in the mirror templates to clarify that the -py mirror still needs network access at install time (to fetch the build backend), even though it has no runtime dependencies. This aligns the mirror documentation with how pre-commit installs language: python hooks (PEP 517 build isolation) and avoids overstating “no network at all”.

Changes:

• Update -py mirror docs to distinguish runtime “no fetches” from install-time build-backend fetches (hatchling).
• Update -rs mirror docs to describe the real distinction as “what gets fetched and required toolchains,” rather than “network vs no network”.

File summaries

File	Description
mirrors/rs/pre-commit-hooks.yaml	Updates mirror comparison wording to reflect install-time fetches/toolchain differences accurately.
mirrors/py/pyproject.toml.in	Clarifies that dependency-free runtime does not imply offline build/install due to PEP 517 backend installation.
mirrors/py/pre-commit-hooks.yaml	Clarifies that the hook code resolves from the tree, but the build backend is fetched during install.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The changes are limited to template comments and improve accuracy without affecting tool behavior or interfaces.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Lite