http-fields

Typed, validated HTTP headers for Python. Each header is an immutable dataclass whose fields are the structured components of the header. abnf grammars are used both to parse incoming header strings and to validate field values, so a constructed header is always well-formed.

Requires Python 3.10+.

from http_fields import ContentType, Header

ct = ContentType.parse("text/html; charset=UTF-8")
ct.type, ct.subtype, ct.charset          # ('text', 'html', 'UTF-8')
str(ct)                                   # 'Content-Type: text/html;charset=UTF-8'

ContentType.of(type="text", subtype="html", charset="utf-8")   # build from pieces
Header.create("x-request-id", "abc123")                         # dispatch by name

Install

uv add http-fields
# or: pip install http-fields

Documentation

Full documentation: https://http-fields.readthedocs.io/

It follows the Diátaxis model:

• Tutorial: Getting started
• How-to guides: parse & build · custom / unknown headers · Structured Fields
• Reference: header catalog · structuredfields API
• Explanation: the header model

The sources live in docs/.

Development

uv sync                       # create the environment
uv run pytest                 # run the tests
uv run ruff check .           # lint
uv run ruff format .          # format
uv run basedpyright           # type-check

uv sync --group docs          # add the docs toolchain
uv run sphinx-build -b html docs docs/_build/html   # build the docs locally