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. 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.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/aio-libs/aiohttp shows verifiable citations alongside every claim.

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.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 20 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ Non-standard license (Other) — review terms

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

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

What it runs against: a local clone of aio-libs/aiohttp — 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 aio-libs/aiohttp | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of aio-libs/aiohttp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/aio-libs/aiohttp.git
#   cd aiohttp
#
# 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 aio-libs/aiohttp and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f ".github/workflows/ci-cd.yml" \\
  && ok ".github/workflows/ci-cd.yml" \\
  || miss "missing critical file: .github/workflows/ci-cd.yml"
test -f "setup.py" \\
  && ok "setup.py" \\
  || miss "missing critical file: setup.py"
test -f "pyproject.toml" \\
  && ok "pyproject.toml" \\
  || miss "missing critical file: pyproject.toml"
test -f ".mypy.ini" \\
  && ok ".mypy.ini" \\
  || miss "missing critical file: .mypy.ini"
test -f "CHANGES/.TEMPLATE.rst" \\
  && ok "CHANGES/.TEMPLATE.rst" \\
  || miss "missing critical file: CHANGES/.TEMPLATE.rst"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/aio-libs/aiohttp"
  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).

aiohttp is a production-grade async HTTP client and server framework built on asyncio for Python 3.8+. It provides out-of-the-box support for HTTP/1.1 requests, WebSocket connections, middleware-based routing, and efficient streaming, allowing developers to build high-performance concurrent web services without callback hell. Monolithic structure: core async HTTP client/server logic likely lives in aiohttp/ root package (inferred from module structure), with CI workflows in .github/workflows/, documentation configuration in .readthedocs.yml, and extensive changelog management via CHANGES/ directory (fragment-based versioning). Cython-optimized I/O paths are built separately (.coveragerc-cython.toml, code-compiled modules) alongside pure Python fallbacks.

Python developers building async web services (microservices, APIs, real-time applications) and those needing a performant async HTTP client as an alternative to requests. Contributors are typically Python library maintainers and infrastructure engineers who need async-first HTTP handling with WebSocket support.

aiohttp is mature and production-ready with 15k+ GitHub stars, active CI/CD pipelines (.github/workflows/ci-cd.yml), comprehensive test coverage (codecov.yml present), and recent changelog entries (CHANGES/ directory shows work through 2024). It is actively maintained with frequent feature additions (11989.feature.rst, 11966.feature.rst) and bugfixes, though some breaking changes have been introduced recently (11601.breaking.rst, 11012.breaking.rst).

The codebase shows moderate risk: recent breaking changes (11601.breaking.rst, 11012.breaking.rst) may impact downstream users, and the majority of code is Python (2.9M lines) with Cython extensions (45k lines) requiring C compiler knowledge for builds. The polyglot nature (Python/Cython/C) plus .git-blame-ignore-revs suggests complex refactoring history; contributors should expect occasional structural churn. Dependency management uses .pip-tools.toml suggesting pinned transitive dependencies.

Recent work includes feature additions (11989.feature.rst, 11268.feature.rst, 11681.feature.rst, 11763-11766.feature.rst), bugfixes especially around reliability (10600.bugfix.rst, 10683.bugfix.rst, 10753.bugfix.rst, 11761.bugfix.rst), documentation updates, and contrib ecosystem work (11826.contrib.rst). Breaking changes are being actively managed through version milestones (.cherry_picker.toml suggests backport workflow). CI/CD is sophisticated with CodeQL security scanning, auto-merge workflows, and label-based automation.

Clone the repository: git clone https://github.com/aio-libs/aiohttp.git && cd aiohttp. Install with dev dependencies: pip install -e '.[speedups]' (speedups include Cython optimizations). Run tests: make test (Makefile present in root). Build docs: make docs (ReadTheDocs configuration present).

Daily commands: Start dev server with example: python examples/server_simple.py (from README). For client development, tests run via pytest or make test. Dev tools configured in .pre-commit-config.yaml and .mypy.ini for type checking. Use Makefile targets: make lint, make test, make coverage for common tasks.

