psf/requests
There is no application entrypoint — the package root `src/requests/__init__.py` is the runtime boundary, and it does dependency-compatibility checking, optional pyOpenSSL SNI injection, and re-export of the public API before anything else runs. Beneath it sit four layers: the stateless verb wrappers (`api.py`), the stateful `Session` (`sessions.py`), the request/response value objects (`models.py`), and the urllib3-backed transport (`adapters.py`). Cross-cutting support lives in `utils.py` (proxies, netrc, header validation, length probing), `cookies.py` (a `CookieJar`/`MutableMapping` hybrid), `structures.py` (`CaseInsensitiveDict`, `LookupDict`), and `exceptions.py`. There is no storage layer: the only persistent state is the in-memory `RequestsCookieJar` on a `Session` and urllib3's connection pools. Build is setuptools via `pyproject.toml`; test/lint/typecheck/publish are four separate GitHub Actions workflows, and distribution is a Trusted-Publishing PyPI upload on `v*` tags.
- The package root is the de-facto entrypoint: importing `requests` runs `check_compatibility()` to assert urllib3 >= 1.21.1 and chardet 3.0.2–8.0.0 / charset_normalizer 2.0.0–4.0.0, emitting `RequestsDependencyWarning` on mismatch rather than failing the import.
- Import also attempts `pyopenssl.inject_into_urllib3()` when `ssl.HAS_SNI` is falsy and then version-checks `cryptography` via `_check_cryptography()`, warning if below 1.3.4 — a side effect that mutates urllib3 globally at import time.
- The public API surface is fixed by the `__all__` tuple in `__init__.py`: 7 verb functions (`get/post/put/patch/delete/head/options`) plus `request`, the `Session`/`Request`/`PreparedRequest`/`Response` types, `codes`, and 9 exception classes.
- `api.request()` is stateless by construction — it opens `sessions.Session()` in a `with` block for every call specifically to close sockets and avoid `ResourceWarning`, meaning module-level calls get zero connection reuse.
- `Session.__init__` establishes all mutable session state (headers from `default_headers()`, empty proxies/params/hooks, `verify=True`, `max_redirects=DEFAULT_REDIRECT_LIMIT` of 30, `trust_env=True`) and mounts an `HTTPAdapter` for both `https://` and `http://`.
- The transport boundary is `HTTPAdapter.send()`, which calls `conn.urlopen(..., redirect=False, preload_content=False, decode_content=False, retries=self.max_retries)` — requests deliberately disables urllib3's own redirect and decode handling and reimplements both.
- The only external integrations are the four hard runtime dependencies declared in `pyproject.toml`: `charset_normalizer>=2,<4`, `idna>=2.5,<4`, `urllib3>=1.26,<3`, `certifi>=2023.5.7`; SOCKS and chardet are optional extras.
- The CA bundle boundary is `certs.where()`, a one-line re-export of `certifi.where` that the module docstring explicitly names as the seam distro packagers should patch; it is captured once at import into `utils.DEFAULT_CA_BUNDLE_PATH`.
- Build/test commands live in the `Makefile`: `make init` installs `requirements-dev.txt`, `make test` runs `pytest tests`, `make ci` adds `--junitxml=report.xml`, and `make coverage` runs pytest-cov against `src/requests`.
- pytest is configured with `addopts = "--doctest-modules"` and `testpaths = ["tests"]`, so the docstring examples in `api.py`, `sessions.py`, and `status_codes.py` are executed as tests alongside the suite.
- Deployment is PyPI-only via `.github/workflows/publish.yml`, which builds with `SOURCE_DATE_EPOCH` pinned to the commit time for reproducibility and publishes through `pypa/gh-action-pypi-publish` with `attestations: true` and `id-token: write` (Trusted Publishing, no stored API token).
- Five CI workflows gate the repo: `run-tests.yml` (matrix of Python 3.10–3.15-dev plus 3.14t free-threaded and pypy-3.11, across ubuntu/macOS/windows), `lint.yml` (pre-commit), `typecheck.yml` (pyright), `codeql-analysis.yml`, and `zizmor.yml` for Actions-security scanning.
- `packages.py` is a compatibility shim that aliases `sys.modules['requests.packages.urllib3.*']` to the real urllib3/idna/chardet modules so pre-2.16 imports still resolve to identical module objects.
- Docs are a separate Sphinx build deployed to Read the Docs with the `dirhtml` builder on Python 3.12, producing PDF and ePub alongside HTML; `make docs` builds them locally.