h11

Warnings

• breaking ProtocolError was split into LocalProtocolError and RemoteProtocolError in v0.10. Catching the old bare ProtocolError still works (it is now an abstract base class), but code that previously caught ProtocolError to distinguish client vs server errors must be updated.
  Fix: Catch h11.LocalProtocolError for errors you caused and h11.RemoteProtocolError for peer misbehavior. Both inherit from h11.ProtocolError if you need a catch-all.
• breaking Python 2 support was dropped in v0.12; Python 3.6 support dropped in v0.14. h11 now requires Python >= 3.8 (as of v0.16).
  Fix: Upgrade to Python >= 3.8. Pin h11 <= 0.11.x only if you must keep Python 2 support.
• breaking Outgoing header validation became strict in v0.10+: headers with illegal characters or leading/trailing whitespace in values now raise LocalProtocolError. Previously, whitespace was silently stripped.
  Fix: Strip whitespace from header values before passing them to h11 event constructors, or fix the upstream source producing invalid header values.
• breaking v0.16.0 rejects previously-accepted malformed Transfer-Encoding: chunked bodies (CVE / GHSA-vqfr-h8mv-ghfj). Code or test suites that construct intentionally malformed chunked bodies will now get a RemoteProtocolError.
  Fix: Upgrade to h11 >= 0.16.0. If you are behind a reverse proxy, also ensure the proxy correctly validates chunked encoding to prevent request smuggling.
• gotcha Protocol errors are unrecoverable. Once LocalProtocolError or RemoteProtocolError is raised, the Connection state becomes ERROR and all subsequent send()/next_event() calls also raise. You cannot reset or reuse the connection.
  Fix: Close the socket and create a brand-new h11.Connection for the next request. Do not attempt to call start_next_cycle() after an error.
• gotcha start_next_cycle() for keep-alive reuse raises LocalProtocolError('not in a reusable state') if called before both sides have reached DONE state. Forgetting to send or fully consume EndOfMessage is a common cause.
  Fix: Verify conn.our_state is h11.DONE and conn.their_state is h11.DONE before calling conn.start_next_cycle(). Always fully drain response events (including EndOfMessage) before reusing.
• gotcha Response bodies may be delivered across multiple Data events because h11 buffers as little as possible. Assuming a single Data event contains the full body will silently truncate data.
  Fix: Accumulate all Data event payloads in a list/bytearray and concatenate only after receiving EndOfMessage.

Install

• pip install h11 pip

Imports

• Connection

  import h11; conn = h11.Connection(our_role=h11.CLIENT)

  All public symbols live directly on the h11 namespace. Do not import from h11._connection or other private submodules.
• Request / Response / Data / EndOfMessage / InformationalResponse / ConnectionClosed

  import h11  # then use h11.Request, h11.Response, etc.

  All event classes are top-level on h11. Importing from h11._events is private API and may break across patch releases.
• LocalProtocolError / RemoteProtocolError / ProtocolError

  import h11  # catch h11.LocalProtocolError, h11.RemoteProtocolError

  These are re-exported at the top-level h11 namespace; importing from h11._util is private and unsupported.
• NEED_DATA / PAUSED / CLIENT / SERVER

  import h11  # use h11.NEED_DATA, h11.PAUSED, h11.CLIENT, h11.SERVER

  Sentinel values are identity-compared with 'is', not '=='. Use type(event) dispatch or identity checks.

Quickstart

Minimal synchronous HTTP/1.1 client using a raw socket. Demonstrates Connection setup, sending a Request + EndOfMessage, and draining events in a loop.

import socket
import ssl
import h11

HOST = "httpbin.org"
PORT = 443

ctx = ssl.create_default_context()
sock = ctx.wrap_socket(
    socket.create_connection((HOST, PORT)),
    server_hostname=HOST,
)

conn = h11.Connection(our_role=h11.CLIENT)

# Send request
sock.sendall(conn.send(h11.Request(
    method="GET",
    target="/get",
    headers=[("Host", HOST), ("Connection", "close")],
)))
sock.sendall(conn.send(h11.EndOfMessage()))

# Receive events
while True:
    event = conn.next_event()
    if event is h11.NEED_DATA:
        data = sock.recv(4096)
        conn.receive_data(data)
        continue
    if isinstance(event, h11.Response):
        print("Status:", event.status_code)
    elif isinstance(event, h11.Data):
        print("Body chunk:", event.data[:80])
    elif isinstance(event, (h11.EndOfMessage, h11.ConnectionClosed)):
        break

sock.close()