• .github/workflows/ci-cd.yml — Primary CI/CD pipeline defining build, test, and release workflows for all supported Python versions and platforms.
• setup.py — Package entry point and dependency configuration; all contributors must understand build requirements and C extension compilation.
• pyproject.toml — Modern Python project configuration including test dependencies, code quality tools, and build system specification.
• .mypy.ini — Type checking configuration enforced across the codebase; critical for understanding type safety expectations.
• CHANGES/.TEMPLATE.rst — Changelog entry template defining the release documentation process for all contributions.
• .pre-commit-config.yaml — Pre-commit hooks enforcing code quality and formatting standards on every commit.
• .github/CODEOWNERS — Code ownership mapping defining which maintainers review specific modules and features.

Add a new HTTP client feature or capability

1. Define the feature interface in aiohttp/client.py by adding methods to ClientSession or creating a new request parameter (aiohttp/client.py)
2. Implement request handling logic in aiohttp/client_reqrep.py for ClientRequest processing (aiohttp/client_reqrep.py)
3. Add response handling in aiohttp/client_reqrep.py for ClientResponse if response parsing is affected (aiohttp/client_reqrep.py)
4. Update protocol handling in aiohttp/protocol.py if low-level HTTP semantics change (aiohttp/protocol.py)
5. Add a changelog entry in CHANGES/ directory describing the feature (CHANGES/.TEMPLATE.rst)

Add a new web server route or view handler

1. Define route patterns using decorators from aiohttp/web_routedef.py in your application (aiohttp/web_routedef.py)
2. Create view function or class accessing request data from aiohttp/web_request.py (aiohttp/web_request.py)
3. Return response using aiohttp/web_response.py response classes (aiohttp/web_response.py)
4. Register route with dispatcher via aiohttp/web_urldispatcher.py URL pattern matching (aiohttp/web_urldispatcher.py)

Add custom middleware or request processing

1. Implement middleware factory function following patterns in aiohttp/web_middlewares.py (aiohttp/web_middlewares.py)
2. Register middleware with app via app.middlewares list documented in aiohttp/web.py (aiohttp/web.py)
3. Access request/response objects from aiohttp/web_request.py and aiohttp/web_response.py as needed (aiohttp/web_request.py)

Handle WebSocket connections

1. Use server-side WebSocket handler from aiohttp/ws_server.py in web route (aiohttp/ws_server.py)
2. For client, use WebSocket connection from aiohttp/ws_client.py via ClientSession (aiohttp/ws_client.py)
3. Manage connection lifecycle and message sending/receiving with WebSocket protocol (aiohttp/protocol.py)

• asyncio — Enables high-concurrency I/O with cooperative multitasking; aiohttp's entire event loop model depends on it
• yarl (URL parsing) — Immutable URL handling with RFC 3986 compliance; critical for URL normalization in both client and server
• multidict — Efficient multi-value dictionary for HTTP headers that can have multiple values per key
• C extensions (via Cython) — Performance-critical path optimization for HTTP parsing and protocol handling; compiled via setup.py
• Python type hints + mypy — Static type safety across the async codebase; enforced via .mypy.ini configuration

• Async-only API with no synchronous fallback

  • Why: Simplifies codebase and avoids threading complexity in async context
  • Consequence: Cannot be used in synchronous applications; requires asyncio-compatible environment

• Connection pooling at Connector level

  • Why: Maximizes connection reuse across concurrent requests
  • Consequence: More complex pool lifecycle management; potential for connection leaks if not properly closed

• Streaming response body by default

  • Why: Prevents loading large responses entirely into memory
  • Consequence: Response must be explicitly read/iterated; easier to forget resource cleanup

• Middleware chain before route matching

  • Why: Allows cross-cutting concerns (auth, logging) without modifying individual handlers
  • Consequence: Middleware runs even for 404 routes; cannot access matched route parameters from middleware

• Does not provide built-in authentication or authorization mechanisms
• Does not handle database connections or ORM integration
• Does not support HTTP/2 server mode (client mode only in some versions)
• Does not provide distributed session management (single-server only by default)
• Does not include built-in rate limiting or throttling

