http-fields 0.1.1__tar.gz

http_fields-0.1.1/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+docs/_build/
+
+# Test / type-check caches
+.coverage
+.pytest_cache/
+.mypy_cache/
+
+# Environments
+.venv/
+
+# Release artifacts (generated by the release workflow / its local dry-run)
+sbom/
+requirements-runtime.txt
+
+# Editor / OS
+.vscode/
+*.code-workspace
+.DS_Store

http_fields-0.1.1/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project is in its 0.x series;
+the API may still change between minor versions.
+
+## [0.1.1] - 2026-07-22
+
+Initial release published to PyPI as **http-fields** (`import http_fields`).
+
+(`0.1.0` was tagged but never published to PyPI: its package metadata was missing a summary
+and carried a `Development Status :: 5 - Production/Stable` classifier that overstated the
+stability of a 0.x release. Caught on TestPyPI before the PyPI upload.)
+
+### Added
+
+- A typed, immutable model of HTTP header fields: each header is a frozen dataclass whose fields
+  are the header's structured components, parsed and validated against the relevant RFC ABNF
+  grammar — RFC 9110/9111, 6265, 6266, widely-deployed extensions (Forwarded, CORS, Link, HSTS,
+  Alt-Svc, Prefer), and the RFC 9651 Structured Fields headers.
+- **One construction contract.** `Header.parse(value)` is the only entry point that accepts a raw
+  string; constructors take each field as its already-parsed type, so a constructor never re-runs
+  the grammar on untrusted text. Passing a raw string where a typed field is expected raises
+  `TypeError` pointing at `parse()`. Value objects (`Protocol`, `LinkValue`, `AltValue`,
+  `ForwardedElement`, `Preference`, `Host`, …) accept plain strings for their individual parts and
+  coerce them to validated leaf types.
+- Self-validating leaf types, so an invalid value cannot be held at all: `Token`, `Method`,
+  `FieldName`, `RangeUnit`, `LanguageTag`, `CorsMethod`/`CorsFieldName`, `Expectation`,
+  `Hostname`, `ProtocolName`/`ProtocolVersion`, `ReceivedProtocol`/`ReceivedBy`/`Comment`,
+  `URIReference`, `ProtocolId`/`AltAuthority`, and a shared optional-valued `Param`.
+- An annotation-driven runtime field-type check on every header, applied uniformly with no
+  per-class configuration.
+- A standalone RFC 9651 Structured Fields implementation (Item / List / Dictionary).
+
+### Security
+
+- Every construction path — not just `parse()` — rejects CR/LF/NUL and other invalid content, so a
+  header built from partially attacker-controlled data cannot be used for response splitting /
+  header injection. `parse()` input is length-bounded to limit CPU exhaustion from pathological
+  input.
+
+### Performance
+
+- A header is parsed **at most once**: visitors build field values as trusted leaf types, skipping
+  a re-parse of text the grammar just validated. Structured-Fields headers validate by serializing
+  rather than re-parsing.
+- Each header's serialized `value` (and `str()`/`bytes()`/`asgi_value`) is computed once and cached
+  per instance.
+
+[0.1.1]: https://github.com/declaresub/http-fields/releases/tag/v0.1.1

http_fields-0.1.1/LICENSE.txt

@@ -0,0 +1,16 @@
+Copyright 2022 Charles Yeomans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

