Requests

What it is

The project is a Python library for making HTTP requests. It provides a high-level interface for interacting with web services, handling common tasks such as session management, authentication, cookie handling, and redirect following.

What it does

The library exposes functions for each HTTP method (get, post, put, patch, delete, head, options) that delegate to a session context manager. Key subsystems include a model layer for encoding parameters and multipart file data, a session layer with redirect and hook management, an adapter layer for low-level transport, authentication handlers (Basic, Digest, Proxy), a cookie jar wrapper, a case‑insensitive dictionary for headers, and a set of runtime‑checkable type protocols.

Architecture health

The project has zero import cycles. It consists of 23 source files and 10 test files, yielding a test ratio of approximately 0.43. No semgrep findings are present. Several structural patterns are used: mixin classes for request encoding, hooks, and redirect handling, a base adapter class, and a base authentication class.

What it enforces

The library validates HTTP header names and values against compiled regular expressions, rejecting invalid ones. Parameter encoding accepts strings, bytes, streams, or key‑value iterables and uses URL encoding with doseq=True. File encoding raises a ValueError when files are falsy or data is a string. Redirect limits are enforced; exceeding max_redirects raises a TooManyRedirects exception. SSL certificate verification can be disabled or pointed to a custom CA bundle or directory. The CaseInsensitiveDict stores keys lowercased but preserves original case in iteration.

Definition of Done

The single base exception class RequestException inherits from IOError and captures the response and request objects. The redirect resolver removes Content‑Length, Content‑Type, and Transfer‑Encoding headers for non‑307/308 redirects. The is_prepared function narrows the type of a PreparedRequest to a validated request with non‑optional URL and method. The MockRequest wrapper marks all requests as unverifiable and raises NotImplementedError for add_header. The _basic_auth_str function issues deprecation warnings for non‑string credentials and encodes them in latin1 before base64.

Gaps and risks

There is a potential bug in MockResponse.getheaders where the result of the call is not returned, which may affect cookie extraction. The test infrastructure uses threading.Server, which could indicate concurrency concerns in production use. The library depends on urllib3 and idna, with a fallback import mechanism that copies modules to the requests.packages namespace. No concurrency‑safety guarantees are evident from the source.