Cython build overhead: first install or test run will compile C extensions, requiring a C compiler (gcc/clang/MSVC) and development headers. Watch .coveragerc-cython.toml — coverage reporting differs for Cython-compiled vs. pure Python paths. The fragment-based changelog (CHANGES/) is mandatory: PRs must include a CHANGES/NNNNN.{bugfix|feature|misc|breaking|doc|contrib}.rst file or CI will fail. AsyncIO event loop behavior varies by OS (Windows uses ProactorEventLoop by default, others use EpollEventLoop); tests may be platform-sensitive. CodeQL security scanning is active in CI—no hardcoded secrets or unsafe patterns will merge.

• Connection Pooling — aiohttp maintains HTTP connection pools to reuse TCP sockets across requests, reducing latency and improving throughput; understanding pool sizing and eviction is critical for tuning client performance
• WebSocket State Machine — aiohttp's WebSocket implementation manages bidirectional message framing and connection states; contributors need to understand frame types, close codes, and backpressure handling
• Middleware Pipeline — aiohttp server uses middleware chaining for request/response interception (similar to ASGI); plugins for logging, auth, CORS live here
• Streaming and Backpressure — aiohttp handles large request/response bodies via streaming (chunked reading/writing); misunderstanding backpressure can cause memory leaks or stalled uploads
• Cython Optimization — Critical I/O paths (HTTP parsing, multidict ops) are JIT-compiled to C via Cython; modifying these requires understanding .pyx files and C Python API
• Event Loop Integration — aiohttp is tightly coupled to asyncio's event loop; platform-specific loop implementations (ProactorEventLoop on Windows, EpollEventLoop on Linux) cause subtle test failures if ignored

• encode/httpx — Modern async HTTP client emphasizing API simplicity and async/await; direct competitor to aiohttp's client side
• pallets/flask — Traditional sync HTTP server framework; aiohttp is Flask's spiritual async successor with similar routing/middleware model
• encode/starlette — Lightweight async web framework built on ASGI standard; uses similar async patterns but with different routing design (competes in server space)
• aio-libs/multidict — Sister project in aio-libs org; provides optimized dict-like container for HTTP headers/query params used internally by aiohttp
• aio-libs/yarl — Sister project for URL handling; aiohttp depends on it for URL parsing and manipulation (listed in async ecosystem)

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 test coverage for CHANGES fragment validation

The CHANGES directory uses a fragment-based changelog system (.bugfix.rst, .feature.rst, .breaking.rst, etc. files) with a .TEMPLATE.rst and .gitignore. There's no apparent validation workflow to ensure contributors follow the correct naming convention and format before merging. Adding a CI check (GitHub Action) to validate fragment filenames, content structure, and prevent malformed entries would catch issues early and reduce maintainer burden.

• [ ] Create a new GitHub Actions workflow in .github/workflows/changelog-validate.yml
• [ ] Implement validation logic to check: fragment filename format (PR number + category), required metadata, no empty fragments
• [ ] Reference the .TEMPLATE.rst structure to define validation rules
• [ ] Integrate with existing CI pipeline to run on PRs that modify CHANGES/ directory
• [ ] Document the changelog contribution process in a CHANGES/README.md or CONTRIBUTING guide section

Implement pre-commit hook configuration for aiohttp development

The repo has .pre-commit-config.yaml but it's minimal. Given the presence of .mypy.ini, .lgtm.yml, and complex test coverage requirements (.coveragerc-cython.toml, .coveragerc.toml), developers would benefit from a comprehensive pre-commit setup that enforces type checking, formatting, and linting before commits. This reduces CI friction and catches issues locally.

• [ ] Expand .pre-commit-config.yaml with hooks for: mypy (using existing .mypy.ini), black/ruff for formatting, flake8 or pylint
• [ ] Add hooks to validate CHANGES fragments match naming convention
• [ ] Include a hook to ensure no direct modifications to CHANGES/CHANGES.rst (should use fragments)
• [ ] Document setup instructions in CONTRIBUTING.md or .github/CONTRIBUTING section
• [ ] Test the config locally against a sample PR workflow

