blackbull.headers

blackbull.headers

Ordered, multi-valued byte headers with case-insensitive lookup.

Headers

Ordered multi-valued headers with bytes names and values.

Lookups ignore name casing; iteration preserves input casing and duplicate order. get returns the first value or its default; getlist returns all matching (name, value) pairs, or an empty list.

__add__(other)

Return a new Headers containing all pairs from self then other.

__eq__(other)

Value equality on the ordered (name, value) pair list.

Two Headers are equal when they carry the same fields in the same order (RFC 7230 §3.2.2 — order is significant for repeated fields). Enables Connection round-trip equality.

__getitem__(name)

Return all pairs for name. Raises KeyError if absent.

append(name_or_pairs, value=None)

Append header(s) to the end of the list.

Two-argument form: append(name, value) — adds a single pair. One-argument form: append(pairs) — adds every pair in the iterable.

from_lowered(pairs) classmethod

Adopt pairs whose names the caller guarantees are lowercase.

Uppercase names would become unreachable through lookup. Do not mutate the list after handing it over; this path takes ownership instead of copying.

get(name, default=b'')

Return the first value for name, or default if absent.

Mirrors dict.get(key, default): single value, optional default. For headers that may repeat use getlist(name).

get_combined(name)

Return values joined by ,, or None when absent.

Use only for fields allowing comma combination. For fields such as Set-Cookie, use getlist instead. A single empty value returns b''.

get_sf_dict(name)

Parse name as a Structured Field Dictionary (RFC 9651).

Multiple field lines are combined first. Returns an ordered dict of member name → Item / Inner List, or None if the field is absent or fails strict parsing (per RFC 9651 §4.2 the whole field is then ignored).

Example::

headers.get_sf_dict(b'priority')      # {'u': (2, {}), 'i': (True, {})}

get_sf_item(name)

Parse name as a Structured Field Item (RFC 9651).

Returns (bare_item, parameters), or None if the field is absent or fails strict parsing (per RFC 9651 §4.2 the whole field is then ignored).

Example::

headers.get_sf_item(b'deprecation')   # (Date(1659578233), {})

get_sf_list(name)

Parse name as a Structured Field List (RFC 9651).

Multiple field lines are combined first. Returns a list of Items / Inner Lists, or None if the field is absent or fails strict parsing (per RFC 9651 §4.2 the whole field is then ignored).

Example::

headers.get_sf_list(b'accept-query')  # [('a', {}), ('b', {})]

getlist(name)

Return all pairs for name, or [] if the header is absent.