edri.api.headerkit package

Submodules

edri.api.headerkit.core module

class edri.api.headerkit.core.Headers(raw: ~collections.abc.Iterable[tuple[bytes, bytes]], *, registry: ~edri.api.headerkit.registry.Registry | None = None, policy: ~edri.api.headerkit.policy.HeaderPolicy = HeaderPolicy(mode=<ParseMode.STRICT: 'strict'>, unknown=<UnknownHeaderMode.RAW: 'raw'>, max_total_bytes=65536, max_field_lines=256, allow_obs_text=True, strip_ows=True), http_version: str = '1.1')

Bases: object

Lossless, lazy, typed HTTP header accessor for ASGI scopes.

The object keeps the original ASGI byte pairs intact while indexing by lowercase header name. Semantic parsing is opt-in and lazy through the registry.

property accept: Accept

property accept_encoding: tuple[Any, ...]

property accept_language: tuple[Any, ...]

all(name: bytes | str) → tuple[str, ...]

property authorization: Authorization | None

property cache_control: CacheControl

combined(name: bytes | str) → bytes | None

property content_length: int | None

property content_type: MediaType | None

property cookies: Cookies

property date: DateHeader | None

decode_value(value: bytes) → str

property etag: EntityTag | None

first(name: bytes | str) → str | None

first(name: bytes | str, default: T) → str | T

classmethod from_scope(scope: ~collections.abc.Mapping[str, ~typing.Any], *, registry: ~edri.api.headerkit.registry.Registry | None = None, policy: ~edri.api.headerkit.policy.HeaderPolicy = HeaderPolicy(mode=<ParseMode.STRICT: 'strict'>, unknown=<UnknownHeaderMode.RAW: 'raw'>, max_total_bytes=65536, max_field_lines=256, allow_obs_text=True, strip_ows=True)) → Headers

property host: str | None

property if_none_match: EntityTagSet

list_members(name: bytes | str) → tuple[str, ...]

names() → tuple[bytes, ...]

static normalize_name(name: bytes | str) → bytes

parse(name: bytes | str) → Any

property range: Range | None

property raw: tuple[tuple[bytes, bytes], ...]

Original ASGI byte pairs, with original casing/order/duplicates.

raw_all(name: bytes | str) → tuple[bytes, ...]

singleton(name: bytes | str) → str | None

singleton_raw(name: bytes | str) → bytes | None

edri.api.headerkit.defaults module

edri.api.headerkit.errors module

exception edri.api.headerkit.errors.DuplicateHeader

Bases: HeaderError

A header was repeated where the selected policy requires a singleton.

exception edri.api.headerkit.errors.HeaderError

Bases: ValueError

Base class for header parsing/access errors.

exception edri.api.headerkit.errors.HeaderTooLarge

Bases: HeaderError

The configured aggregate header-size limit was exceeded.

exception edri.api.headerkit.errors.InvalidHeader

Bases: HeaderError

Header name or value is syntactically invalid at the generic HTTP layer.

exception edri.api.headerkit.errors.ParseError

Bases: HeaderError

A semantically known header failed to parse.

edri.api.headerkit.grammar module

edri.api.headerkit.parsers module

edri.api.headerkit.policy module

class edri.api.headerkit.policy.HeaderPolicy(mode: 'ParseMode' = <ParseMode.STRICT: 'strict'>, unknown: 'UnknownHeaderMode' = <UnknownHeaderMode.RAW: 'raw'>, max_total_bytes: 'int' = 65536, max_field_lines: 'int' = 256, allow_obs_text: 'bool' = True, strip_ows: 'bool' = True)

Bases: object

class edri.api.headerkit.policy.ParseMode(*values)

Bases: str, Enum

COMPAT = 'compat'

STRICT = 'strict'

class edri.api.headerkit.policy.UnknownHeaderMode(*values)

Bases: str, Enum

COMBINE = 'combine'

RAW = 'raw'

REJECT_DUPES = 'reject-dupes'

edri.api.headerkit.registry module

class edri.api.headerkit.registry.FieldSpec(name: 'bytes', combine: 'CombineMode', parser: 'Parser | None' = None, allow_duplicate_identical: 'bool' = False, request: 'bool' = True, response: 'bool' = True, description: 'str' = '')

