h2: Pure-Python HTTP/2 Protocol Implementation

Warnings

• breaking As of v4.3.0, many event classes (e.g., `RequestReceived`, `DataReceived`) have been converted to Python dataclasses. This means they now have required arguments for instantiation. Directly instantiating these events without arguments, a common previous API pattern, will no longer work.
  Fix: Review calls to event constructors and provide all required arguments. Consult the `h2` API documentation for the exact constructor signatures for each event class.
• breaking The `client_side` and `header_encoding` arguments and properties of `H2Connection` were deprecated and subsequently removed. Headers are now returned as byte strings by default, and `dict` objects are no longer allowed for user-supplied headers; a sequence of 2-tuples must be used.
  Fix: Instead of direct `H2Connection` arguments, use `h2.config.H2Configuration` to configure the connection. Ensure all headers are provided as a list of `(name, value)` byte-string tuples. The `header_encoding` can be set on `H2Configuration` if UTF-8 encoding is desired for received headers.
• breaking Header field names and values with leading/trailing whitespace are now rejected. Also, specific headers (e.g., `TE` not equal to `trailers`, connection-specific headers) are strictly enforced according to RFC 7540 and will cause rejections or normalization.
  Fix: Ensure all header names and values are clean and conform to RFC 7540. The library may normalize or reject non-compliant headers.
• gotcha `h2` is a purely in-memory protocol stack. It does not handle network I/O, concurrency, or parsing beyond the HTTP/2 frame layer. Users must implement their own networking (e.g., sockets), buffering, and event loops.
  Fix: Integrate `h2` with a networking library (e.g., `socket`, `asyncio`, `Twisted`) and handle the `data_to_send()` and `receive_data()` methods appropriately within your application's I/O loop.
• gotcha Automatic flow control window management was introduced in v2.5.0 via `acknowledge_received_data`. Before this, users had to manually call `increment_flow_control_window` for both stream and connection level windows, which is a common source of deadlock or stalls if not handled correctly.
  Fix: Utilize `conn.acknowledge_received_data(amount)` after processing received data to automatically manage flow control windows. If precise control is needed, ensure `conn.increment_flow_control_window(amount, stream_id)` is called for both the specific stream and stream 0 (connection-level).
• breaking Support for Python 3.9 and PyPy 3.9 has been removed.
  Fix: Upgrade to a supported Python version (e.g., Python 3.10+).

Install

• pip install h2 Install latest version

Imports

• H2Connection

  from h2.connection import H2Connection

• H2Configuration

  from h2.config import H2Configuration

• ConnectionClosed

  from h2.errors import ConnectionClosed

  Moved from exceptions to errors module in older versions, but the primary error classes are now in `h2.errors`.
• RequestReceived

  from h2.events import RequestReceived

  As of v4.3.0, event classes like `RequestReceived` are dataclasses and require arguments during instantiation, changing a commonly used API pattern.

Quickstart

This quickstart demonstrates how to initialize an `H2Connection` with `H2Configuration` and send basic HTTP/2 headers. The library is purely in-memory, so managing I/O (sending and receiving bytes over a network socket) is left to the user's application.

import h2.connection
import h2.config
import os

# Example: Initialize H2Connection for a client or server
config = h2.config.H2Configuration(client_side=True) # or False for server_side
conn = h2.connection.H2Connection(config=config)

# Example of sending a request (client-side)
stream_id = conn.get_next_available_stream_id()
headers = [
    (':method', 'GET'),
    (':authority', os.environ.get('H2_EXAMPLE_AUTHORITY', 'example.com')),
    (':scheme', 'https'),
    (':path', '/')
]
conn.send_headers(stream_id=stream_id, headers=headers)
conn.end_stream(stream_id)

# Data to send over the wire (conceptual)
data_to_send = conn.data_to_send()
if data_to_send:
    # In a real application, you would send this data over a socket.
    # print(f"Sending {len(data_to_send)} bytes: {data_to_send!r}")
    pass

# Simulate receiving data and processing events
# events = conn.receive_data(received_bytes)
# for event in events:
#     if isinstance(event, h2.events.RequestReceived):
#         print(f"Request received on stream {event.stream_id}")

print("h2 connection initialized and example headers sent.")