0
# Hyperframe
1

2
A pure-Python HTTP/2 framing library that provides comprehensive frame type support for creating, serializing, and parsing HTTP/2 frames without external dependencies. Hyperframe offers complete implementations of all standard HTTP/2 frame types with proper flag handling, stream association management, and built-in validation for maximum reusability across HTTP/2 implementations.
3

4
## Package Information
5

6
- **Package Name**: hyperframe
7
- **Language**: Python
8
- **Installation**: `pip install hyperframe`
9
- **Type Support**: Fully typed with `py.typed` marker
10

11
## Core Imports
12

13
```python
14
import hyperframe
15
```
16

17
For working with specific frame types:
18

19
```python
20
from hyperframe.frame import (
21
    Frame, DataFrame, HeadersFrame, PriorityFrame, RstStreamFrame,
22
    SettingsFrame, PushPromiseFrame, PingFrame, GoAwayFrame,
23
    WindowUpdateFrame, ContinuationFrame, AltSvcFrame, ExtensionFrame
24
)
25
```
26

27
For exception handling:
28

29
```python
30
from hyperframe.exceptions import (
31
    HyperframeError, UnknownFrameError, InvalidFrameError,
32
    InvalidDataError, InvalidPaddingError
33
)
34
```
35

36
## Basic Usage
37

38
```python
39
from hyperframe.frame import DataFrame, Frame
40

41
# Create a DATA frame
42
data_frame = DataFrame(stream_id=1, data=b"Hello, HTTP/2!")
43
data_frame.flags.add("END_STREAM")
44

45
# Serialize frame to binary
46
frame_bytes = data_frame.serialize()
47

48
# Parse frame from binary data
49
parsed_frame, length = Frame.parse_frame_header(frame_bytes[:9])
50
parsed_frame.parse_body(memoryview(frame_bytes[9:9 + length]))
51

52
print(f"Parsed frame: {parsed_frame}")
53
print(f"Frame data: {parsed_frame.data}")
54
```
55

56
## Architecture
57

58
Hyperframe uses an object-oriented design with inheritance hierarchies:
59

60
- **Frame**: Base class for all HTTP/2 frames with common serialization and parsing logic
61
- **Mixins**: `Padding` and `Priority` mixins provide shared functionality for frames that support these features
62
- **Concrete Frame Classes**: Specific implementations for each HTTP/2 frame type (DATA, HEADERS, SETTINGS, etc.)
63
- **Flags**: Type-safe flag management system ensuring only valid flags are set per frame type
64
- **Exceptions**: Comprehensive error handling for parsing failures and invalid frame content
65

66
This design provides maximum flexibility for HTTP/2 implementations while maintaining strict compliance with the HTTP/2 specification.
67

68
## Capabilities
69

70
### Frame Parsing and Creation
71

72
Core functionality for parsing HTTP/2 frames from binary data and creating new frames with proper validation and serialization support.
73

74
```python { .api }
75
class Frame:
76
    def __init__(self, stream_id: int, flags: Iterable[str] = ()) -> None: ...
77
    
78
    @staticmethod
79
    def parse_frame_header(header: memoryview, strict: bool = False) -> tuple[Frame, int]: ...
80
    
81
    @staticmethod
82
    def explain(data: memoryview) -> tuple[Frame, int]: ...
83
    
84
    def serialize() -> bytes: ...
85
    def parse_body(data: memoryview) -> None: ...
86
```
87

88
[Frame Operations](./frame-operations.md)
89

90
### Data and Header Frames
91

92
Implementation of HTTP/2 DATA and HEADERS frames for carrying application data and HTTP headers with support for padding, priority information, and proper stream association.
93

94
```python { .api }
95
class DataFrame(Padding, Frame):
96
    def __init__(self, stream_id: int, data: bytes = b"", **kwargs) -> None: ...
97
    
98
    @property
99
    def flow_controlled_length(self) -> int: ...
100

101
class HeadersFrame(Padding, Priority, Frame):
102
    def __init__(self, stream_id: int, data: bytes = b"", **kwargs) -> None: ...
103
```
104

105
[Data and Headers](./data-headers.md)
106

107
### Control Frames
108

109
HTTP/2 control frames for connection and stream management including SETTINGS, RST_STREAM, PRIORITY, PING, GOAWAY, and WINDOW_UPDATE frames.
110

111
```python { .api }
112
class SettingsFrame(Frame):
113
    def __init__(self, stream_id: int = 0, settings: dict[int, int] | None = None, **kwargs) -> None: ...
114
    
115
    # Settings constants
116
    HEADER_TABLE_SIZE: int
117
    ENABLE_PUSH: int
118
    MAX_CONCURRENT_STREAMS: int
119
    INITIAL_WINDOW_SIZE: int
120
    MAX_FRAME_SIZE: int
121
    MAX_HEADER_LIST_SIZE: int
122
    ENABLE_CONNECT_PROTOCOL: int
123
```
124

125
[Control Frames](./control-frames.md)
126

127
### Extension and Advanced Features
128

129
Support for PUSH_PROMISE, CONTINUATION, ALTSVC frames and extension frames for handling unknown frame types, plus comprehensive flag management and error handling.
130

131
```python { .api }
132
class ExtensionFrame(Frame):
133
    def __init__(self, type: int, stream_id: int, flag_byte: int = 0x0, body: bytes = b"", **kwargs) -> None: ...
134

135
class Flags:
136
    def __init__(self, defined_flags: Iterable[Flag]) -> None: ...
137
    def add(self, value: str) -> None: ...
138
    def discard(self, value: str) -> None: ...
139
```
140

141
[Advanced Features](./advanced-features.md)
142

143
## Package Constants
144

145
```python { .api }
146
__version__: str  # "6.1.0"
147
FRAME_MAX_LEN: int  # 16384 - Maximum initial frame length
148
FRAME_MAX_ALLOWED_LEN: int  # 16777215 - Maximum allowed frame length
149
FRAMES: dict[int, type[Frame]]  # Mapping of frame type bytes to frame classes
150
```
151

152
## Exception Hierarchy
153

154
```python { .api }
155
class HyperframeError(Exception):
156
    """Base class for all hyperframe exceptions."""
157

158
class UnknownFrameError(HyperframeError):
159
    def __init__(self, frame_type: int, length: int) -> None: ...
160
    
161
class InvalidFrameError(HyperframeError):
162
    """Parsing failed due to incorrect data layout."""
163

164
class InvalidDataError(HyperframeError):
165
    """Frame content violates the specification."""
166

167
class InvalidPaddingError(HyperframeError):
168
    """Frame padding is invalid."""
169
```