PyPI JSON API ↔ pip Client: Coordinating Per-Connection Timeouts with Total Operation Deadlines During Multi-Package Resolution

Interoperability Gap

PyPI's repository APIs (both the legacy JSON endpoint at /pypi/<name>/json and the PEP 691 JSON-based simple index) impose no server-side request deadlines. The pip client enforces its own --timeout (default 15 seconds) per connection attempt and --retries (default 5) for transient failures, but these parameters apply to individual HTTP exchanges rather than to the full resolution-and-download cycle for a dependency graph.

Constraints and Uncertainty

When pip resolves a large dependency tree, it may issue dozens of sequential metadata fetches followed by multiple file downloads, each potentially redirected to the CDN (files.pythonhosted.org) where timeout semantics shift to the edge. No standardized cancellation token or context propagates from the resolver through the downloader to the underlying urllib3 or httpx transports, so a user-initiated interrupt (SIGINT) or a wall-clock deadline cannot be honored cooperatively across phases. Partial downloads leave .part files in the HTTP cache that are not automatically resumed on retry, and concurrent pip invocations sharing a cache directory can race on entry finalization after a timeout.

Specific Questions

1. Should pip introduce a distinct --total-timeout (or similar) that bounds the entire resolution-and-fetch operation, and how would it interact with the existing per-connection --timeout and retry logic?
2. What cancellation propagation mechanism—context objects, asyncio tasks, or a custom token—would allow the resolver, downloader, and transport layers to abort in-flight work consistently without leaving corrupted cache entries?
3. How should clients handle conditional GET revalidation (ETag/Last-Modified from PEP 691) when a retry follows a timeout: treat the cached response as stale and revalidate, or assume the timeout indicates a transient network issue and reuse the cached metadata without a conditional request?