http-fields 0.1.1__py3-none-any.whl

http_fields/structuredfields.py

@@ -0,0 +1,356 @@
+"""Structured Field Values for HTTP (RFC 9651).
+
+Provides the value model (``Item``, ``InnerList``, ``Token``, ``DisplayString``) plus parse and
+serialize functions for the three top-level types: Item, List, and Dictionary. Bare items map to
+native Python types: Integer -> int, Decimal -> decimal.Decimal, String -> str, Token -> Token,
+Boolean -> bool, Byte Sequence -> bytes, Date -> datetime, Display String -> DisplayString.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import TypeAlias
+
+from abnf import NodeVisitor
+from abnf.grammars import rfc9651
+from abnf.parser import Node
+
+__all__ = [
+    "BareItem",
+    "DisplayString",
+    "InnerList",
+    "Item",
+    "Member",
+    "Parameters",
+    "Token",
+    "parse_dictionary",
+    "parse_item",
+    "parse_list",
+    "serialize_dictionary",
+    "serialize_item",
+    "serialize_list",
+]
+
+
+class Token(str):
+    """A Structured Fields Token (an unquoted identifier), distinct from a String."""
+
+    __slots__ = ()
+
+
+class DisplayString(str):
+    """A Structured Fields Display String (Unicode text), distinct from a String."""
+
+    __slots__ = ()
+
+
+# A bare item is one of these Python types (Token/DisplayString are str subclasses).
+BareItem: TypeAlias = (
+    int | Decimal | bool | bytes | datetime | str | Token | DisplayString
+)
+Parameters: TypeAlias = tuple[tuple[str, object], ...]
+
+
+@dataclass(frozen=True)
+class Item:
+    """A bare item together with its parameters."""
+
+    value: object
+    parameters: tuple[tuple[str, object], ...] = ()
+
+
+@dataclass(frozen=True)
+class InnerList:
+    """An ordered list of items, with parameters, i.e. ``(a b);q=1``."""
+
+    items: tuple[Item, ...] = ()
+    parameters: tuple[tuple[str, object], ...] = field(default_factory=tuple)
+
+
+# A member of a List or Dictionary is either an Item or an InnerList.
+Member: TypeAlias = Item | InnerList
+
+
+# --- string / display-string / byte helpers -------------------------------------------------
+
+
+def _unescape_string(raw: str) -> str:
+    inner = raw[1:-1]  # strip the surrounding DQUOTEs
+    out: list[str] = []
+    i = 0
+    while i < len(inner):
+        if inner[i] == "\\":
+            out.append(inner[i + 1])
+            i += 2
+        else:
+            out.append(inner[i])
+            i += 1
+    return "".join(out)
+
+
+def _escape_string(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _decode_displaystring(raw: str) -> DisplayString:
+    inner = raw[2:-1]  # strip the leading %" and trailing "
+    buf = bytearray()
+    i = 0
+    while i < len(inner):
+        if inner[i] == "%":
+            buf.append(int(inner[i + 1 : i + 3], 16))
+            i += 3
+        else:
+            buf.append(ord(inner[i]))
+            i += 1
+    return DisplayString(buf.decode("utf-8"))
+
+
+def _encode_displaystring(value: str) -> str:
+    out = ['%"']
+    for byte in value.encode("utf-8"):
+        if byte in (0x25, 0x22) or byte < 0x20 or byte > 0x7E:
+            out.append(f"%{byte:02x}")
+        else:
+            out.append(chr(byte))
+    out.append('"')
+    return "".join(out)
+
+
+def _serialize_decimal(value: Decimal) -> str:
+    text = f"{value:.3f}".rstrip("0")
+    return text + "0" if text.endswith(".") else text
+
+
+# --- parsing --------------------------------------------------------------------------------
+
+
+class _StructuredFieldsVisitor(NodeVisitor):
+    @staticmethod
+    def visit_sf_integer(node: Node) -> int:
+        return int(node.value)
+
+    @staticmethod
+    def visit_sf_decimal(node: Node) -> Decimal:
+        return Decimal(node.value)
+
+    @staticmethod
+    def visit_sf_string(node: Node) -> str:
+        return _unescape_string(node.value)
+
+    @staticmethod
+    def visit_sf_token(node: Node) -> Token:
+        return Token(node.value)
+
+    @staticmethod
+    def visit_sf_boolean(node: Node) -> bool:
+        return node.value == "?1"
+
+    @staticmethod
+    def visit_sf_binary(node: Node) -> bytes:
+        return base64.b64decode(node.value.strip(":"))
+
+    @staticmethod
+    def visit_sf_date(node: Node) -> datetime:
+        return datetime.fromtimestamp(int(node.value.lstrip("@")), tz=timezone.utc)
+
+    @staticmethod
+    def visit_sf_displaystring(node: Node) -> DisplayString:
+        return _decode_displaystring(node.value)
+
+    def visit_bare_item(self, node: Node) -> object:
+        return self.visit(node.children[0])
+
+    def visit_param_value(self, node: Node) -> object:
+        return self.visit(node.children[0])
+
+    def visit_parameter(self, node: Node) -> tuple[str, object]:
+        key = ""
+        value: object = True  # a bare parameter key means Boolean true
+        for child in node.children:
+            if child.name == "param-key":
+                key = child.value
+            elif child.name == "param-value":
+                value = self.visit(child)
+        return (key, value)
+
+    def visit_parameters(self, node: Node) -> tuple[tuple[str, object], ...]:
+        # RFC 9651 section 4.2.3.2: parameters are an ordered map; a duplicate key
+        # keeps the last value at the first occurrence's position.
+        params: dict[str, object] = {}
+        for c in node.children:
+            if c.name == "parameter":
+                key, value = self.visit(c)
+                params[key] = value
+        return tuple(params.items())
+
+    def visit_sf_item(self, node: Node) -> Item:
+        value: object = None
+        params: tuple[tuple[str, object], ...] = ()
+        for child in node.children:
+            if child.name == "bare-item":
+                value = self.visit(child)
+            elif child.name == "parameters":
+                params = self.visit(child)
+        return Item(value, params)
+
+    def visit_inner_list(self, node: Node) -> InnerList:
+        items = tuple(self.visit(c) for c in node.children if c.name == "sf-item")
+        params: tuple[tuple[str, object], ...] = ()
+        for child in node.children:
+            if child.name == "parameters":
+                params = self.visit(child)
+        return InnerList(items, params)
+
+    def visit_list_member(self, node: Node) -> object:
+        return self.visit(node.children[0])
+
+    def visit_sf_list(self, node: Node) -> tuple[object, ...]:
+        return tuple(self.visit(c) for c in node.children if c.name == "list-member")
+
+    def visit_member_value(self, node: Node) -> object:
+        return self.visit(node.children[0])
+
+    def visit_dict_member(self, node: Node) -> tuple[str, object]:
+        key = ""
+        member: object = None
+        params: tuple[tuple[str, object], ...] = ()
+        for child in node.children:
+            if child.name == "member-key":
+                key = child.value
+            elif child.name == "member-value":
+                member = self.visit(child)
+            elif child.name == "parameters":
+                params = self.visit(child)
+        if member is None:
+            member = Item(True, params)  # a bare key means Boolean true
+        return (key, member)
+
+    def visit_sf_dictionary(self, node: Node) -> tuple[tuple[str, object], ...]:
+        # RFC 9651 section 4.2.2: a duplicate key keeps the last value at the
+        # first occurrence's position.
+        members: dict[str, object] = {}
+        for c in node.children:
+            if c.name == "dict-member":
+                key, member = self.visit(c)
+                members[key] = member
+        return tuple(members.items())
+
+
+_VISITOR = _StructuredFieldsVisitor()
+
+
+def parse_item(value: str) -> Item:
+    """Parse a Structured Fields Item."""
+    return _VISITOR.visit(rfc9651.Rule("sf-item").parse_all(value))
+
+
+def parse_list(value: str) -> tuple[Item | InnerList, ...]:
+    """Parse a Structured Fields List into a tuple of Item / InnerList. An empty string is an
+    empty list."""
+    if not value.strip():
+        return ()
+    return _VISITOR.visit(rfc9651.Rule("sf-list").parse_all(value))
+
+
+def parse_dictionary(value: str) -> tuple[tuple[str, Item | InnerList], ...]:
+    """Parse a Structured Fields Dictionary into a tuple of (key, Item / InnerList) pairs
+    (ordered). An empty string is an empty dictionary."""
+    if not value.strip():
+        return ()
+    return _VISITOR.visit(rfc9651.Rule("sf-dictionary").parse_all(value))
+
+
+# --- serializing ----------------------------------------------------------------------------
+
+# RFC 9651 section 4.1 requires serializers to fail on values that cannot be
+# represented, rather than emit output that will not round-trip.
+_INTEGER_MAX = 10**15 - 1  # section 4.1.4
+_DECIMAL_INT_MAX = Decimal(10) ** 12  # section 4.1.5: integer part <= 12 digits
+_TOKEN_RE = re.compile(r"^[A-Za-z*][A-Za-z0-9!#$%&'*+\-.^_`|~:/]*$")  # section 4.1.7
+_KEY_RE = re.compile(r"^[a-z*][a-z0-9_.*-]*$")  # section 3.1.2 key
+
+
+def _validate_key(key: object) -> str:
+    if not isinstance(key, str) or not _KEY_RE.match(key):
+        raise ValueError(f"Invalid Structured Fields key: {key!r}.")
+    return key
+
+
+def serialize_bare(value: object) -> str:
+    """Serialize a bare item to its Structured Fields text form."""
+    if isinstance(value, bool):
+        return "?1" if value else "?0"
+    if isinstance(value, int):
+        if not -_INTEGER_MAX <= value <= _INTEGER_MAX:
+            raise ValueError(f"Integer {value} is out of range for Structured Fields.")
+        return str(value)
+    if isinstance(value, Decimal):
+        if abs(value) >= _DECIMAL_INT_MAX:
+            raise ValueError(f"Decimal {value} integer part exceeds 12 digits.")
+        return _serialize_decimal(value)
+    if isinstance(value, DisplayString):
+        return _encode_displaystring(value)
+    if isinstance(value, Token):
+        if not _TOKEN_RE.match(value):
+            raise ValueError(f"Invalid Structured Fields Token: {value!r}.")
+        return str(value)
+    if isinstance(value, str):
+        if any(ord(c) < 0x20 or ord(c) > 0x7E for c in value):
+            raise ValueError(f"String {value!r} contains characters outside %x20-7E.")
+        return '"' + _escape_string(value) + '"'
+    if isinstance(value, bytes):
+        return ":" + base64.b64encode(value).decode("ascii") + ":"
+    if isinstance(value, datetime):
+        # A naive datetime is interpreted as UTC so output does not depend on the
+        # machine's local timezone.
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return "@" + str(int(value.timestamp()))
+    raise TypeError(f"Cannot serialize {value!r} as a Structured Fields bare item.")
+
+
+def _serialize_params(params: tuple[tuple[str, object], ...]) -> str:
+    out: list[str] = []
+    for key, value in params:
+        _validate_key(key)
+        out.append(f";{key}" if value is True else f";{key}={serialize_bare(value)}")
+    return "".join(out)
+
+
+def serialize_item(item: Item) -> str:
+    """Serialize an Item."""
+    return serialize_bare(item.value) + _serialize_params(item.parameters)
+
+
+def _serialize_inner_list(inner: InnerList) -> str:
+    body = " ".join(serialize_item(i) for i in inner.items)
+    return f"({body})" + _serialize_params(inner.parameters)
+
+
+def _serialize_member(member: object) -> str:
+    if isinstance(member, InnerList):
+        return _serialize_inner_list(member)
+    assert isinstance(member, Item)
+    return serialize_item(member)
+
+
+def serialize_list(members: tuple[object, ...]) -> str:
+    """Serialize a List of Item / InnerList members."""
+    return ", ".join(_serialize_member(m) for m in members)
+
+
+def serialize_dictionary(members: tuple[tuple[str, object], ...]) -> str:
+    """Serialize a Dictionary of (key, Item / InnerList) members."""
+    parts: list[str] = []
+    for key, member in members:
+        _validate_key(key)
+        if isinstance(member, Item) and member.value is True:
+            parts.append(key + _serialize_params(member.parameters))
+        else:
+            parts.append(f"{key}={_serialize_member(member)}")
+    return ", ".join(parts)

http_fields/structuredheaders.py

@@ -0,0 +1,90 @@
+"""Base classes for headers whose value is a Structured Field (RFC 9651)."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import ParseError, Rule
+from abnf.grammars import rfc9651
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.structuredfields import (
+    InnerList,
+    Item,
+    parse_dictionary,
+    parse_list,
+    serialize_dictionary,
+    serialize_list,
+)
+
+
+@dataclass(frozen=True)
+class StructuredListHeader(Header):
+    """Base for headers that are a Structured Fields List (Cache-Status, Proxy-Status)."""
+
+    rule: ClassVar[Rule] = rfc9651.Rule("sf-list")
+
+    members: tuple[Item | InnerList, ...]
+
+    def __init__(self, *members: Item | InnerList) -> None:
+        object.__setattr__(self, "members", tuple(members))
+        # Check field types first, so a wrong-typed member gets the contract's TypeError
+        # (pointing at parse()) rather than tripping the serializer's Item assertions below.
+        self._check_field_types()
+        # Serializing validates every member (rejecting injection / out-of-range values
+        # via serialize_bare) and caches the result; a valid serialization is grammar-valid
+        # by construction, so no re-parse is needed.
+        _ = self.value
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        cls._check_length(value)
+        try:
+            return cls(*parse_list(value))
+        except ParseError as exc:
+            raise ValueError(f'Invalid {cls.__name__} value "{value}".') from exc
+
+    @property
+    def value(self) -> str:
+        return serialize_list(self.members)
+
+
+@dataclass(frozen=True)
+class DigestHeader(Header):
+    """Base for headers that are a Structured Fields Dictionary of byte-sequence digests
+    (Content-Digest, Repr-Digest)."""
+
+    rule: ClassVar[Rule] = rfc9651.Rule("sf-dictionary")
+
+    digests: tuple[tuple[str, bytes], ...]
+
+    def __init__(self, *digests: tuple[str, bytes]) -> None:
+        object.__setattr__(self, "digests", tuple(digests))
+        # Check field types first, so a wrong-typed member gets the contract's TypeError
+        # (pointing at parse()) rather than an unpack/serializer error below.
+        self._check_field_types()
+        # Serializing validates every dictionary key (via _validate_key) and caches the
+        # result; a valid serialization is grammar-valid by construction, so no re-parse.
+        _ = self.value
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        cls._check_length(value)
+        try:
+            members = parse_dictionary(value)
+        except ParseError as exc:
+            raise ValueError(f'Invalid {cls.__name__} value "{value}".') from exc
+        digests: list[tuple[str, bytes]] = []
+        for key, m in members:
+            # Each digest value must be a byte sequence; anything else is
+            # malformed and must be rejected rather than silently discarded.
+            if not (isinstance(m, Item) and isinstance(m.value, bytes)):
+                raise ValueError(
+                    f"{cls.__name__} member {key!r} is not a byte sequence."
+                )
+            digests.append((key, m.value))
+        return cls(*digests)
+
+    @property
+    def value(self) -> str:
+        return serialize_dictionary(tuple((key, Item(d)) for key, d in self.digests))

