hyperframe

hyperframe implements HTTP/2’s low-level framing layer: the fixed-format binary frames (HEADERS, DATA, SETTINGS, WINDOW_UPDATE, PING, GOAWAY, and the rest of the spec’s frame types) that carry every piece of HTTP/2 traffic. It provides classes to parse raw bytes into typed frame objects and to serialize frame objects back into bytes, along with the flag-handling logic each frame type requires.

As the lowest layer of the three python-hyper sibling libraries, hyperframe sits underneath both hpack (header compression) and h2 (the full protocol state machine) — h2 depends on hyperframe directly to read and write frames off the wire, while itself remaining agnostic to the transport those bytes travel over.

What You Get

• Typed Frame subclasses for every HTTP/2 frame type (HeadersFrame, DataFrame, SettingsFrame, WindowUpdateFrame, PingFrame, GoAwayFrame, RstStreamFrame, and more)
• A flags.py module implementing per-frame-type flag semantics (END_STREAM, END_HEADERS, PADDED, PRIORITY, ACK) with validation
• Bidirectional parse/serialize methods so frames can be read off the wire and written back out symmetrically
• Dedicated exceptions.py types for malformed or invalid frame data
• Used directly by h2 as its frame-parsing layer, forming the base of the python-hyper HTTP/2 stack

Common Use Cases

• Parsing and constructing HTTP/2 frames as part of implementing the HTTP/2 protocol (typically consumed via h2 rather than directly)
• Building low-level HTTP/2 traffic analysis or debugging tools that need to decode individual frames off a captured stream
• Writing HTTP/2 conformance tests that construct specific malformed or edge-case frames to verify protocol handling
• Any project implementing a partial or custom subset of HTTP/2 framing without adopting the full h2 state machine

Under The Hood

Architecture - frame.py defines a Frame base class and one subclass per HTTP/2 frame type, each implementing parse_body()/serialize() for that frame’s specific binary layout, while flags.py centralizes the flag bitmask logic shared across frame types so each subclass only declares which flags it supports. Tech Stack - Pure Python with no runtime dependencies, the smallest and most narrowly scoped of the three python-hyper packages (4 source modules total). Code Quality - 3 test files cover frame parsing, serialization round-tripping, and flag validation, with CI and Codecov badges tracked in the README; the minimal module count keeps the entire framing layer auditable in a single sitting. API Design - Each frame type is a small, self-describing class matching the HTTP/2 spec’s frame definitions one-to-one, so the API surface is essentially one class per frame type with parse/serialize symmetry — narrow in scope but very predictable for anyone cross-referencing the HTTP/2 RFC.