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
```
