Skip to main content

HTTP Structured Fields in Python

Test Status

This is a Python 3 library implementing parsing and serialisation of RFC 9651.

Python API

Parsing

Textual HTTP headers can be parsed by calling parse; the return value is a data structure that represents the field value.

>>> from http_sf import parse, ser
>>> parse(b"foo; a=1, bar; b=2", tltype="dictionary")
{'foo': (True, {'a': 1}), 'bar': (True, {'b': 2})}

parse() takes a bytes-like object as the first argument; it's annotated as Buffer, so anything that supports the buffer protocol works (bytes, bytearray, memoryview, mmap, array.array, and so on). Anything other than bytes is copied to bytes first. Other types, including str, raise a TypeError; if you want to parse a string, please .encode() it first.

Indicating Top-Level Type

Because the library needs to know which kind of field it is, you need to hint this when calling parse. There are two ways to do this:

  1. Using a tltype parameter, whose value should be one of 'dictionary', 'list', or 'item'.
  2. Using a name parameter to indicate a field name that has a registered type, per the retrofit draft.

Note that if you use name, a KeyError will be raised if the type associated with the name isn't known, unless you also pass a tltype as a fallback.

Error Handling

When parsing fails, a StructuredFieldError (a subclass of ValueError) is raised. Its string form includes the position and context when they are known, and it has attributes that can be used to debug the error:

  • position: The character offset in the input bytes where the error was detected. In most cases this is the first byte the parser rejected (for example, the . in the Date @1.5, or the fourth digit after the . in the Decimal 1.23456, even though the specification only checks the length of a fraction after reading the whole number), or the end of the input if it ended too soon. An error that can only be found once a whole value has been read, and can't be pinned to one byte (for example, a Date that is out of range), is reported at the end of that value.
  • offending_char: The byte (as an int) at position, or None if position is at the end of the input.
  • context: If the error occurred within a Dictionary or Parameter value, the key name.
>>> from http_sf import parse, StructuredFieldError
>>> try:
...     parse(b"foo;", tltype="item")
... except StructuredFieldError as e:
...     print(e)
...     print(e.position)
...
Trailing delimiter at position 4
4

Duplicate Keys

By default, duplicate keys in Dictionaries and Parameters are overwritten by the last value, as per the specification. If you wish to detect when this happens, you can set a callback:

>>> from http_sf import parse
>>> def complain(key, context):
...     print(f"Duplicate key: {key} in {context}")
...
>>> parse(b"a=1, a=2", tltype="dictionary", on_duplicate_key=complain)
Duplicate key: a in dictionary
{'a': (2, {})}

Types

In the returned data, Dictionaries are represented as Python dictionaries; Lists are represented as Python lists, and Items are the bare type.

Bare types are represented using the following Python types:

  • Integers: int
  • Decimals: decimal.Decimal (ser() accepts float as well)
  • Strings: str
  • Tokens: http_sf.Token (a UserString)
  • Byte Sequences: bytes
  • Booleans: bool
  • Dates: datetime.datetime (parsed values are timezone-aware, in UTC; values to be serialised must be timezone-aware too, or ser() raises ValueError)
    • Python's datetime can only represent years 1 to 9999, so parse() raises StructuredFieldError for Date values outside @-62135596800 (0001-01-01T00:00:00Z) to @253402300799 (9999-12-31T23:59:59Z), even though RFC 9651 allows the full Integer range.
  • Display Strings: http_sf.DisplayString (a UserString)

Inner Lists are represented as lists as well.

ser() also accepts subclasses of int, str, float and bytes (IntEnum and str Enum members, numpy.float64, and so on). It serialises the underlying value and ignores any overrides, such as __str__ or __float__.

Parameter and Dictionary keys must be str; ser() raises TypeError for any other type, and ValueError for a str that isn't a valid key. Subclasses are serialised by their underlying value, as above.

Parameters

