GO — Healthy across the board

• In RepoPilot's curated trusted-corpus (29 projects)
• Last commit 2d ago
• 23+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

Requests is a Python HTTP client library that abstracts away the complexities of making HTTP/1.1 requests with a simple, elegant API. It handles connection pooling, SSL/TLS verification, authentication (Basic, Digest), automatic decompression, cookie persistence, and streaming downloads — allowing developers to write requests.get(url) instead of wrestling with urllib or httplib directly. Single-package structure: the core library lives in requests/ (not shown in truncated file list but standard layout). The docs/ directory contains Sphinx documentation with API docs (api.rst) and dev guides. The tests/ directory (not shown) holds the test suite. Configuration spans .github/workflows/ for CI/CD, .readthedocs.yaml for doc building, .pre-commit-config.yaml for local checks, and Makefile for common tasks.

Python developers building web applications, data pipelines, or services that need to make HTTP calls to APIs or servers. They range from beginners writing simple scripts to large teams maintaining production services that depend on reliable HTTP communication.

Highly mature and production-ready. Requests is downloaded ~300M times per week and is depended on by 4M+ repositories. The codebase is 390KB+ of Python, has comprehensive GitHub Actions CI (run-tests.yml, lint.yml, codeql-analysis.yml, typecheck.yml), security policies, and active maintenance with dependabot integration. This is one of the most trusted HTTP libraries in Python.

Low risk for typical use cases. The main risk is slow response to severe security issues (relies on small core team), and the requirement to use Python 3.10+ limits backcompat. The repository enforces code quality through pre-commit hooks (.pre-commit-config.yaml), CodeQL analysis, and type checking (typecheck.yml workflow), but adoption of new Python versions may lag behind releases.

Active maintenance with focus on code quality: TypeScript-style type checking (typecheck.yml), security scanning (codeql-analysis.yml, zizmor.yml for supply chain), automated issue/PR management (close-issues.yml, lock-issues.yml), and automated publishing (publish.yml). The project recently enforced an AI policy (.github/AI_POLICY.md), indicating governance focus. Development targets Python 3.10+ officially.

git clone -c fetch.fsck.badTimezone=ignore https://github.com/psf/requests.git
cd requests
python -m pip install -e .
python -m pip install -r requirements-dev.txt  # inferred from dev workflow
make test  # or pytest from Makefile

Daily commands:

make test        # run full test suite
make lint        # run code linters (flake8, black)
make docs        # build Sphinx docs to docs/_build/

Or directly: pytest tests/ to run tests, python -c 'import requests; print(requests.__version__)' to verify installation.

• src/requests/__init__.py — Main entry point exporting the public API (get, post, Session, etc.) that all users import.
• src/requests/sessions.py — Core Session class that manages HTTP request lifecycle, connection pooling, and state persistence.
• src/requests/adapters.py — HTTPAdapter that bridges requests to urllib3, handling retries, pooling, and the actual socket-level transport.
• src/requests/models.py — Request and Response model classes that encapsulate HTTP message structure and parsing logic.
• src/requests/auth.py — Authentication handlers (BasicAuth, DigestAuth) implementing the auth hook interface.
• src/requests/utils.py — Utility functions for URL encoding, headers, cookies, and content negotiation used throughout the library.
• pyproject.toml — Project metadata, dependencies (urllib3, certifi, charset-normalizer), and build configuration.

• Session (Python, urllib3) — Orchestrates request lifecycle: preparation, auth, hooks, adapter dispatch, and response finalization.
  • Failure mode: Misconfigured auth or hooks break all requests in that session; connection errors propagate as exceptions.
• HTTPAdapter (urllib3, OpenSSL) — Manages connection pooling via urllib3.PoolManager; applies retries, proxy settings, and SSL/TLS config.
  • Failure mode: Pool exhaustion causes timeouts; certificate verification failures raise SSLError; retries can mask transient failures.
• PreparedRequest (Python, urllib.parse) — Immutable representation of an HTTP request ready for transmission; encodes method, URL, headers, body.
  • Failure mode: Invalid URL encoding or malformed headers cause transmission errors; mutation after preparation is not supported.