http_fields-0.1.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: http-fields
+Version: 0.1.1
+Summary: Typed, immutable HTTP header fields for Python, parsed and validated against RFC ABNF grammars
+Project-URL: Homepage, https://github.com/declaresub/http-fields
+Project-URL: Documentation, https://http-fields.readthedocs.io/
+Project-URL: Repository, https://github.com/declaresub/http-fields
+Project-URL: Changelog, https://github.com/declaresub/http-fields/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/declaresub/http-fields/issues
+Author-email: Charles Yeomans <charles@declaresub.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: abnf,generator,headers,http,parser
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: abnf>=2.6.0
+Requires-Dist: typing-extensions>=4.0
+Description-Content-Type: text/markdown
+
+# http-fields
+
+Typed, validated HTTP headers for Python. Each header is an immutable
+[dataclass](https://docs.python.org/3/library/dataclasses.html) whose fields are the structured
+components of the header. [abnf](https://pypi.org/project/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+.
+
+```python
+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
+
+```sh
+uv add http-fields
+# or: pip install http-fields
+```
+
+## Documentation
+
+Full documentation: **<https://http-fields.readthedocs.io/>**
+
+It follows the [Diátaxis](https://diataxis.fr/) model:
+
+- **Tutorial:**
+  [Getting started](https://http-fields.readthedocs.io/en/latest/tutorials/getting-started.html)
+- **How-to guides:**
+  [parse & build](https://http-fields.readthedocs.io/en/latest/how-to/parse-and-build-headers.html) ·
+  [custom / unknown headers](https://http-fields.readthedocs.io/en/latest/how-to/custom-and-unknown-headers.html) ·
+  [Structured Fields](https://http-fields.readthedocs.io/en/latest/how-to/structured-fields.html)
+- **Reference:**
+  [header catalog](https://http-fields.readthedocs.io/en/latest/reference/headers.html) ·
+  [`structuredfields` API](https://http-fields.readthedocs.io/en/latest/reference/structured-fields.html)
+- **Explanation:**
+  [the header model](https://http-fields.readthedocs.io/en/latest/explanation/design.html)
+
+The sources live in [`docs/`](docs/index.md).
+
+## Development
+
+```sh
+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
+```

http_fields-0.1.1/README.md

@@ -0,0 +1,60 @@
+# http-fields
+
+Typed, validated HTTP headers for Python. Each header is an immutable
+[dataclass](https://docs.python.org/3/library/dataclasses.html) whose fields are the structured
+components of the header. [abnf](https://pypi.org/project/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+.
+
+```python
+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
+
+```sh
+uv add http-fields
+# or: pip install http-fields
+```
+
+## Documentation
+
+Full documentation: **<https://http-fields.readthedocs.io/>**
+
+It follows the [Diátaxis](https://diataxis.fr/) model:
+
+- **Tutorial:**
+  [Getting started](https://http-fields.readthedocs.io/en/latest/tutorials/getting-started.html)
+- **How-to guides:**
+  [parse & build](https://http-fields.readthedocs.io/en/latest/how-to/parse-and-build-headers.html) ·
+  [custom / unknown headers](https://http-fields.readthedocs.io/en/latest/how-to/custom-and-unknown-headers.html) ·
+  [Structured Fields](https://http-fields.readthedocs.io/en/latest/how-to/structured-fields.html)
+- **Reference:**
+  [header catalog](https://http-fields.readthedocs.io/en/latest/reference/headers.html) ·
+  [`structuredfields` API](https://http-fields.readthedocs.io/en/latest/reference/structured-fields.html)
+- **Explanation:**
+  [the header model](https://http-fields.readthedocs.io/en/latest/explanation/design.html)
+
+The sources live in [`docs/`](docs/index.md).
+
+## Development
+
+```sh
+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
+```

http_fields-0.1.1/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+`http-fields` parses and validates HTTP header values, often from untrusted input, so
+correctness of that validation is a security property (e.g. rejecting CR/LF/NUL to prevent
+response splitting / header injection).
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities **privately**, not via a public issue:
+
+- Preferred: GitHub's **"Report a vulnerability"** button on the repository's *Security* tab
+  (private vulnerability reporting).
+- Alternatively, email the maintainer at **charles@declaresub.com**.
+
+Please include a description, affected version/commit, and a minimal reproduction. You'll get
+an acknowledgement, and we'll coordinate a fix and disclosure with you.
+
+## Supported versions
+
+This project is **pre-release** (no tagged release yet); the latest `master` is the supported
+version. Once releases are published, this section will list the supported release lines.
+
+## Verifying a release
+
+Once releases are published to PyPI, this section will describe how to verify a release's
+provenance (build attestations / Sigstore bundle and the attached SBOM).

http_fields-0.1.1/docs/conf.py

@@ -0,0 +1,45 @@
+# Sphinx configuration. Prose lives in Markdown; MyST-Parser reads it directly.
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+project = "http-fields"
+author = "Charles Yeomans"
+copyright = "Charles Yeomans"  # noqa: A001
+
+try:
+    release = _version("http-fields")
+except PackageNotFoundError:  # not installed in the docs environment
+    release = "0.0.0"
+version = release
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+]
+
+# autodoc
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+}
+autodoc_typehints = "description"  # render annotations into the field list
+python_use_unqualified_type_names = True
+
+# Cross-link stdlib types (datetime, Decimal, ...) in signatures.
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+# Resolve [text](other.md) cross-links between source files, and allow the
+# ::: fenced form for directives in addition to the ``` form.
+myst_enable_extensions = ["colon_fence"]
+
+# Generate anchors for h1-h3 so in-page links like [x](#some-heading) resolve.
+myst_heading_anchors = 3
+
+source_suffix = {".md": "markdown"}
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "furo"
+html_title = "http-fields"

http_fields-0.1.1/docs/explanation/design.md

@@ -0,0 +1,77 @@
+# The header model
+
+This page explains *why* `http-fields` is shaped the way it is. For task-focused instructions,
+see the [how-to guides](../how-to/parse-and-build-headers.md); for the full API, the
+[reference](../reference/headers.md).
+
+## Headers are immutable value objects
+
+Every header is a frozen dataclass whose fields are the *structured components* of the header —
+`Age.seconds`, `ContentType.media_type`, `SetCookie.max_age`, and so on. Consequences:
+
+- **Immutable.** You never mutate a header in place; you build a new one. This makes headers safe
+  to share and cache.
+- **Comparable and hashable.** Two headers are equal when their fields are equal, so headers work
+  in sets and as dict keys.
+- **The value is derived.** `.value` (and `str()`, `bytes()`) are computed from the fields, so the
+  serialized form always reflects the current structured state — they can't drift apart.
+
+## abnf drives parsing *and* validation
+
+The library is built on [abnf](https://pypi.org/project/abnf/) grammars for the relevant RFCs.
+Those grammars are used in both directions:
+
+- **Parsing** — `Header.parse(value)` runs the grammar over the raw value and a visitor turns the
+  parse tree into structured fields.
+- **Validation** — the field types themselves (`Token`, `NonNegativeInt`, `EntityTag`, …) parse
+  and validate on construction. So validity isn't a separate step bolted on; it's a property of
+  the types the fields are made of.
+
+A constructed header is therefore always well-formed: invalid input raises `ValueError` (or
+`TypeError` for wrong argument types), whether it came from `parse()` or direct construction.
+
+Because each field type is self-validating, a header is parsed **at most once**. `parse()` runs
+the grammar and the visitor wraps the already-validated node text as leaf types with
+`parse=False` (a trusted construction that skips re-parsing); direct construction validates only
+the parts you actually pass. There is no second grammar pass to re-check a value the visitor just
+built. Structured-Fields headers take this a step further: their serializer *is* the validator —
+a value that would inject control characters or exceed a numeric bound simply fails to serialize —
+so a successful serialization is grammar-valid by construction, with no re-parse at all.
+
+## One construction contract
+
+There is a single, consistent way to make headers:
+
+- **`Header.parse(value)`** is the only string entry point.
+- **Direct construction** takes the structured fields as their parsed types. Scalars coerce plain
+  values (`Age(60)`); list-style headers take leaf types as varargs
+  (`Connection(Token("keep-alive"), Token("close"))`); headers with richer values take value
+  objects (`Upgrade(Protocol("HTTP", "2"))`). A raw string where a typed field is expected is a
+  `TypeError` — reach for `parse()` instead.
+- **Builders** (`ContentType.of(...)`, `SetCookie.build(...)`, `ETag.from_tag(...)`) exist only
+  where piece-wise construction is richer than the stored fields.
+- **`Header.create(name, value)`** dispatches by field name to the right subclass, or a
+  `CustomHeader`.
+
+This is a deliberate break from the older overloaded "string *or* pieces" constructors: one
+object, one obvious way to build it, and precise types throughout.
+
+## Shared bases where shapes repeat
+
+Families that share an identical shape are factored onto a common base — dates (`DateHeader`),
+entity-tag lists (`EntityTagListHeader`), product lists (`UserAgent`/`Server`), the auth pairs
+(`WWWAuthenticate`/`ProxyAuthenticate`, …), and Structured-Fields lists/dictionaries. Where a
+family only *rhymes* (different element types or separators), the headers stay individual — a
+shared base isn't forced.
+
+## Scope
+
+Coverage spans the core HTTP RFCs (9110, 9111, 6265, 6266), widely-deployed extensions
+(Forwarded, CORS, Link, HSTS, Alt-Svc, Prefer), and the modern Structured-Fields headers
+(RFC 9651 and the specs built on it). Headers defined outside a clean RFC ABNF grammar are out of
+scope, because the whole library is grammar-driven.
+
+---
+
+*Implementation notes, design decisions, and the migration history live in the project's internal
+design document (`.claude/design/header-model.md`).*

http_fields-0.1.1/docs/how-to/custom-and-unknown-headers.md

@@ -0,0 +1,51 @@
+# How to handle custom and unknown headers
+
+## Dispatch an incoming header by name
+
+When you receive a `(name, value)` pair and don't know the type ahead of time, use
+`Header.create()`. It matches the name (case-insensitively) against the known headers and returns
+that subclass, falling back to `CustomHeader` for anything unrecognized:
+
+```python
+from http_fields import Header, ContentType, CustomHeader
+
+h = Header.create("Content-Type", "text/plain")
+isinstance(h, ContentType)     # True
+
+h = Header.create("X-Request-Id", "abc123")
+isinstance(h, CustomHeader)    # True
+```
+
+`create()` validates the value through the matched header's `parse()`, so an invalid known-header
+value still raises `ValueError`.
+
+## Represent an arbitrary header
+
+`CustomHeader` models any header with a non-standard field name. Its name and value are validated
+as an RFC 9110 `field-name` / `field-value`:
+
+```python
+from http_fields import CustomHeader
+
+h = CustomHeader("X-Request-Id", "abc123")
+h.name          # 'X-Request-Id'
+h.value         # 'abc123'
+str(h)          # 'X-Request-Id: abc123'
+h.asgi_value    # (b'X-Request-Id', b'abc123')
+
+CustomHeader("bad name", "v")   # ValueError: Invalid field-name "bad name".
+```
+
+## Iterate the known headers
+
+`Header.subclass_tree()` yields every registered header class, which is handy for tooling or
+introspection:
+
+```python
+from http_fields import Header
+
+names = sorted(
+    c.name for c in Header.subclass_tree()
+    if isinstance(getattr(c, "name", None), str)
+)
+```

http_fields-0.1.1/docs/how-to/parse-and-build-headers.md

@@ -0,0 +1,108 @@
+# How to parse and build headers
+
+There are three ways to get a header instance. This guide shows when to use each.
+
+## Parse a raw value string
+
+`Header.parse(value)` is the only string entry point. It validates against the header's abnf
+grammar and raises `ValueError` on bad input.
+
+```python
+from http_fields import CacheControl
+
+cc = CacheControl.parse("max-age=3600, no-cache, immutable")
+cc.max_age       # 3600
+cc.no_cache      # True
+cc.immutable     # True
+```
+
+Pass the header *value* only — not the `Name: value` line.
+
+## Construct from parsed fields
+
+`parse()` is the entry point for *strings*. Direct construction takes each field as its
+already-parsed type — a leaf type or value object — so a constructor never re-runs the grammar
+on untrusted text. Passing a raw string where a typed field is expected raises `TypeError`
+pointing you back to `parse()`.
+
+Plain scalars still coerce their natural Python value:
+
+```python
+from datetime import datetime, timezone
+from http_fields import Age, Date, RetryAfter
+
+Age(60)                                                  # int -> NonNegativeInt
+Date(datetime(2030, 1, 1, tzinfo=timezone.utc))          # a datetime
+RetryAfter(120)                                          # delay-seconds ...
+RetryAfter(datetime(2030, 1, 1, tzinfo=timezone.utc))    # ... or an HTTP-date
+```
+
+List-style headers take their leaf types as varargs. Build the leaves (each validates itself),
+or `parse()` a whole value string:
+
+```python
+from http_fields import Connection, FieldName, Token, Vary
+
+Connection(Token("keep-alive"), Token("close"))
+Vary(FieldName("accept-encoding"), FieldName("accept-language"))
+
+Connection.parse("keep-alive, close")                    # from a raw string
+```
+
+`Connection("keep-alive")` — a bare string — is now a `TypeError`; use `Connection.parse(...)`.
+
+Headers with structured values take value objects, which coerce their string parts to validated
+leaves:
+
+```python
+from http_fields import Protocol, Upgrade
+
+Upgrade(Protocol("HTTP", "2"), Protocol("WebSocket"))
+Upgrade.parse("HTTP/2, WebSocket")                       # equivalent, from a string
+```
+
+## Use a builder classmethod
+
+Headers whose piece-wise construction is richer than their stored fields expose a builder:
+
+| Header | Builder |
+|---|---|
+| `ContentType` | `ContentType.of(type, subtype, *, charset=None, boundary=None, params=None)` |
+| `SetCookie` | `SetCookie.build(cookie_name, cookie_value, *, domain=None, path=None, expires=None, max_age=None, secure=False, http_only=False, samesite="Lax", extension=None)` |
+| `ContentDisposition` | `ContentDisposition.build(disposition_type, disposition_parms=None)` |
+| `ETag` | `ETag.from_tag(tag, weak=False)` |
+
+```python
+from http_fields import ContentType, SetCookie, ETag
+
+ContentType.of(type="text", subtype="html", charset="utf-8")
+SetCookie.build(cookie_name="SID", cookie_value="abc", path="/", secure=True)
+ETag.from_tag("deadbeef", weak=True)
+```
+
+`.build()` validates its input strictly (raising `TypeError`/`ValueError`); `SetCookie.parse()`
+uses the more lenient RFC 6265 §5 algorithm for interoperability.
+
+## Wildcard headers
+
+`If-Match` / `If-None-Match` use `wildcard=True` for `*`; `AltSvc` uses `clear=True` for `clear`:
+
+```python
+from http_fields import IfMatch, AltSvc
+from http_fields.visitors.rfc9110 import EntityTag
+
+IfMatch(wildcard=True)                 # "*"
+IfMatch(EntityTag("deadbeef"))         # a specific tag
+AltSvc(clear=True)                     # "clear"
+```
+
+## Serialize
+
+Any header round-trips to text and bytes:
+
+```python
+str(cc)         # 'Cache-Control: max-age=3600,no-cache,immutable'
+cc.value        # 'max-age=3600,no-cache,immutable'
+bytes(cc)       # b'Cache-Control: ...'
+cc.asgi_value   # (b'Cache-Control', b'...')
+```

http_fields-0.1.1/docs/how-to/structured-fields.md

@@ -0,0 +1,75 @@
+# How to work with Structured Fields
+
+[RFC 9651 Structured Field Values](https://www.rfc-editor.org/rfc/rfc9651) is the type system
+that modern HTTP headers are built on. `http-fields` ships a standalone implementation in
+`http_fields.structuredfields`, plus header classes that use it.
+
+## Use the Structured-Fields headers
+
+These behave like any other header:
+
+```python
+from http_fields import Priority, CacheStatus, ContentDigest
+import base64
+
+Priority.parse("u=5, i").urgency        # 5
+Priority(urgency=5, incremental=True).value    # 'u=5, i'
+
+digest = base64.b64encode(b"hello").decode()
+cd = ContentDigest.parse(f"sha-256=:{digest}:")
+cd.digests                               # (('sha-256', b'hello'),)
+
+cs = CacheStatus.parse("ExampleCache; hit; ttl=376")
+cs.members[0].value                      # 'ExampleCache' (a Token)
+cs.members[0].parameters                 # (('hit', True), ('ttl', 376))
+```
+
+## Parse and serialize raw Structured Fields
+
+Use the `parse_*` / `serialize_*` functions directly for the three top-level types — Item, List,
+and Dictionary:
+
+```python
+from http_fields.structuredfields import (
+    parse_item, parse_list, parse_dictionary,
+    serialize_item, serialize_list, serialize_dictionary,
+)
+
+parse_item("5;foo=bar")          # Item(value=5, parameters=(('foo', Token('bar')),))
+parse_list("a, b, (c d);x=1")    # tuple of Item / InnerList
+parse_dictionary("a=1, b, c=?0") # tuple of (key, Item / InnerList) pairs
+```
+
+Bare items map to native Python types:
+
+| Structured Fields type | Python type |
+|---|---|
+| Integer | `int` |
+| Decimal | `decimal.Decimal` |
+| String | `str` |
+| Token | `Token` (a `str` subclass) |
+| Boolean | `bool` |
+| Byte Sequence | `bytes` |
+| Date | `datetime.datetime` |
+| Display String | `DisplayString` (a `str` subclass) |
+
+`Token` and `DisplayString` are distinct `str` subclasses so they serialize correctly (a `Token`
+is bare, a `str` is quoted):
+
+```python
+from http_fields.structuredfields import Item, Token, serialize_item
+
+serialize_item(Item(Token("gzip")))   # 'gzip'
+serialize_item(Item("gzip"))          # '"gzip"'
+```
+
+## Build values from scratch
+
+Compose `Item` / `InnerList` and serialize:
+
+```python
+from http_fields.structuredfields import Item, InnerList, Token, serialize_list
+
+members = (Item(Token("sugar")), InnerList((Item(1), Item(2)), (("x", True),)))
+serialize_list(members)               # 'sugar, (1 2);x'
+```

http_fields-0.1.1/docs/index.md

@@ -0,0 +1,44 @@
+# http-fields documentation
+
+```{toctree}
+:hidden:
+:maxdepth: 2
+
+tutorials/getting-started
+how-to/parse-and-build-headers
+how-to/custom-and-unknown-headers
+how-to/structured-fields
+reference/headers
+reference/structured-fields
+reference/api
+explanation/design
+```
+
+`http-fields` represents HTTP headers as immutable Python dataclasses. [abnf](https://pypi.org/project/abnf/)
+grammars drive both directions: **parsing** incoming header strings and **validating** field
+values, so a constructed header is always well-formed.
+
+Requires Python 3.10+.
+
+## Documentation
+
+The docs follow the [Diátaxis](https://diataxis.fr/) model:
+
+- **[Tutorials](tutorials/getting-started.md)** — start here if you're new. A hands-on walk
+  through installing, parsing, building, and serializing headers.
+- **How-to guides** — task-focused recipes:
+  - [Parse and build headers](how-to/parse-and-build-headers.md)
+  - [Custom and unknown headers](how-to/custom-and-unknown-headers.md)
+  - [Work with Structured Fields](how-to/structured-fields.md)
+- **Reference** — precise technical description:
+  - [Header catalog](reference/headers.md) — every header, grouped by spec, with its constructors.
+  - [`structuredfields` API](reference/structured-fields.md)
+- **[Explanation](explanation/design.md)** — the *why*: the frozen-dataclass model, the
+  construction contract, and where validation lives.
+
+## Install
+
+```sh
+uv add http-fields
+# or: pip install http-fields
+```