0
# h2
1
2
A pure-Python implementation of the HTTP/2 protocol that provides low-level connection and stream management capabilities. h2 is designed to be embeddable in any Python program, offering a complete HTTP/2 protocol stack without handling network I/O, parsing, or concurrency layers.
3
4
## Package Information
5
6
- **Package Name**: h2
7
- **Language**: Python
8
- **Installation**: `pip install h2`
9
- **Dependencies**: `hyperframe>=6.1,<7`, `hpack>=4.1,<5`
10
11
## Core Imports
12
13
```python
14
from h2.connection import H2Connection
15
from h2.config import H2Configuration
16
```
17
18
Common imports for working with events and exceptions:
19
20
```python
21
from h2.events import RequestReceived, ResponseReceived, DataReceived
22
from h2.exceptions import ProtocolError, StreamClosedError
23
from h2.errors import ErrorCodes
24
```
25
26
## Basic Usage
27
28
```python
29
from h2.connection import H2Connection
30
from h2.config import H2Configuration
31
from h2.events import RequestReceived, ResponseReceived, DataReceived
32
33
# Configure and create connection
34
config = H2Configuration(client_side=True)
35
conn = H2Connection(config=config)
36
37
# Initialize connection
38
conn.initiate_connection()
39
data_to_send = conn.data_to_send()
40
# Send data_to_send over your network connection
41
42
# Send a request
43
conn.send_headers(
44
stream_id=1,
45
headers=[
46
(':method', 'GET'),
47
(':path', '/'),
48
(':scheme', 'https'),
49
(':authority', 'example.com'),
50
]
51
)
52
data_to_send = conn.data_to_send()
53
# Send data_to_send over your network connection
54
55
# Process received data
56
received_data = b"..." # Data from network
57
events = conn.receive_data(received_data)
58
59
for event in events:
60
if isinstance(event, ResponseReceived):
61
print(f"Response headers: {event.headers}")
62
elif isinstance(event, DataReceived):
63
print(f"Response data: {event.data}")
64
# Acknowledge received data for flow control
65
conn.acknowledge_received_data(len(event.data), event.stream_id)
66
```
67
68
## Architecture
69
70
h2 implements a layered HTTP/2 protocol stack:
71
72
- **H2Connection**: Core connection object managing overall HTTP/2 state, frame processing, and multiple streams
73
- **Event System**: Protocol actions generate structured events that applications process
74
- **Settings Management**: HTTP/2 settings negotiation and validation
75
- **Flow Control**: Connection and per-stream flow control window management
76
- **Configuration**: Behavioral control through H2Configuration with validation and normalization options
77
78
This design separates protocol logic from network I/O, allowing integration into any networking framework while providing complete HTTP/2 compliance.
79
80
## Capabilities
81
82
### Connection Management
83
84
Core HTTP/2 connection handling including connection establishment, frame processing, stream management, and connection termination. The H2Connection class provides the primary interface for all HTTP/2 operations.
85
86
```python { .api }
87
class H2Connection:
88
def __init__(self, config: H2Configuration | None = None): ...
89
def initiate_connection(self) -> None: ...
90
def send_headers(self, stream_id: int, headers: list, **kwargs) -> None: ...
91
def send_data(self, stream_id: int, data: bytes, **kwargs) -> None: ...
92
def receive_data(self, data: bytes) -> list[Event]: ...
93
def data_to_send(self, amount: int | None = None) -> bytes: ...
94
```
95
96
[Connection Management](./connection.md)
97
98
### Configuration
99
100
HTTP/2 connection configuration controlling validation, encoding, normalization, and logging behavior. H2Configuration allows fine-tuned control over protocol handling.
101
102
```python { .api }
103
class H2Configuration:
104
def __init__(
105
self,
106
client_side: bool = True,
107
header_encoding: str | None = None,
108
validate_outbound_headers: bool = True,
109
**kwargs
110
): ...
111
```
112
113
[Configuration](./configuration.md)
114
115
### Event System
116
117
Structured events representing HTTP/2 protocol actions and state changes. All connection operations generate events that applications process to handle requests, responses, data, and protocol state changes.
118
119
```python { .api }
120
class RequestReceived(Event):
121
stream_id: int
122
headers: list[Header]
123
124
class ResponseReceived(Event):
125
stream_id: int
126
headers: list[Header]
127
128
class DataReceived(Event):
129
stream_id: int
130
data: bytes
131
flow_controlled_length: int
132
```
133
134
[Event System](./events.md)
135
136
### Exception Handling
137
138
Comprehensive exception hierarchy for HTTP/2 protocol errors, stream errors, and configuration issues. All exceptions include appropriate error codes and context information.
139
140
```python { .api }
141
class H2Error(Exception): ...
142
class ProtocolError(H2Error): ...
143
class StreamClosedError(NoSuchStreamError): ...
144
class FlowControlError(ProtocolError): ...
145
```
146
147
[Exception Handling](./exceptions.md)
148
149
### Settings Management
150
151
HTTP/2 settings negotiation, validation, and state management. Settings control connection behavior and are negotiated between peers during connection establishment.
152
153
```python { .api }
154
class SettingCodes(enum.IntEnum):
155
HEADER_TABLE_SIZE = 0x1
156
ENABLE_PUSH = 0x2
157
MAX_CONCURRENT_STREAMS = 0x3
158
159
class Settings(MutableMapping[Union[SettingCodes, int], int]):
160
def __init__(self, client: bool = True, **kwargs): ...
161
def acknowledge(self) -> dict: ...
162
```
163
164
[Settings Management](./settings.md)
165
166
## Error Codes
167
168
HTTP/2 standard error codes for protocol violations and connection issues:
169
170
```python { .api }
171
class ErrorCodes(enum.IntEnum):
172
NO_ERROR = 0x0
173
PROTOCOL_ERROR = 0x1
174
INTERNAL_ERROR = 0x2
175
FLOW_CONTROL_ERROR = 0x3
176
SETTINGS_TIMEOUT = 0x4
177
STREAM_CLOSED = 0x5
178
FRAME_SIZE_ERROR = 0x6
179
REFUSED_STREAM = 0x7
180
CANCEL = 0x8
181
COMPRESSION_ERROR = 0x9
182
CONNECT_ERROR = 0xa
183
ENHANCE_YOUR_CALM = 0xb
184
INADEQUATE_SECURITY = 0xc
185
HTTP_1_1_REQUIRED = 0xd
186
```