Bases: object

class edri.api.headerkit.registry.Registry(specs: list[FieldSpec] | None = None)

Bases: object

copy() → Registry

get(name: bytes) → FieldSpec | None

register(spec: FieldSpec) → None

edri.api.headerkit.response module

class edri.api.headerkit.response.ResponseHeaders(raw: Iterable[tuple[bytes, bytes]] = ())

Bases: object

Builder for ASGI response header byte pairs.

It deliberately treats Set-Cookie as append-only and never coalesces it.

append(name: bytes | str, value: bytes | str | int) → None

asgi() → list[tuple[bytes, bytes]]

delete_cookie(name: str, *, path: str = '/', domain: str | None = None) → None

extend(raw: Iterable[tuple[bytes, bytes]]) → None

remove(name: bytes | str) → None

set(name: bytes | str, value: bytes | str | int) → None

set_content_type(media_type: str, **params: str) → None

set_cookie(name: str, value: str, *, path: str | None = None, domain: str | None = None, max_age: int | None = None, expires: datetime | str | None = None, secure: bool = False, httponly: bool = False, samesite: str | None = None) → None

set_date(name: str, value: datetime | None = None) → None

edri.api.headerkit.types module

class edri.api.headerkit.types.Accept(items: 'tuple[AcceptItem, ...]')

Bases: object

best_match(offers: Iterable[str], default: str | None = None) → str | None

class edri.api.headerkit.types.AcceptItem(media: 'MediaType', q: 'float' = 1.0, accept_ext: 'Mapping[str, str] | None' = None, order: 'int' = 0)

Bases: object

property acceptable: bool

property specificity: int

property value: str

class edri.api.headerkit.types.Authorization(scheme: 'str', credentials: 'str')

Bases: object

class edri.api.headerkit.types.ByteRange(start: 'int | None', end: 'int | None')

Bases: object

class edri.api.headerkit.types.CacheControl(directives: 'Mapping[str, str | bool]')

Bases: object

get(key: str, default: str | bool | None = None) → str | bool | None

property max_age: int | None

property no_cache: bool

property no_store: bool

class edri.api.headerkit.types.CombineMode(*values)

Bases: str, Enum

COMMA_LIST = 'comma-list'

COOKIE = 'cookie'

NEVER_COMBINE = 'never-combine'

OPAQUE = 'opaque'

SINGLETON = 'singleton'

class edri.api.headerkit.types.Cookies(pairs: 'tuple[tuple[str, str], ...]')

Bases: object

as_dict() → dict[str, str]

dechunked() → Cookies

Reassemble Auth.js / NextAuth chunked cookies.

When a cookie value exceeds the ~4 KB browser limit, Auth.js splits it into name.0, name.1, … and the browser sends each chunk back as a separate cookie. This rejoins a contiguous family starting at .0 into a single name cookie (values concatenated in index order).

A non-chunked cookie of the same base name takes precedence (its chunk siblings are then left untouched). Chunk families with a missing .0 or a gap keep their unconsumed members as literal cookies, so nothing is silently dropped.

get(name: str, default: str | None = None) → str | None

get_all(name: str) → tuple[str, ...]

class edri.api.headerkit.types.DateHeader(value: 'datetime')

Bases: object

class edri.api.headerkit.types.EntityTag(tag: 'str', weak: 'bool' = False)

Bases: object

class edri.api.headerkit.types.EntityTagSet(any: 'bool', tags: 'tuple[EntityTag, ...]' = ())

Bases: object

class edri.api.headerkit.types.Forwarded(elements: 'tuple[ForwardedElement, ...]')

Bases: object

class edri.api.headerkit.types.ForwardedElement(params: 'Mapping[str, str]')

Bases: object

class edri.api.headerkit.types.MediaType(type: 'str', subtype: 'str', params: 'Mapping[str, str]')

Bases: object

property essence: str

matches(candidate: str) → bool

class edri.api.headerkit.types.Range(unit: 'str', ranges: 'tuple[ByteRange, ...]')

Bases: object

class edri.api.headerkit.types.Weighted(value: 'str', q: 'float' = 1.0, params: 'Mapping[str, str] | None' = None, order: 'int' = 0)

Bases: object

property acceptable: bool

Module contents