Allow overriding the network timeout with HATCH_NETWORK_TIMEOUT

[puneetgani]

Closes #2158

What

DEFAULT_TIMEOUT in hatch/utils/network.py (added in #1531) is hardcoded to 10 seconds and applies to every network request Hatch makes itself. On slow or heavily proxied connections that is too short, and the only workaround available today is patching the constant, which is what the issue reporter resorted to.

This adds a get_timeout() helper that returns DEFAULT_TIMEOUT unless the HATCH_NETWORK_TIMEOUT environment variable is set, and uses it at both call sites:

• download_file — Python distributions and SPDX license texts
• PackageIndex.client — publishing to a package index

The default behaviour is unchanged.

$ HATCH_NETWORK_TIMEOUT=60 hatch python install 3.12

Why an environment variable rather than config.toml

Neither call site has access to the application config: PythonManager is constructed without it, and DefaultTemplate only receives a cache directory. Threading config into both would be a much larger change, whereas an environment variable works from anywhere and matches the existing HATCH_* convention (HATCH_CACHE_DIR, HATCH_DATA_DIR, HATCH_PYTHON_SOURCE_*). I'm happy to rework this as a config.toml option instead if you'd prefer that direction.

This also covers the publisher-timeout half of #761, which @jamesdow21 noted on the issue is the same underlying problem.

Validation

The value must parse as a finite, positive number; anything else raises a ValueError naming the variable. An explicitly passed timeout= keyword still wins over the environment variable, since download_file uses setdefault.

Notes

This does not change the timeout of the installers Hatch shells out to (pip, uv) — those have their own settings, which the docs now point to. The issue title mentions pip install, but DEFAULT_TIMEOUT never reached pip; the body and the reporter's workaround are about the constant itself, which is what this changes.

Changes

• src/hatch/utils/network.py — get_timeout(), used by download_file
• src/hatch/index/core.py — use get_timeout() for the index client
• src/hatch/config/constants.py — AppEnvVars.NETWORK_TIMEOUT
• docs/config/hatch.md — new "Network" section
• docs/history/hatch.md — changelog entry
• tests/utils/test_network.py — new file, 16 tests covering the default, overrides, validation failures, and that the value reaches streaming_response

ruff check, ruff format --check, and mypy pass on the changed files. tests/utils, tests/index, tests/python, tests/config, and tests/publish pass locally (260 passed, 30 skipped).

AI disclosure

Per the AI contributions policy in CONTRIBUTING.md: this change was written with Claude Code (Opus 5). I reviewed the design decision, the diff, and the tests, and verified the behaviour end to end against a live hatch python install run. I can explain and defend every line of it.