0
# h11
1

2
A pure-Python, bring-your-own-I/O implementation of HTTP/1.1 that focuses on correctly parsing and generating HTTP messages at the byte level. h11 follows a "bring-your-own-I/O" architecture, containing no networking code and integrating with any network framework (synchronous, asynchronous, threaded, etc.). The library provides robust RFC 7230 compliant parsing with linear-time algorithms, bounded memory usage, and comprehensive spec conformance while remaining lightweight at ~800 lines of code.
3

4
## Package Information
5

6
- **Package Name**: h11
7
- **Language**: Python
8
- **Installation**: `pip install h11`
9

10
## Core Imports
11

12
```python
13
import h11
14
```
15

16
Common usage imports:
17

18
```python
19
from h11 import Connection, CLIENT, SERVER, Request, Response, Data, EndOfMessage
20
```
21

22
## Basic Usage
23

24
```python
25
import h11
26

27
# Create a client connection
28
conn = h11.Connection(h11.CLIENT)
29

30
# Create and send a request
31
req = h11.Request(method=b'GET', target=b'/', headers=[(b'host', b'example.com')])
32
data = conn.send(req)
33
# Send data over your socket/transport
34

35
# End the request message
36
eom = h11.EndOfMessage()
37
data = conn.send(eom)
38
# Send data over your socket/transport
39

40
# Process incoming response data
41
conn.receive_data(received_bytes)
42
while True:
43
    event = conn.next_event()
44
    if event is h11.NEED_DATA:
45
        # Need more data from socket
46
        break
47
    elif isinstance(event, h11.Response):
48
        print(f"Response status: {event.status_code}")
49
    elif isinstance(event, h11.Data):
50
        print(f"Body data: {event.data}")
51
    elif isinstance(event, h11.EndOfMessage):
52
        print("Response complete")
53
        break
54
```
55

56
## Architecture
57

58
h11 implements a symmetric state machine architecture where the same events are used for both client and server implementations:
59

60
- **Connection**: Central state machine managing HTTP/1.1 protocol flow
61
- **Events**: Immutable objects representing HTTP message components (Request, Response, Data, etc.)
62
- **States**: Connection states tracking protocol progression (IDLE, SEND_BODY, DONE, etc.)
63
- **Roles**: CLIENT and SERVER roles with symmetric event handling
64
- **Bring-Your-Own-I/O**: No networking dependencies, works with any I/O framework
65

66
The symmetric design enables the same events to represent HTTP requests and responses, making it suitable for clients, servers, proxies, and testing tools.
67

68
## Capabilities
69

70
### Connection Management
71

72
Core connection handling and state management for HTTP/1.1 protocol implementation.
73

74
```python { .api }
75
class Connection:
76
    def __init__(self, our_role, max_incomplete_event_size=16384): ...
77
    def next_event(self): ...
78
    def send(self, event): ...
79
    def send_with_data_passthrough(self, event): ...
80
    def receive_data(self, data): ...
81
    def start_next_cycle(self): ...
82
    def send_failed(self): ...
83

84
# Connection control sentinels
85
class NEED_DATA: ...
86
class PAUSED: ...
87
```
88

89
[Connection Management](./connection.md)
90

91
### HTTP Events
92

93
Event classes representing different parts of HTTP messages - requests, responses, data, and connection lifecycle.
94

95
```python { .api }
96
class Event: ...
97
class Request(Event): ...
98
class InformationalResponse(Event): ...
99
class Response(Event): ...
100
class Data(Event): ...
101
class EndOfMessage(Event): ...
102
class ConnectionClosed(Event): ...
103
```
104

105
[HTTP Events](./events.md)
106

107
### Protocol States
108

109
State constants and role definitions for managing HTTP/1.1 connection lifecycle and protocol compliance.
110

111
```python { .api }
112
# Role constants
113
CLIENT = ...
114
SERVER = ...
115

116
# Connection state constants
117
IDLE = ...
118
SEND_RESPONSE = ...
119
SEND_BODY = ...
120
DONE = ...
121
MUST_CLOSE = ...
122
CLOSED = ...
123
ERROR = ...
124
SWITCHED_PROTOCOL = ...
125
```
126

127
[Protocol States](./states.md)
128

129
### Exception Handling
130

131
Protocol error hierarchy for handling HTTP/1.1 violations and connection errors.
132

133
```python { .api }
134
class ProtocolError(Exception): ...
135
class LocalProtocolError(ProtocolError): ...
136
class RemoteProtocolError(ProtocolError): ...
137
```
138

139
[Exception Handling](./exceptions.md)
140

141
## Types
142

143
```python { .api }
144
# Type aliases for headers
145
Headers = List[Tuple[bytes, bytes]]
146

147
# Event union type
148
Event = Union[
149
    Request, InformationalResponse, Response, 
150
    Data, EndOfMessage, ConnectionClosed
151
]
152

153
# State machine result types
154
NextEventResult = Union[Event, Type[NEED_DATA], Type[PAUSED]]
155
SendResult = Optional[bytes]
156
SendWithDataResult = Optional[List[bytes]]
157
```