Structured Types that can have parameters (including Dictionary and List members as well as singular Items and Inner Lists) are represented as a tuple of (value, parameters) where parameters is a dictionary.

So, a single item that's a Token with one parameter whose value is an integer will be represented like this:

>>> parse(b"foo; a=1", tltype="item")
(Token("foo"), {'a': 1})

Note that even if there aren't parameters, a tuple will still be returned, as in some items on this List:

>>> parse(b"a, b; q=5, c", tltype="list")
[(Token("a"), {}), (Token("b"), {'q': 5}), (Token("c"), {})]

Serialisation

To serialise that data structure back to a textual Structured Field, use ser:

>>> field = parse(b"a, b; q=5, c", tltype="list")
>>> ser(field)
'a, b;q=5, c'

When using ser, if an Item or Inner List doesn't have parameters, they can be omitted; for example:

>>> structure = [5, 6, (7, {"with": "param"})]
>>> ser(structure)
'5, 6, 7;with="param"'

Note that ser produces a string, not a bytes-like object.

Migrating from http_sfv

If you have code that uses the deprecated http_sfv package, a drop-in compatibility layer is available in http_sf.compat. It provides the same object-oriented Dictionary, List, Item, InnerList, Token, and DisplayString classes built on top of this library's functional API, so existing code typically only needs an import change:

# Before
from http_sfv import Dictionary, List, Item, Token

# After
from http_sf.compat import Dictionary, List, Item, Token

The compat layer exposes the same .parse(bytes) / str(...) workflow, .value / .params attributes, structural list/dict behaviour, and Item equality semantics (compared by value, ignoring parameters) as http_sfv. New code should prefer the functional parse / ser API documented above.

Command Line Use

You can validate and examine the data model of a field value by calling the library on the command line, using -d, -l and -i to denote dictionaries, lists or items respectively; e.g.,

> python3 -m http_sf -i "foo;bar=baz"
[
    {
        "__type": "token",
        "value": "foo"
    },
    {
        "bar": {
            "__type": "token",
            "value": "baz"
        }
    }
]

or:

> python3 -m http_sf -i "foo;&bar=baz"
VALUE: foo;&bar=baz
FAIL: Key does not begin with lcalpha or * at position 4

(On failure, the input and the error are written to standard error, and the exit status is 1.)

Alternatively, you can pass the field name with the -n option, provided that it is a compatible retrofit field:

> python3 -m http_sf -n "Cache-Control" "max-age=40, must-revalidate"
{
    "max-age": [
        40,
        {}
    ],
    "must-revalidate": [
        true,
        {}
    ]
}

Note that if successful, the output is in the JSON format used by the test suite.

Metadata

Release files for http-sf 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for http-sf 1.5.0
File Size Uploaded Provenance Actions
http_sf-1.5.0.tar.gz 55.6 kB With provenance Details for http_sf-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for http-sf 1.5.0
File Interpreter ABI Platform Actions
http_sf-1.5.0-py3-none-any.whl Python 3 none any Details for http_sf-1.5.0-py3-none-any.whl

Total release size: 83.2 kB

Release files / http_sf-1.5.0.tar.gz

Download URL http_sf-1.5.0.tar.gz
Size 55.6 kB
Tags Source
SHA-256 checksum
How to use checksums
b54cfa55f428dd7cb1cfcc6fbd5020f967060df136ffa37cab5b9798f647612f
BLAKE2b-256 checksum
How to use checksums
44d1af2d7665a9cb295f95a4125826a45443bd6f554946d1ca9876cf3ef1dc3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Release files / http_sf-1.5.0-py3-none-any.whl

Download URL http_sf-1.5.0-py3-none-any.whl
Size 27.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
031282bd376549b04fcaa397d9ef351acdc5bd383435cccd1d8ea17b1661c80e
BLAKE2b-256 checksum
How to use checksums
f44a5a1d3b0fcb58cbd827a968f69d6139c1af419dd008f2c4caf8a8ab78b7bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Security for http-sf 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for http_sf-1.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page