http_fields/te.py

@@ -0,0 +1,36 @@
+"""TE header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc9110.te import TCoding, TEVisitor
+
+
+@dataclass(frozen=True)
+class TE(Header):
+    """TE header, as defined by RFC 9110: the transfer-codings the client is willing to
+    accept (plus the special ``trailers`` token), each with an optional weight."""
+
+    name: ClassVar[str] = "TE"
+    rule: ClassVar[Rule] = rfc9110.Rule("TE")
+    visitor: ClassVar[TEVisitor] = TEVisitor()
+
+    codings: tuple[TCoding, ...]
+
+    def __init__(self, *codings: TCoding) -> None:
+        # Each TCoding self-validates (Token coding, safe Weight/Parameter), so the
+        # field-type check fully guarantees a safe serialized value -- no re-parse.
+        object.__setattr__(self, "codings", tuple(codings))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(coding) for coding in self.codings)

http_fields/trailer.py

@@ -0,0 +1,44 @@
+"""Trailer header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Node, NodeVisitor, Rule
+from abnf.grammars import rfc9110
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc9110 import FieldName
+
+
+class TrailerVisitor(NodeVisitor):
+    def visit_trailer(self, node: Node) -> list[str]:
+        return [x for x in map(self.visit, node.children) if x is not None]
+
+    @staticmethod
+    def visit_field_name(node: Node) -> str:
+        return node.value
+
+
+@dataclass(frozen=True)
+class Trailer(Header):
+    """Trailer header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "Trailer"
+    rule: ClassVar[Rule] = rfc9110.Rule("Trailer")
+    visitor: ClassVar[TrailerVisitor] = TrailerVisitor()
+
+    field_names: tuple[FieldName, ...]
+
+    def __init__(self, *field_names: FieldName) -> None:
+        object.__setattr__(self, "field_names", tuple(field_names))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(
+            *(FieldName(f, parse=False) for f in cls.visitor.visit(cls._node(value)))
+        )
+
+    @property
+    def value(self) -> str:
+        return ", ".join(self.field_names)

http_fields/upgrade.py

@@ -0,0 +1,35 @@
+"""Upgrade header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc9110.upgrade import Protocol, UpgradeVisitor
+
+
+@dataclass(frozen=True)
+class Upgrade(Header):
+    """Upgrade header, as defined by RFC 9110: a list of protocols, e.g. ``HTTP/2, WebSocket``."""
+
+    name: ClassVar[str] = "Upgrade"
+    rule: ClassVar[Rule] = rfc9110.Rule("Upgrade")
+    visitor: ClassVar[UpgradeVisitor] = UpgradeVisitor()
+
+    protocols: tuple[Protocol, ...]
+
+    def __init__(self, *protocols: Protocol) -> None:
+        # Each Protocol self-validates on construction, so the field-type check is a
+        # complete guarantee -- no need to re-parse the serialized value here.
+        object.__setattr__(self, "protocols", tuple(protocols))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(protocol) for protocol in self.protocols)