• Response (Python, charset-normalizer) — Parses and exposes HTTP response: status, headers, content; lazy-loads body and auto-detects encoding.
  • Failure mode: Corrupted content-encoding or wrong charset detection yields garbled .text; missing content-length may cause incomplete reads.
• Auth handlers (hashlib, base64) — Callable objects that inject credentials (Basic, Digest, custom) into request headers before transmission.
  • Failure mode: Weak auth schemes transmit credentials in plaintext; Digest replay attacks possible without nonce validation.
• Cookies (http.cookiejar) — RequestsCookieJar manages Set-Cookie and Cookie headers, persisting state across requests in a session.
  • Failure mode: Expired or invalid cookies silently sent; third-party cookie blocking not automatic; session theft if cookies leaked.
• Content negotiation (charset-normalizer, zlib) — Auto-detects encoding, parses JSON, handles gzip/deflate decompression via urllib3.
  • Failure mode: Wrong charset guessing produces garbled text; missing content-encoding header skips decompression.

• User code → requests.api (get, post, etc.) — User calls convenience function with URL, params, headers, auth, etc.
• requests.api → Session.request() — Convenience functions delegate to a module-level Session instance.
• Session.request() → PreparedRequest — Session.prepare_request() encodes URL, headers, body, and applies auth hooks.
• Session (with hooks) → HTTPAdapter.send() — Session dispatches the prepared request to the appropriate adapter (http:// or https://).
• HTTPAdapter → urllib3.PoolManager — Adapter sends the request and receives raw HTTPResponse from the connection pool.
• urllib3 HTTPResponse → Response object — Session wraps urllib3's response, applies response hooks, and returns a user-facing Response object.

Add a new authentication scheme

1. Create a new callable class (e.g., CustomAuth) that inherits or mimics the auth interface with call(r) method. (src/requests/auth.py)
2. Implement call to modify the request object (r) in-place, adding headers or credentials. (src/requests/auth.py)
3. Pass your auth object to requests.get(..., auth=CustomAuth()) or session.auth = CustomAuth(). (src/requests/api.py)
4. Add tests verifying the auth handler modifies requests correctly. (tests)

Add a new hook (event callback)

1. Register your hook function in the hooks dict with a key like 'response', 'request', etc. (src/requests/hooks.py)
2. Define a hook function matching the signature: def my_hook(r, *args, **kwargs): ... (src/requests/models.py)
3. Pass hooks={'response': [my_hook]} to requests.get() or session.hooks. (src/requests/sessions.py)

Customize request preparation (encoding, headers, auth)

1. Override or extend PreparedRequest in models.py or subclass Session. (src/requests/models.py)
2. Override prepare_auth, prepare_headers, prepare_body, or prepare_url in your Session subclass. (src/requests/sessions.py)
3. Instantiate your custom Session and call .request() with your custom logic. (src/requests/api.py)

Add custom transport/adapter behavior (retries, proxies, SSL)

1. Subclass HTTPAdapter and override send() to intercept transport logic. (src/requests/adapters.py)
2. Mount your custom adapter: session.mount('https://', CustomAdapter()). (src/requests/sessions.py)
3. Use your session for all requests: session.get(url) will use your custom adapter. (src/requests/api.py)

• urllib3 — Provides HTTP/1.1, connection pooling, retries, and SSL/TLS handling without reimplementing low-level socket logic.
• certifi — Supplies a curated, up-to-date CA certificate bundle for SSL/TLS verification across all platforms.
• charset-normalizer — Intelligently detects and normalizes character encodings from HTTP responses without manual user intervention.
• http.cookiejar — Standard library cookie handling with RFC 6265 compliance; requests wraps it for a friendlier API.

• Delegating transport to urllib3 rather than using httplib directly

  • Why: urllib3 provides mature pooling, retries, and proxy support; reimplementing would increase maintenance burden.
  • Consequence: Adds a dependency but eliminates many socket-level bugs; users trade library size for robustness.

• Session-per-connection-pool vs. global default session

  • Why: Users can create multiple Session instances for isolation (cookies, auth, adapters); the module also provides convenience functions using a module-level session.
  • Consequence: Flexibility for advanced use cases; simpler users can call requests.get() directly without session overhead.

• Hook system for extensibility instead of subclassing only

  • Why: Hooks allow users to inject custom logic (logging, retries, transformations) without forking the library.
  • Consequence: More extension points but increased API surface; users must understand hook signatures and execution order.

• Content auto-detection (encoding, JSON parsing) vs. explicit declaration

  • Why: Reduces boilerplate for common cases; r.json() and r.text work without manual headers inspection.
  • Consequence: Convenience for users; occasional surprises when content-type is missing or wrong; users can override via explicit encoding.

• Real-time bidirectional communication (not WebSocket support); use other libraries like websockets.
• HTTP/2 or HTTP/3 (stays on HTTP/1.1 via urllib3; httpx for HTTP/2).
• Async I/O (synchronous only; use httpx or aiohttp for async).
• GraphQL-specific tooling (general-purpose HTTP library, not GraphQL client).
• Request/response streaming with unlimited buffering (respects memory constraints via iter_content()).

• Avg cyclomatic complexity: ~7 — High number of optional parameters, hook callbacks, and fallback behaviors (auth, encoding, retries); cyclomatic complexity peaks in Session.request and models.py Response methods.
• Largest file: src/requests/models.py (1,050 lines)

• Global mutable default session (Medium) — src/requests/api.py: Module-level session() function reuses a single SessionRedirect instance across all convenience function calls, risking cookie/auth bleed if not careful.
• Direct attribute mutation on Response (Low) — src/requests/models.py: Response._content and Response.encoding can be set after construction; no immutability enforcement, inviting bugs if modified mid-pipeline.
• Late binding of default adapters (Medium) — src/requests/sessions.py: HTTPAdapter instances are created once per scheme per session and cached; if adapter state is mutable, concurrent modification could race.
• Implicit charset fallback chain (Low) — src/requests/models.py: Response.encoding cascades through multiple heuristics (Content-Type, charset-normalizer, ISO-8859-1); hard to debug if a user's response is decoded incorrectly.

• src/requests/models.py (Response.iter_content) (Memory/I/O performance) — Content is iterated byte-by-byte or in small chunks; large files may stress memory or trigger many small reads.
• src/requests/utils.py (requote_uri, super_len) (CPU/I/O performance) — URL and body length computation may involve multiple passes over strings or file-like objects.
• src/requests/adapters.py (HTTPAdapter.send) (Latency) — Each request acquisition from the pool + TLS handshake is synchronous; no pipelining or multiplexing.
• src/requests/sessions.py (Session.request) (Latency) — Full request preparation, auth, hooks, and response finalization are sequential; no async batching.

1. Bad timezone in git history: The clone command requires -c fetch.fsck.badTimezone=ignore to avoid failures; a known quirk of the historical repository.
2. Python 3.10+ only: The codebase officially supports only Python 3.10+; older Python versions will fail silently or with cryptic errors.
3. urllib3 is a hard dependency: Requests wraps urllib3 heavily; understanding urllib3's behavior (connection pooling, retries, timeout handling) is necessary for debugging.
4. No async support: If you need async/await, use httpx or aiohttp, not requests; this is by design and won't change.
5. Encoding auto-detection: The library uses chardet to guess response encoding; can sometimes guess wrong if headers are missing. Always verify with .encoding property.
6. Session cookie storage is in-memory by default: Sessions don't persist cookies to disk without extra code; consider requests-cache or browser cookies for persistence.

• Connection Pooling — Requests reuses TCP connections across multiple requests to reduce latency and server load; the HTTPAdapter leverages urllib3's PoolManager to implement this, and understanding when pools are created/reused is critical for performance tuning.
• Keep-Alive (HTTP/1.1 Persistent Connections) — Requests automatically negotiates Keep-Alive headers to hold connections open; this is transparent but essential for understanding why a single Session is faster than repeated module-level requests.get() calls.
• Authentication Schemes (Basic, Digest) — The auth.py module implements pluggable auth handlers for different HTTP authentication methods. Understanding how auth hooks into the request lifecycle is necessary to implement custom auth (e.g., OAuth, API keys).
• Content Negotiation & Encoding Detection — Requests uses chardet to auto-detect response character encoding and respects Content-Type headers; incorrect encoding detection is a common silent bug (e.g., UTF-8 vs Latin-1).
• Chunked Transfer Encoding — Requests supports streaming large responses via chunked encoding without loading entire response bodies into memory; the streaming API (response.iter_content, response.raw) depends on understanding chunk boundaries.
• Certificate Pinning & SSL/TLS Verification — Requests validates SSL certificates by default and supports custom CA bundles; misunderstanding cert verification is the root cause of many 'SSL error' issues in production.
• Hooks (Request/Response Lifecycle Callbacks) — Sessions and individual requests support hooks for logging, modifying requests/responses on-the-fly, or triggering side effects; this extensibility pattern is subtle but powerful for middleware-like behavior.

• encode/httpx — Modern async/await alternative to Requests with a nearly identical API; recommended for new projects needing async I/O
• kennethreitz/httpbin — HTTP testing service created by Requests' original author; widely used in Requests tests and docs as a mock HTTP server
• urllib3/urllib3 — Low-level HTTP connection library that Requests depends on; understanding urllib3 helps debug connection, pooling, and SSL issues
• psf/cython-package — Related PSF infrastructure project; Requests maintainers coordinate through PSF governance for security and release processes
• pallets/flask — Companion ecosystem project; Flask developers use Requests to write integration tests and HTTP client code in Flask applications

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive type hints to src/requests core modules

The repo has a typecheck.yml workflow but the codebase likely lacks complete type annotations. Since the repo is widely used as a reference implementation, adding type hints to core modules (sessions, models, auth, etc.) would improve IDE support, catch bugs early, and serve as a reference for the community. The existing typecheck.yml workflow suggests this is already a priority.

• [ ] Run mypy/pyright against src/requests to identify untyped modules
• [ ] Add type hints to src/requests/sessions.py (main Session class)
• [ ] Add type hints to src/requests/models.py (Request/Response classes)
• [ ] Add type hints to src/requests/auth.py (authentication handlers)
• [ ] Ensure typecheck.yml workflow passes with strict settings
• [ ] Update pyproject.toml with type checking configuration if needed

Add integration tests for HTTP/2 and connection pooling edge cases

The requests library is heavily used in production, but the test coverage for connection pooling behavior, HTTP/2 support (via urllib3), and edge cases around connection reuse is likely incomplete. Adding focused integration tests would prevent regressions and improve reliability for users relying on these features.

• [ ] Review run-tests.yml workflow to understand current test scope
• [ ] Add integration tests for connection pool exhaustion scenarios
• [ ] Add tests for keepalive behavior and connection reuse across multiple requests
• [ ] Add tests for HTTP/2 multiplexing (if supported via urllib3)
• [ ] Add tests for timeout behavior on slow/stalled connections
• [ ] Document test execution in docs/dev/contributing.rst

Create a security audit checklist and document dependency vulnerability monitoring

The repo has SECURITY.md and dependabot.yml but lacks documented procedures for security reviews. Adding a specific checklist for common HTTP library vulnerabilities (SSRF, header injection, cookie handling) and linking it to the contribution guide would help contributors understand security considerations and catch issues early.

• [ ] Expand docs/community/vulnerabilities.rst with specific OWASP/CWE categories relevant to HTTP libraries
• [ ] Create a SECURITY_CHECKLIST.md documenting authentication, SSL/TLS, cookie, and header validation checks
• [ ] Add examples in docs/dev/contributing.rst showing how to test for common vulnerabilities
• [ ] Document how dependabot.yml integrates with the release process in docs/community/release-process.rst
• [ ] Link security checklist to .github/CODEOWNERS for review on sensitive files

• Add explicit type hints to requests/cookies.py (if not yet fully typed). The typecheck.yml workflow is active but cookie handling is historically complex; improving type coverage here benefits IDE support and catches bugs.: Improves code quality, is self-contained, and the PR review process is predictable for a typed-code contribution.
• Document the less-obvious features in docs/api.rst such as: response.stream parameter behavior, the difference between timeout as float vs tuple, and how to debug SSL certificate issues. Cross-reference them to real examples in the test suite.: These features confuse new users; documentation gaps appear in frequent GitHub issues. Writing docs is low-risk and builds familiarity with the codebase.
• Audit the error messages in requests/exceptions.py and requests/models.py to ensure they guide users toward solutions (e.g., 'ConnectionError: Failed to resolve hostname. Check your DNS and firewall rules.'). Add contextual hints where exceptions are raised.: Error clarity directly impacts developer experience; this is a high-impact, low-complexity change that reduces support burden.

The psf/requests repository demonstrates a strong security posture with established security policies, community guidelines, and CI/CD workflows including CodeQL analysis and linting. No critical vulnerabilities were identified in the visible structure. Primary concerns are around dependency management practices (pinned versions without flexibility for patches) and verification that security documentation is comprehensive. The codebase follows security best practices with automated scanning (codeql-analysis.yml) and a defined issue triage process. Recommendations focus on improving dependency update flexibility and ensuring security policies are comprehensive and well-documented.

• Medium · Pinned Sphinx Dependency Without Security Updates — docs/requirements.txt. The documentation dependency Sphinx==7.2.6 is pinned to a specific version. While pinning can prevent unexpected breakages, it may prevent security updates from being applied automatically. Sphinx 7.2.6 is from 2023 and may have known vulnerabilities that have been patched in newer versions. Fix: Consider using version constraints like Sphinx>=7.2.6,<8.0 to allow security patches while preventing major version breakage. Regularly audit dependencies for known vulnerabilities using tools like pip-audit or safety.
• Low · Missing Security Policy Clarity — .github/SECURITY.md. While a SECURITY.md file exists in .github/, the file structure doesn't show its content. Security policies should be clearly documented and easily discoverable for responsible disclosure. Fix: Ensure SECURITY.md contains clear vulnerability reporting procedures, supported versions, and expected response times for security reports.
• Low · AI Policy Exists But Scope Unclear — .github/AI_POLICY.md. The presence of .github/AI_POLICY.md suggests recent security considerations around AI-generated code, but the policy's content and enforcement mechanisms are not visible. Fix: Ensure the AI policy clearly defines what AI tools are permitted in the codebase, security scanning requirements, and attribution/licensing concerns.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Read in the suggested order before editing unfamiliar code. The reading-order list is computed from the actual import graph, not LLM guesses; reading bottom-up materially reduces wrong-edit risk.
3. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
4. Cite source on changes. When proposing an edit, cite the specific path/to/file.ext:Lstart-Lend you're reasoning about, the same way RepoPilot's own RAG cites code in https://repopilot.app/r/psf/requests.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live psf/requests repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/psf/requests.

What it runs against: a local clone of psf/requests — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in psf/requests | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of psf/requests. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/psf/requests.git
#   cd requests
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of psf/requests and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "psf/requests(\\.git)?\\b" \\
  && ok "origin remote is psf/requests" \\
  || miss "origin remote is not psf/requests (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/requests/__init__.py" \\
  && ok "src/requests/__init__.py" \\
  || miss "missing critical file: src/requests/__init__.py"
test -f "src/requests/sessions.py" \\
  && ok "src/requests/sessions.py" \\
  || miss "missing critical file: src/requests/sessions.py"
test -f "src/requests/adapters.py" \\
  && ok "src/requests/adapters.py" \\
  || miss "missing critical file: src/requests/adapters.py"
test -f "src/requests/models.py" \\
  && ok "src/requests/models.py" \\
  || miss "missing critical file: src/requests/models.py"
test -f "src/requests/auth.py" \\
  && ok "src/requests/auth.py" \\
  || miss "missing critical file: src/requests/auth.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/psf/requests"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Computed from the actual import graph (no LLM). Read in this order to learn the codebase from the foundation up — each step builds on the previous ones.

1. src/requests/compat.py — Foundation: doesn't import anything internally and is imported by 13 other files. Read first to learn the vocabulary.
2. tests/testserver/server.py — Foundation: imported by 3, no internal dependencies of its own.
3. src/requests/structures.py — Built on the foundation; imported by 9 downstream files.
4. src/requests/_internal_utils.py — Built on the foundation; imported by 6 downstream files.
5. src/requests/status_codes.py — Layer 2 — application-level code that wires the lower layers together.

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.