Add integration tests for asyncio event loop handling across platforms

As an async framework for Python, aiohttp must handle different asyncio implementations (ProactorEventLoop on Windows, SelectorEventLoop on Unix, uvloop on some installations). The file structure shows comprehensive test coverage but no dedicated test module explicitly validating platform-specific event loop behaviors. Adding platform-specific integration tests would catch subtle concurrency bugs early.

• [ ] Create tests/test_event_loop_integration.py with parameterized tests for different event loop implementations
• [ ] Test client/server behavior under SelectorEventLoop, ProactorEventLoop, and optionally uvloop
• [ ] Add CI matrix in .github/workflows/ci-cd.yml to run tests on Windows (ProactorEventLoop), Linux (SelectorEventLoop), and macOS
• [ ] Test edge cases: loop cleanup, task cancellation, connection handling across event loop types
• [ ] Document findings in docs/ regarding event loop compatibility

• Add missing type hints to pure-Python fallback implementations in aiohttp/ (especially for WebSocket state machines and connection pool logic). See .mypy.ini for strictness level. Benefit: improves IDE support and static analysis.
• Expand docstring examples in the main client/server modules to match the README examples (e.g., ClientSession, WebSocketResponse). Add integration tests validating those examples still run. Benefit: reduces doc-to-code drift and helps new users.
• Audit and add missing test coverage for Cython-optimized code paths (marked in .coveragerc-cython.toml). Create platform-specific test fixtures for Windows vs. Unix event loop behavior. Benefit: improves reliability on diverse platforms.

The aiohttp repository demonstrates a reasonable security posture with CI/CD workflows, CodeQL integration, and active maintenance (evidenced by multiple change files). However, a comprehensive security assessment cannot be completed without access to the actual dependency file (setup.py, pyproject.toml, or requirements.txt) to identify vulnerable packages. The project maintains security best practices with automated code analysis, but dependency audit and regular security updates are critical given its role as a widely-used HTTP framework. No hardcoded secrets or obvious injection vulnerabilities are apparent from the file structure alone, but the actual source code requires detailed review for authentication, authorization, and input validation implementations.

• Medium · Missing Dependency File for Analysis — setup.py, setup.cfg, pyproject.toml, or requirements.txt (not provided). The dependency/package file content was not provided for analysis. This prevents identification of known vulnerable dependencies or outdated packages that may have security flaws. Fix: Provide the complete dependency manifest file. Run pip audit or use tools like safety to scan for known vulnerabilities in dependencies. Regularly update dependencies to patch security issues.
• Low · Potential Sensitive Configuration in Repository — .mypy.ini, .pre-commit-config.yaml, .readthedocs.yml. The presence of files like .editorconfig, .mypy.ini, and .pre-commit-config.yaml, while not directly security-critical, indicates the repository contains development configuration. Ensure no credentials are accidentally committed to git. Fix: Ensure .gitignore includes patterns for sensitive files (.env, *.key, secrets/, etc.). Use pre-commit hooks to prevent credential commits. Consider using git-secrets or similar tools.
• Low · CodeQL Configuration Present — .github/codeql.yml, .github/workflows/codeql.yml. While positive, the presence of .github/codeql.yml and security workflow configurations suggests static analysis is in place. However, the actual configuration content should be reviewed to ensure comprehensive scanning. Fix: Review CodeQL configuration to ensure all high-severity checks are enabled. Ensure SAST scanning includes authentication checks, injection vulnerabilities, and cryptographic weakness detection.
• Low · Framework Security Considerations — aiohttp core library (not directly visible in file listing). As an HTTP client/server framework, aiohttp is responsible for handling web traffic. The framework should implement secure defaults for headers, cookie handling, and request validation to prevent downstream vulnerabilities in applications using it. Fix: Review security best practices: 1) Implement secure-by-default HTTP header handling, 2) Validate and sanitize all user inputs, 3) Ensure HTTPS support with certificate validation, 4) Implement proper CSRF protection mechanisms, 5) Use parameterized queries if SQL is involved, 6) Implement rate limiting and DoS protection.

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

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

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