http_fields/uriheader.py

@@ -0,0 +1,36 @@
+"""Base class for headers whose value is a single URI reference."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.parsedobjs import ParsedStr
+
+
+@dataclass(frozen=True)
+class UriHeader(Header):
+    """Base for headers whose value is a single URI reference.
+
+    Concrete subclasses supply ``name``, ``rule``, and ``uri_type`` -- a self-validating
+    ParsedStr over that grammar rule. The uri validates on construction (not only via
+    :meth:`parse`), so a raw constructor call cannot smuggle CR/LF/NUL or other invalid
+    content into the serialized header.
+    """
+
+    uri_type: ClassVar[type[ParsedStr]]
+
+    uri: ParsedStr
+
+    def __init__(self, uri: str) -> None:
+        # The uri self-validates as a leaf; an already-parsed value passes through.
+        object.__setattr__(self, "uri", type(self).uri_type(uri))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(value)
+
+    @property
+    def value(self) -> str:
+        return self.uri

http_fields/useragent.py

@@ -0,0 +1,18 @@
+"""User-Agent header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.productlistheader import ProductListHeader
+from http_fields.visitors.rfc9110 import UserAgentVisitor
+
+
+class UserAgent(ProductListHeader):
+    """User-Agent header, as defined by RFC 9110. ``items`` is a sequence of Product or
+    Comment values."""
+
+    name: ClassVar[str] = "User-Agent"
+    rule: ClassVar[Rule] = rfc9110.Rule("User-Agent")
+    visitor = UserAgentVisitor()

