or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdconnection.mdevents.mdexceptions.mdindex.mdsettings.md
tile.json

tessl/pypi-h2

Pure-Python HTTP/2 protocol implementation providing low-level connection and stream management

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/h2@4.3.x

To install, run

npx @tessl/cli install tessl/pypi-h2@4.3.0

index.mddocs/

h2

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.

Package Information

  • Package Name: h2
  • Language: Python
  • Installation: pip install h2
  • Dependencies: hyperframe>=6.1,<7, hpack>=4.1,<5

Core Imports

from h2.connection import H2Connection
from h2.config import H2Configuration

Common imports for working with events and exceptions:

from h2.events import RequestReceived, ResponseReceived, DataReceived
from h2.exceptions import ProtocolError, StreamClosedError
from h2.errors import ErrorCodes

Basic Usage

from h2.connection import H2Connection
from h2.config import H2Configuration
from h2.events import RequestReceived, ResponseReceived, DataReceived

# Configure and create connection
config = H2Configuration(client_side=True)
conn = H2Connection(config=config)

# Initialize connection
conn.initiate_connection()
data_to_send = conn.data_to_send()
# Send data_to_send over your network connection

# Send a request
conn.send_headers(
    stream_id=1,  
    headers=[
        (':method', 'GET'),
        (':path', '/'),
        (':scheme', 'https'),
        (':authority', 'example.com'),
    ]
)
data_to_send = conn.data_to_send()
# Send data_to_send over your network connection

# Process received data
received_data = b"..."  # Data from network
events = conn.receive_data(received_data)

for event in events:
    if isinstance(event, ResponseReceived):
        print(f"Response headers: {event.headers}")
    elif isinstance(event, DataReceived):
        print(f"Response data: {event.data}")
        # Acknowledge received data for flow control
        conn.acknowledge_received_data(len(event.data), event.stream_id)

Architecture

h2 implements a layered HTTP/2 protocol stack:

  • H2Connection: Core connection object managing overall HTTP/2 state, frame processing, and multiple streams
  • Event System: Protocol actions generate structured events that applications process
  • Settings Management: HTTP/2 settings negotiation and validation
  • Flow Control: Connection and per-stream flow control window management
  • Configuration: Behavioral control through H2Configuration with validation and normalization options

This design separates protocol logic from network I/O, allowing integration into any networking framework while providing complete HTTP/2 compliance.

Capabilities

Connection Management

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.

class H2Connection:
    def __init__(self, config: H2Configuration | None = None): ...
    def initiate_connection(self) -> None: ...
    def send_headers(self, stream_id: int, headers: list, **kwargs) -> None: ...
    def send_data(self, stream_id: int, data: bytes, **kwargs) -> None: ...
    def receive_data(self, data: bytes) -> list[Event]: ...
    def data_to_send(self, amount: int | None = None) -> bytes: ...

Connection Management

Configuration

HTTP/2 connection configuration controlling validation, encoding, normalization, and logging behavior. H2Configuration allows fine-tuned control over protocol handling.

class H2Configuration:
    def __init__(
        self,
        client_side: bool = True,
        header_encoding: str | None = None,
        validate_outbound_headers: bool = True,
        **kwargs
    ): ...

Configuration

Event System

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.

class RequestReceived(Event):
    stream_id: int
    headers: list[Header]
    
class ResponseReceived(Event):
    stream_id: int
    headers: list[Header]
    
class DataReceived(Event):
    stream_id: int
    data: bytes
    flow_controlled_length: int

Event System

Exception Handling

Comprehensive exception hierarchy for HTTP/2 protocol errors, stream errors, and configuration issues. All exceptions include appropriate error codes and context information.

class H2Error(Exception): ...
class ProtocolError(H2Error): ...
class StreamClosedError(NoSuchStreamError): ...
class FlowControlError(ProtocolError): ...

Exception Handling

Settings Management

HTTP/2 settings negotiation, validation, and state management. Settings control connection behavior and are negotiated between peers during connection establishment.

class SettingCodes(enum.IntEnum):
    HEADER_TABLE_SIZE = 0x1
    ENABLE_PUSH = 0x2
    MAX_CONCURRENT_STREAMS = 0x3
    
class Settings(MutableMapping[Union[SettingCodes, int], int]):
    def __init__(self, client: bool = True, **kwargs): ...
    def acknowledge(self) -> dict: ...

Settings Management

Error Codes

HTTP/2 standard error codes for protocol violations and connection issues:

class ErrorCodes(enum.IntEnum):
    NO_ERROR = 0x0
    PROTOCOL_ERROR = 0x1
    INTERNAL_ERROR = 0x2
    FLOW_CONTROL_ERROR = 0x3
    SETTINGS_TIMEOUT = 0x4
    STREAM_CLOSED = 0x5
    FRAME_SIZE_ERROR = 0x6
    REFUSED_STREAM = 0x7
    CANCEL = 0x8
    COMPRESSION_ERROR = 0x9
    CONNECT_ERROR = 0xa
    ENHANCE_YOUR_CALM = 0xb
    INADEQUATE_SECURITY = 0xc
    HTTP_1_1_REQUIRED = 0xd