Product View: Python Requests Library

Feature Inventory

Overall Assessment: All documented features are fully implemented. This is a mature, production-grade HTTP library. No features are partial or scaffolding.

What the Code Does That the Spec Doesn't Mention

1. HEAD requests silently disable redirects by default — The head() function at both the API level (src/requests/api.py:113) and Session level (src/requests/sessions.py:684-693) sets allow_redirects=False by default. This is a deliberate design choice (HEAD responses should not follow redirects per HTTP semantics), but it's a behavioral difference from all other methods that users may not expect.

2. data and json cannot be used together — When both data and json are provided, only data is used in the body. The json parameter is silently ignored (src/requests/models.py:422-449). Tests confirm this (tests/test_requests.py:2141-2149). This is not documented in the API docstrings.

3. Session headers with None values are excluded from requests — If a session header is set to None, it is stripped from the prepared request rather than sent as an empty header (tests/test_requests.py:496-502). This is a user-facing behavior that could affect debugging.

4. Redirect auth stripping has special-case logic — Authorization headers are stripped on cross-host redirects, but there's a specific exception: HTTP→HTTPS redirects on standard ports (80→443) are allowed to keep auth (src/requests/sessions.py:154-184). This is a backward-compatibility decision not documented in the API reference.

5. Non-ASCII redirect locations are re-encoded — The get_redirect_target method encodes the Location header in latin1 and then decodes as UTF-8 (src/requests/sessions.py:134-152). This handles a real-world encoding ambiguity but is an undocumented heuristic.

6. Streaming bodies are seeked for redirect replay — When a request body is a stream, the library records the stream position and rewinds it for redirect retries. If rewinding fails, it raises UnrewindableBodyError (src/requests/utils.py:1139-1155). This is critical for users sending file-like objects with redirects.

7. Response.ok is NOT a 200 check — The ok property returns True for any status code < 400, not just 200 (src/requests/models.py:860-872). This is a common point of confusion for new users.

8. Digest auth resets its 401 counter on redirect — HTTPDigestAuth.handle_redirect resets num_401_calls to 1 on redirect responses (src/requests/auth.py:268-271). This prevents the auth from giving up after a redirect to another digest-protected resource.

9. Session is a context manager that closes adapters — Using with requests.Session() as s: closes all connection pools on exit (src/requests/sessions.py:505-509, src/requests/adapters.py:555-563). This prevents resource warnings but is an implicit behavior users may not realize.

10. Response.next is only populated when redirects are NOT followed — The next property returns a PreparedRequest for the next redirect only when allow_redirects=False (src/requests/sessions.py:818-820). When redirects are followed, the history is flattened into response.history.

Spec Gaps

This codebase is the Python requests library (v2.x era, with type hints added). There is no separate spec/README file in the extracted claims — the "spec" is the docstrings and the public API. Based on the code:

1. No documented behavior for data={} default — In Session.request(), data defaults to {} (empty dict) when not provided (src/requests/sessions.py:628). This means every request without explicit data sends an empty form-encoded body. This could surprise users who expect no body at all for GET/DELETE requests.

2. json parameter silently ignored when data is also provided — The docstrings for post() and Session.request() list both data and json as optional, but don't document that data takes precedence. A user providing both would expect an error or merge behavior.

3. No documented limit on redirect count — The default is 30 (src/requests/sessions.py:488), but this is not mentioned in the API docstrings for request() or Session.request().

4. stream parameter default behavior is implicit — The Session defaults stream=False (src/requests/sessions.py:466), meaning response content is always fully downloaded unless explicitly opted out. This is documented in the request() docstring but not in the Session class docstring.

5. No mention of trust_env in convenience function docstrings — The requests.get(), requests.post(), etc. docstrings don't mention that environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, REQUESTS_CA_BUNDLE) are read by default.

Open Questions for Engineering

1. data={} default — bug or feature? In Session.request() line 628, data defaults to {} (empty dict). This means a session.get(url) sends an empty Content-Type: application/x-www-form-urlencoded body. Is this intentional? It could break servers that reject unexpected request bodies on GET. The api.py convenience functions pass data=None by default, so this only affects direct Session.request() usage.

2. json + data silent override — should this raise? When both data and json are provided, data wins silently. Should we raise a ValueError (like we do for data + files conflicts at src/requests/models.py:422-449)? The current behavior is surprising and could lead to hard-to-debug issues.

3. HEAD redirect behavior — is the default False universally correct? The head() function defaults allow_redirects=False. While this follows HTTP spec guidance, some APIs return 302 on HEAD and expect clients to follow. Should this be configurable without kwargs? The current implementation forces users to write requests.head(url, allow_redirects=True) explicitly.

4. Response.ok naming confusion — The property returns True for any 2xx or 3xx status. Users frequently assume it means "status == 200". Consider whether a deprecation or clearer documentation is warranted.

5. Session pickling — what's the use case? The __getstate__/__setstate__ implementation serializes session attributes but not connection pools. Is this for caching session configuration (headers, auth, cookies) across process restarts? The current implementation would lose live connections.

6. No rate limiting or retry built-in — The library delegates retry logic to urllib3. Users who want automatic retries must configure HTTPAdapter with max_retries. Should this be a first-class parameter on Session.request()?

7. cert parameter accepts a tuple but docstrings only mention string — The cert parameter can be a ('cert', 'key') tuple, but the docstring at src/requests/api.py:55 says "if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair." — this is actually documented correctly in the API but the Session docstring at line 615 only mentions the string case. Inconsistency.