http_fields/vary.py

@@ -0,0 +1,40 @@
+"""Vary header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc7231
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc9110 import FieldName, VaryVisitor
+
+
+@dataclass(frozen=True)
+class Vary(Header):
+    """Vary header, as defined by RFC 9110.
+
+    An empty ``field_names`` serializes as ``*`` (vary by anything).
+
+    Vary: accept-encoding, accept-language
+    """
+
+    name: ClassVar[str] = "Vary"
+    rule: ClassVar[Rule] = rfc7231.Rule("Vary")
+    visitor: ClassVar[VaryVisitor] = VaryVisitor()
+
+    field_names: tuple[FieldName, ...]
+
+    def __init__(self, *field_names: FieldName) -> None:
+        object.__setattr__(self, "field_names", tuple(field_names))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(
+            *(FieldName(f, parse=False) for f in cls.visitor.visit(cls._node(value)))
+        )
+
+    @property
+    def value(self) -> str:
+        return ", ".join(self.field_names) if self.field_names else "*"

http_fields/via.py

@@ -0,0 +1,35 @@
+"""Via header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc9110.via import ViaElement, ViaVisitor
+
+
+@dataclass(frozen=True)
+class Via(Header):
+    """Via header, as defined by RFC 9110: the intermediaries a message passed through."""
+
+    name: ClassVar[str] = "Via"
+    rule: ClassVar[Rule] = rfc9110.Rule("Via")
+    visitor: ClassVar[ViaVisitor] = ViaVisitor()
+
+    elements: tuple[ViaElement, ...]
+
+    def __init__(self, *elements: ViaElement) -> None:
+        # Each ViaElement self-validates (leaf-typed fields), so the field-type check
+        # fully guarantees a safe serialized value -- no re-parse.
+        object.__setattr__(self, "elements", tuple(elements))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(element) for element in self.elements)