# python-hyper/h11 architecture

> Architecture diagram of the GitHub repository python-hyper/h11, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/python-hyper/h11
- Repository: https://github.com/python-hyper/h11

## Overview

h11 is a pure-Python, bring-your-own-I/O HTTP/1.1 protocol library, not a network client or server. An application feeds received bytes to a Connection and consumes parsed events; to send, it supplies events and writes the returned bytes through its own I/O layer. Connection coordinates role-aware protocol state, parsing, and serialization, covering message framing, headers, keep-alive, and protocol switching. The graph reflects README-described behavior and sampled imports; unsampled implementation details are not inferred.

Main entry points: [`h11/_connection.py`](https://github.com/python-hyper/h11/blob/master/h11/_connection.py) (Connection), [`h11/__init__.py`](https://github.com/python-hyper/h11/blob/master/h11/__init__.py) (Public API), [`h11/_readers.py`](https://github.com/python-hyper/h11/blob/master/h11/_readers.py) (Message Readers), [`h11/_headers.py`](https://github.com/python-hyper/h11/blob/master/h11/_headers.py) (Header Handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_public_api["Public API<br/>[__init__.py]"]
  node_version["Version Metadata<br/>[_version.py]"]
end

subgraph group_protocol["Protocol Engine"]
  node_connection["Connection<br/>[_connection.py]"]
  node_events["HTTP Events<br/>[_events.py]"]
  node_state["Connection State<br/>[_state.py]"]
  node_readers["Message Readers<br/>[_readers.py]"]
  node_writers["Message Writers<br/>[_writers.py]"]
end

subgraph group_support["Parsing and Validation"]
  node_receive_buffer["Receive Buffer<br/>[_receivebuffer.py]"]
  node_headers["Header Handling<br/>[_headers.py]"]
  node_abnf["HTTP Grammar<br/>[_abnf.py]"]
  node_utilities["Protocol Utilities<br/>[_util.py]"]
end

node_application(("Application / I/O"))

node_application -->|"uses API"| node_public_api
node_public_api -->|"exposes"| node_connection
node_public_api -->|"exposes"| node_events
node_public_api -->|"exposes roles"| node_state
node_public_api -->|"exposes errors"| node_utilities
node_public_api -->|"uses version"| node_version
node_application -->|"passes bytes/events"| node_connection
node_connection -->|"checks transitions"| node_state
node_connection -->|"processes events"| node_events
node_connection -->|"dispatches parsing"| node_readers
node_connection -->|"dispatches serialization"| node_writers
node_readers -->|"consumes bytes"| node_receive_buffer
node_readers -->|"creates events"| node_events
node_readers -->|"parses headers"| node_headers
node_writers -->|"serializes events"| node_events
node_writers -->|"writes headers"| node_headers
node_writers -->|"selects by state"| node_state
node_events -->|"normalizes headers"| node_headers
node_headers -->|"validates grammar"| node_abnf
node_headers -->|"converts and validates"| node_utilities
node_readers -->|"matches syntax"| node_abnf
node_readers -->|"selects by state"| node_state
node_connection -->|"buffers input"| node_receive_buffer
node_connection -->|"translates errors"| node_utilities

click node_public_api "https://github.com/python-hyper/h11/blob/master/h11/__init__.py"
click node_connection "https://github.com/python-hyper/h11/blob/master/h11/_connection.py"
click node_events "https://github.com/python-hyper/h11/blob/master/h11/_events.py"
click node_state "https://github.com/python-hyper/h11/blob/master/h11/_state.py"
click node_readers "https://github.com/python-hyper/h11/blob/master/h11/_readers.py"
click node_writers "https://github.com/python-hyper/h11/blob/master/h11/_writers.py"
click node_receive_buffer "https://github.com/python-hyper/h11/blob/master/h11/_receivebuffer.py"
click node_headers "https://github.com/python-hyper/h11/blob/master/h11/_headers.py"
click node_abnf "https://github.com/python-hyper/h11/blob/master/h11/_abnf.py"
click node_utilities "https://github.com/python-hyper/h11/blob/master/h11/_util.py"
click node_version "https://github.com/python-hyper/h11/blob/master/h11/_version.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_version toneBlue
class node_connection,node_events,node_state,node_readers,node_writers toneAmber
class node_receive_buffer,node_headers,node_abnf,node_utilities toneMint
class node_application toneIndigo
```

## Components

### Public API

- [Public API](https://github.com/python-hyper/h11/blob/master/h11/__init__.py): `h11/__init__.py`
- [Version Metadata](https://github.com/python-hyper/h11/blob/master/h11/_version.py): `h11/_version.py`

### Protocol Engine

- [Connection](https://github.com/python-hyper/h11/blob/master/h11/_connection.py): `h11/_connection.py`
- [HTTP Events](https://github.com/python-hyper/h11/blob/master/h11/_events.py): `h11/_events.py`
- [Connection State](https://github.com/python-hyper/h11/blob/master/h11/_state.py): `h11/_state.py`
- [Message Readers](https://github.com/python-hyper/h11/blob/master/h11/_readers.py): `h11/_readers.py`
- [Message Writers](https://github.com/python-hyper/h11/blob/master/h11/_writers.py): `h11/_writers.py`

### Parsing and Validation

- [Receive Buffer](https://github.com/python-hyper/h11/blob/master/h11/_receivebuffer.py): `h11/_receivebuffer.py`
- [Header Handling](https://github.com/python-hyper/h11/blob/master/h11/_headers.py): `h11/_headers.py`
- [HTTP Grammar](https://github.com/python-hyper/h11/blob/master/h11/_abnf.py): `h11/_abnf.py`
- [Protocol Utilities](https://github.com/python-hyper/h11/blob/master/h11/_util.py): `h11/_util.py`

### Other components

- **Application / I/O**

## Connections

- Application / I/O → Public API: uses API (evidence: `README.rst`)
- Public API → Connection: exposes (evidence: `h11/__init__.py`)
- Public API → HTTP Events: exposes (evidence: `h11/__init__.py`)
- Public API → Connection State: exposes roles (evidence: `h11/__init__.py`)
- Public API → Protocol Utilities: exposes errors (evidence: `h11/__init__.py`)
- Public API → Version Metadata: uses version (evidence: `h11/__init__.py`)
- Application / I/O → Connection: passes bytes/events (evidence: `README.rst`)
- Connection → Connection State: checks transitions (evidence: `h11/_connection.py`)
- Connection → HTTP Events: processes events (evidence: `h11/_connection.py`)
- Connection → Message Readers: dispatches parsing (evidence: `h11/_connection.py`)
- Connection → Message Writers: dispatches serialization (evidence: `h11/_connection.py`)
- Message Readers → Receive Buffer: consumes bytes (evidence: `h11/_readers.py`)
- Message Readers → HTTP Events: creates events (evidence: `h11/_readers.py`)
- Message Readers → Header Handling: parses headers (evidence: `h11/_readers.py`)
- Message Writers → HTTP Events: serializes events (evidence: `h11/_writers.py`)
- Message Writers → Header Handling: writes headers (evidence: `h11/_writers.py`)
- Message Writers → Connection State: selects by state (evidence: `h11/_writers.py`)
- HTTP Events → Header Handling: normalizes headers (evidence: `h11/_events.py`)
- Header Handling → HTTP Grammar: validates grammar (evidence: `h11/_headers.py`)
- Header Handling → Protocol Utilities: converts and validates (evidence: `h11/_headers.py`)
- Message Readers → HTTP Grammar: matches syntax (evidence: `h11/_readers.py`)
- Message Readers → Connection State: selects by state (evidence: `h11/_readers.py`)
- Connection → Receive Buffer: buffers input (evidence: `h11/_connection.py`)
- Connection → Protocol Utilities: translates errors (evidence: `h11/_connection.py`)
