or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdcontrol-frames.mddata-headers.mdframe-operations.mdindex.md
tile.json

tessl/pypi-hyperframe

Pure-Python HTTP/2 framing library providing comprehensive frame type support for creating, serializing, and parsing HTTP/2 frames.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/hyperframe@6.1.x

To install, run

npx @tessl/cli install tessl/pypi-hyperframe@6.1.0

index.mddocs/

Hyperframe

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.

Package Information

  • Package Name: hyperframe
  • Language: Python
  • Installation: pip install hyperframe
  • Type Support: Fully typed with py.typed marker

Core Imports

import hyperframe

For working with specific frame types:

from hyperframe.frame import (
    Frame, DataFrame, HeadersFrame, PriorityFrame, RstStreamFrame,
    SettingsFrame, PushPromiseFrame, PingFrame, GoAwayFrame,
    WindowUpdateFrame, ContinuationFrame, AltSvcFrame, ExtensionFrame
)

For exception handling:

from hyperframe.exceptions import (
    HyperframeError, UnknownFrameError, InvalidFrameError,
    InvalidDataError, InvalidPaddingError
)

Basic Usage

from hyperframe.frame import DataFrame, Frame

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

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

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

print(f"Parsed frame: {parsed_frame}")
print(f"Frame data: {parsed_frame.data}")

Architecture

Hyperframe uses an object-oriented design with inheritance hierarchies:

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

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

Capabilities

Frame Parsing and Creation

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

class Frame:
    def __init__(self, stream_id: int, flags: Iterable[str] = ()) -> None: ...
    
    @staticmethod
    def parse_frame_header(header: memoryview, strict: bool = False) -> tuple[Frame, int]: ...
    
    @staticmethod
    def explain(data: memoryview) -> tuple[Frame, int]: ...
    
    def serialize() -> bytes: ...
    def parse_body(data: memoryview) -> None: ...

Frame Operations

Data and Header Frames

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.

class DataFrame(Padding, Frame):
    def __init__(self, stream_id: int, data: bytes = b"", **kwargs) -> None: ...
    
    @property
    def flow_controlled_length(self) -> int: ...

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

Data and Headers

Control Frames

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

class SettingsFrame(Frame):
    def __init__(self, stream_id: int = 0, settings: dict[int, int] | None = None, **kwargs) -> None: ...
    
    # Settings constants
    HEADER_TABLE_SIZE: int
    ENABLE_PUSH: int
    MAX_CONCURRENT_STREAMS: int
    INITIAL_WINDOW_SIZE: int
    MAX_FRAME_SIZE: int
    MAX_HEADER_LIST_SIZE: int
    ENABLE_CONNECT_PROTOCOL: int

Control Frames

Extension and Advanced Features

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

class ExtensionFrame(Frame):
    def __init__(self, type: int, stream_id: int, flag_byte: int = 0x0, body: bytes = b"", **kwargs) -> None: ...

class Flags:
    def __init__(self, defined_flags: Iterable[Flag]) -> None: ...
    def add(self, value: str) -> None: ...
    def discard(self, value: str) -> None: ...

Advanced Features

Package Constants

__version__: str  # "6.1.0"
FRAME_MAX_LEN: int  # 16384 - Maximum initial frame length
FRAME_MAX_ALLOWED_LEN: int  # 16777215 - Maximum allowed frame length
FRAMES: dict[int, type[Frame]]  # Mapping of frame type bytes to frame classes

Exception Hierarchy

class HyperframeError(Exception):
    """Base class for all hyperframe exceptions."""

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

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

class InvalidPaddingError(HyperframeError):
    """Frame padding is invalid."""