CodeVetter · Repo Unpack · Feature catalog
psf/requests
Every user-facing feature is a Python API, not a route or command. The catalog splits into: the seven HTTP verb helpers and their `Session` methods; request-construction features (params, form/JSON/multipart/streamed bodies, file uploads, IDNA hostnames); response-consumption features (`.text` with charset auto-detection, `.json()` with UTF-BOM sniffing, `.iter_content`/`.iter_lines` streaming, `.links` header parsing, `.raise_for_status`); and connection features (pooling, redirects, cookie persistence, proxy resolution including SOCKS, TLS verification and mTLS client certs, netrc auth, digest auth). Two auxiliary surfaces exist: `python -m requests.help` prints a JSON environment report for bug filing, and `python -m requests.certs` prints the CA bundle path.
- Seven verb helpers are exposed at module level and mirrored as `Session` methods; `head()` uniquely defaults `allow_redirects` to `False` at both levels while `get`/`options` default it to `True`.
- Request bodies support four distinct shapes decided in `prepare_body`: JSON via `complexjson.dumps(json, allow_nan=False)` → `application/json`; multipart via `_encode_files`; form-encoding via `_encode_params` → `application/x-www-form-urlencoded`; and streamed iterables/file objects that set `Transfer-Encoding: chunked` when length is unknown.
- Multipart uploads accept 2-, 3-, and 4-tuples (`filename, fileobj`, `+content_type`, `+custom_headers`) and are assembled into urllib3 `RequestField` objects by `encode_multipart_formdata`.
- Streaming bodies and file uploads are mutually exclusive — combining them raises `NotImplementedError("Streamed bodies and files are mutually exclusive.")`.
- Internationalised domains are supported by `_get_idna_encoded_host()`, which applies `idna.encode(host, uts46=True)` for any non-ASCII host and raises `InvalidURL("URL has an invalid label.")` on failure.
- `Response.text` decodes using the header-declared charset, falling back to `apparent_encoding` (charset_normalizer or chardet), and finally to `utf-8` with `errors="replace"` if no detection library is installed.
- `Response.json()` sniffs UTF-8/16/32 via `guess_json_utf()` when no encoding is declared and the body exceeds 3 bytes, and normalises every decode failure into `requests.exceptions.JSONDecodeError`.
- Streaming download is offered by `iter_content(chunk_size, decode_unicode)` and the line-oriented `iter_lines(delimiter=...)`; re-iterating a consumed non-streamed response raises `StreamConsumedError`.
- Pagination via RFC 5988 is supported by `Response.links`, which parses the `Link` header through `parse_header_links()` and keys results by `rel` (falling back to `url`).
- `requests.codes` is a `LookupDict` supporting attribute and item access with multiple aliases per code — including the joke aliases `codes['\\o/']` and `codes['✓']` for 200 — generated by `_init()` which also appends the full table to the module docstring.
- Three auth handlers ship: `HTTPBasicAuth`, `HTTPProxyAuth` (same header under `Proxy-Authorization`), and `HTTPDigestAuth` supporting MD5, MD5-SESS, SHA, SHA-256 and SHA-512 with `qop=auth`.
- `.netrc` credentials are honoured automatically when `trust_env` is true, checked at `$NETRC` if set otherwise `~/.netrc` and `~/_netrc`, and re-applied on cross-host redirects by `rebuild_auth`.
- SOCKS proxy support is optional: `proxy_manager_for()` routes `socks*` proxies to `SOCKSProxyManager`, and a stub raising `InvalidSchema("Missing dependencies for SOCKS support.")` is installed when PySocks is absent.
- `python -m requests.help` (i.e. `help.main()`) prints a sorted, indented JSON bug-report blob covering platform, interpreter implementation, system OpenSSL version, urllib3, chardet/charset_normalizer, pyOpenSSL, cryptography, idna and requests versions.
- Sessions are picklable: `__getstate__`/`__setstate__` serialise the 12 attributes listed in `Session.__attrs__`, while `HTTPAdapter.__setstate__` rebuilds the unpicklable `PoolManager` by re-calling `init_poolmanager`.