feat!: use aria2c automatically when the [aria2] extra is installed

[SkyeAv]

Makes build-fullmap pick its downloader automatically — the bundled aria2c binary whenever the optional [aria2] extra is installed, Tablassert's Python downloader otherwise — and removes the --aria2c / -a flag entirely. Users who install the extra now get the faster download with no flag to discover or remember.

Automatic downloader selection

• Single decision point: build_fullmap resolves extras.is_installed("aria2") exactly once and threads the result into fetch_prebuilt_fullmap and build_fullmap_pipeline through their existing aria2c keyword parameter — no per-file probing, no duplicated decision logic.
• Probed after the reuse short-circuit: a run that reuses an existing database downloads nothing, so it neither probes the extra nor says anything about downloaders.
• Announced, not just logged: the choice is emitted as one download_logger.info record and one stderr line (tablassert build-fullmap: the [aria2] extra is installed; using the bundled aria2c for downloads). loguru's console sink only exists inside a pipeline stage and file logging needs the [log] extra, so the log record alone would never reach a normal terminal; the stderr line follows the reuse short-circuit's existing print(..., file=sys.stderr) precedent. Both derive from one string so they cannot drift.

Flag removal (BREAKING)

• --aria2c / -a are gone from build-fullmap; passing either is an unknown-option parse error, matching the --taxon-allowlist removal precedent in the current Unreleased entry.
• The exit-2 preflight is gone with it — a missing [aria2] extra is no longer an error condition, just a downloader choice.
• No replacement knob: there is deliberately no flag, env var, or config key to opt out of aria2c when the extra is installed. Uninstall the extra instead.

Design

• Detection via extras.is_installed("aria2") (the existing find_spec probe) rather than a _resolve_aria2_binary() try/except: it is cheap, does not execute the module, and lets the choice be logged once at the command boundary. download_babel_file_aria2c's late import_module remains the loud safety net for a present-but-broken extra (TOCTOU).
• Failure semantics are unchanged. A failed prebuilt download still surfaces as PrebuiltFullmapUnavailable → warning → from-scratch BABEL build (and that scratch build keeps using aria2c); a failed BABEL-loop download still propagates BabelDownloadError loudly. There is deliberately no new mid-download fallback from a failing aria2c to the Python downloader — that would mask real network or binary failures.
• Accepted caveat — no platform gate. Selection is a bare find_spec and the aria2 extra carries no environment marker, so a source-built aria2 on macOS would be used. The docs therefore say a normal macOS install resolves to the Python downloader rather than claiming macOS "always" does.
• Honest resolution-failure messages. aria2_unavailable_detail() is reachable from the CLI only after the is_installed probe said yes, so "install the [aria2] extra" was a dead end there (pip reports already-satisfied). It now splits on install state: a present-but-broken install is named as such with reinstall/uninstall advice, while library callers with a genuinely absent extra keep the install hint. The wording is "cannot be resolved (missing, or lacking ARIA2C)" because _resolve_aria2_binary also converts a shadowed module's AttributeError into ImportError.
• Deferred: the adjacent allowlist-rebuild warning has the same terminal-invisibility problem this PR fixes for the downloader choice; errors.py still appends "Check network connectivity or pin a different BABEL version" to broken-install errors. Both are pre-existing and out of scope.

Docs

• docs/cli.md — drops the --aria2c option row; the example is now install-the-extra plus a plain build-fullmap, with a paragraph on automatic selection.
• docs/fullmap.md — opt-in prose replaced throughout; clarifies that both download stages (the prebuilt fullmap.tar.zst archive and the from-scratch BABEL files) use aria2c.
• docs/installation.md — extras row and macOS note reworded; the preflight table intro flags that the [aria2] row is a downloader probe, not a failure report. [aria2] stays named in "When an extra is missing" because test_installation_preflight_docs_cover_source_preflight_calls AST-walks the surviving is_installed call site.
• README.md extras row reworded; CHANGELOG.md carries a BREAKING Unreleased entry. Historical changelog entries mentioning --aria2c are intentionally left as history.

Tests

• Auto-selection, both directions: the choice test is parametrized over both extras.missing states, pinning the exact single log line, its ordering, and that the rejected downloader never runs.
• Failure semantics pinned: a prebuilt aria2c failure still falls back to a scratch build with aria2c still selected, and a BABEL-loop aria2c failure still propagates — both with the Python downloader patched to pytest.fail, so a silent rescue fails the test.
• No-op silence: an existing database neither probes the extra nor emits a choice line on stderr.
• Stale-docs guard: a new parametrized test fails if any live surface (docs/**/*.md, README.md, llms.txt, CONTRIBUTING.md) mentions a retired flag; CHANGELOG.md is excluded since history may name them. --aria2c is matched globally, while the -a table-cell shapes are scoped to the owning command's section — line-scoping would have been vacuous, since option-table rows never repeat the command name — with self-checks proving the matcher is non-vacuous.

Testing

• uv run pytest → 1404 passed, 43 skipped (baseline on main: 1361 passed)
• uv run ruff check . → All checks passed!; uv run ruff format --check . → 88 files already formatted
• uv run pyright → 0 errors, 0 warnings, 0 informations
• uv run tablassert build-fullmap --help 2>&1 | grep -c -- '--aria2c' → 0
• uv run tablassert build-fullmap --aria2c → exit 1, Unknown option: "--aria2c".; same for -a
• rg -n -- '--aria2c' docs/ README.md llms.txt CONTRIBUTING.md src/ → zero matches
• rust/ untouched — every aria2 call site is Python-side

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 10fb7564-4bb0-4357-bfb5-c649e8fd688d

---

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.}