Skip to content

blackbull.protocol.structured_fields

blackbull.protocol.structured_fields

RFC 9651 — Structured Field Values for HTTP.

Strict parser and serialiser for the three top-level Structured Field types (Item, List, Dictionary), implementing the normative algorithms of RFC 9651 §4 (obsoletes RFC 8941; adds the Date and Display String types).

Python type mapping (bare items):

SF type Python type
Integer int
Decimal float
String str
Token Token (str subclass)
Byte Sequence bytes
Boolean bool
Date Date
Display String DisplayString (str subclass)

Structures:

  • Item — (bare_item, parameters) tuple; parameters are a dict[str, bare_item] preserving order.
  • Inner List — (list_of_items, parameters) tuple.
  • List — list of Items / Inner Lists.
  • Dictionary — dict[str, Item | InnerList] preserving order.

Parsing is strict per RFC 9651 §1.1: any violation raises ValueError and the caller is expected to ignore the entire field value (see Headers.get_sf_item / get_sf_list / get_sf_dict, which return None in that case). Serialisation likewise raises ValueError on out-of-range or mistyped input.

An empty List / Dictionary serialises to b''; per RFC 9651 §3.1 the field should then be omitted entirely, which is the caller's job.

Date

RFC 9651 Date — an integer number of Unix seconds (may pre-date 1970).

Deliberately not a datetime: the SF Date range (±10¹⁵−1 seconds) exceeds what datetime can represent. Use to_datetime for values in the representable range.

from_datetime(dt) classmethod

Build a Date from a datetime (naive values are taken as UTC).

to_datetime()

Return the date as an aware UTC datetime.

DisplayString

Bases: str

RFC 9651 Display String — Unicode text, percent-encoded on the wire.

Token

Bases: str

RFC 9651 Token — a short textual identifier (str subclass).

Kept distinct from str (SF String) because the two serialise differently and RFC 9651 requires the distinction to be preserved.

parse_dictionary(value)

Parse a Structured Field Dictionary (RFC 9651 §4.2.2).

Multiple field lines must be combined (joined with b', ') before calling. Returns an ordered dict of member name → Item / Inner List; raises ValueError on any violation of the RFC grammar.

parse_item(value)

Parse a Structured Field Item (RFC 9651 §4.2.3).

Returns (bare_item, parameters). Raises ValueError on any violation of the RFC grammar.

parse_list(value)

Parse a Structured Field List (RFC 9651 §4.2.1).

Multiple field lines must be combined (joined with b', ') before calling. Returns a list of Items / Inner Lists; raises ValueError on any violation of the RFC grammar.

serialize_dictionary(members)

Serialise a Structured Field Dictionary (RFC 9651 §4.1.2) to ASCII bytes.

An empty dictionary yields b'' — per RFC 9651 §3.1 the field should then not be emitted at all.

serialize_item(bare_item, params=None)

Serialise a Structured Field Item (RFC 9651 §4.1.3) to ASCII bytes.

Raises ValueError for out-of-range values (e.g. an integer beyond ±(10¹⁵−1)) or types with no SF mapping.

serialize_list(members)

Serialise a Structured Field List (RFC 9651 §4.1.1) to ASCII bytes.

An empty list yields b'' — per RFC 9651 §3.1 the field should then not be emitted at all.