http-fields 0.1.1__py3-none-any.whl

http_fields/contenttype.py

@@ -0,0 +1,104 @@
+"""Content-Type 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 import ContentTypeVisitor, MediaType, Parameter
+from http_fields.visitors.rfc9110.quotedstring import QuotedString
+
+
+def _unquote(value: str) -> str:
+    """Return the logical value of a parameter, stripping the surrounding DQUOTEs
+    and unescaping quoted-pairs when it is a quoted-string."""
+    if not isinstance(value, QuotedString):
+        return str(value)
+    inner = str(value)[1:-1]
+    out: list[str] = []
+    i = 0
+    while i < len(inner):
+        if inner[i] == "\\" and i + 1 < len(inner):
+            out.append(inner[i + 1])
+            i += 2
+        else:
+            out.append(inner[i])
+            i += 1
+    return "".join(out)
+
+
+@dataclass(frozen=True)
+class ContentType(Header):
+    """Content-Type header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "Content-Type"
+    rule: ClassVar[Rule] = rfc9110.Rule("Content-Type")
+    visitor: ClassVar[ContentTypeVisitor] = ContentTypeVisitor()
+
+    media_type: MediaType
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(cls.visitor.visit(cls._node(value)))
+
+    @classmethod
+    def of(
+        cls,
+        type: str,
+        subtype: str,
+        *,
+        charset: str | None = None,
+        boundary: str | None = None,
+        params: list[tuple[str, str]] | None = None,
+    ) -> Self:
+        """Build a Content-Type from its pieces. ``charset``/``boundary`` take precedence
+        over any same-named entry in ``params``."""
+        all_params: list[Parameter] = [
+            p
+            for p in (
+                Parameter("charset", charset) if charset else None,
+                Parameter("boundary", boundary) if boundary else None,
+            )
+            if p is not None
+        ]
+        for name, val in params or []:
+            param = Parameter(name, val)
+            if (param.name == "charset" and charset) or (
+                param.name == "boundary" and boundary
+            ):
+                continue
+            all_params.append(param)
+        return cls(MediaType(type, subtype, all_params))
+
+    @property
+    def type(self) -> str:
+        return self.media_type.type
+
+    @property
+    def subtype(self) -> str:
+        return self.media_type.subtype
+
+    @property
+    def params(self) -> list[Parameter]:
+        return list(self.media_type.params)
+
+    @property
+    def charset(self) -> str | None:
+        for param in self.media_type.params:
+            if param.name == "charset":
+                return _unquote(param.value)
+        return None
+
+    @property
+    def boundary(self) -> str | None:
+        for param in self.media_type.params:
+            if param.name == "boundary":
+                return _unquote(param.value)
+        return None
+
+    @property
+    def value(self) -> str:
+        return str(self.media_type)

http_fields/cookie.py

@@ -0,0 +1,38 @@
+"""Cookie header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc6265
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc6265 import CookiePair, CookieStringVisitor
+
+
+@dataclass(frozen=True)
+class Cookie(Header):
+    """Cookie header, as defined by RFC 6265."""
+
+    name: ClassVar[str] = "Cookie"
+    rule: ClassVar[Rule] = rfc6265.Rule("cookie-string")
+    visitor: ClassVar[CookieStringVisitor] = CookieStringVisitor()
+
+    pairs: tuple[CookiePair, ...]
+
+    def __init__(self, *pairs: CookiePair | tuple[str, str]) -> None:
+        object.__setattr__(
+            self,
+            "pairs",
+            tuple(p if isinstance(p, CookiePair) else CookiePair(*p) for p in pairs),
+        )
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        # cookies are often sent with an invalid trailing semicolon; strip it before parsing.
+        return cls(*cls.visitor.visit(cls._node(value.rstrip(";"))))
+
+    @property
+    def value(self) -> str:
+        return "; ".join(f"{pair.name}={pair.value}" for pair in self.pairs)

http_fields/date.py

@@ -0,0 +1,17 @@
+"""Date header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.dateheader import DateHeader
+from http_fields.visitors.rfc9110 import DateVisitor
+
+
+class Date(DateHeader):
+    """Date header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "date"
+    rule: ClassVar[Rule] = rfc9110.Rule("Date")
+    visitor = DateVisitor()

http_fields/dateheader.py

@@ -0,0 +1,32 @@
+"""Base class for headers whose value is a single HTTP-date."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import ClassVar
+
+from abnf import NodeVisitor
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc9110 import imf_fixdate
+
+
+@dataclass(frozen=True)
+class DateHeader(Header):
+    """Base for headers whose value is a single HTTP-date (RFC 9110 section 5.6.7).
+
+    Concrete subclasses supply ``name``, ``rule``, and ``visitor`` as ClassVars; the visitor
+    must return a :class:`datetime.datetime`.
+    """
+
+    visitor: ClassVar[NodeVisitor]
+
+    date: datetime
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return imf_fixdate(self.date)

http_fields/entitytaglist.py

@@ -0,0 +1,39 @@
+"""Base class for headers that are a list of entity-tags or ``*``."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import NodeVisitor
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc9110 import EntityTag
+
+
+@dataclass(frozen=True)
+class EntityTagListHeader(Header):
+    """Base for If-Match / If-None-Match: a list of entity-tags, or ``*`` (``wildcard``).
+
+    Concrete subclasses supply ``name``/``rule``/``visitor`` (the visitor returns either the
+    string ``"*"`` or a list of :class:`EntityTag`) and their own ``matches()`` semantics.
+    """
+
+    visitor: ClassVar[NodeVisitor]
+
+    entity_tags: tuple[EntityTag, ...]
+    wildcard: bool
+
+    def __init__(self, *entity_tags: EntityTag, wildcard: bool = False) -> None:
+        object.__setattr__(self, "entity_tags", tuple(entity_tags))
+        object.__setattr__(self, "wildcard", wildcard)
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        result = cls.visitor.visit(cls._node(value))
+        if result == "*":
+            return cls(wildcard=True)
+        return cls(*result)
+
+    @property
+    def value(self) -> str:
+        return "*" if self.wildcard else ", ".join(str(t) for t in self.entity_tags)

http_fields/etag.py

@@ -0,0 +1,46 @@
+"""ETag 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 import EntityTag, ETagVisitor
+
+
+@dataclass(frozen=True)
+class ETag(Header):
+    """ETag header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "ETag"
+    rule: ClassVar[Rule] = rfc9110.Rule("ETag")
+    visitor: ClassVar[ETagVisitor] = ETagVisitor()
+
+    entity_tag: EntityTag
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(cls.visitor.visit(cls._node(value)))
+
+    @classmethod
+    def from_tag(cls, tag: str, weak: bool = False) -> Self:
+        """Build an ETag from an opaque tag and optional weak flag."""
+        return cls(EntityTag(tag, weak=weak))
+
+    @property
+    def value(self) -> str:
+        return str(self.entity_tag)
+
+    def matches(self, entity_tag: EntityTag | None, weak: bool = False) -> bool:
+        """Return True if this ETag matches ``entity_tag`` per RFC 9110 comparison.
+
+        Comparison against None is supported and returns False.
+        """
+        return (
+            self.entity_tag.compare(entity_tag, weak=weak)
+            if isinstance(entity_tag, EntityTag)
+            else False
+        )

http_fields/expect.py

@@ -0,0 +1,52 @@
+"""Expect 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.parsedobjs import ParsedStr
+
+
+class Expectation(ParsedStr):
+    """An RFC 9110 expectation (e.g. ``100-continue``). Self-validating."""
+
+    parser = rfc9110.Rule("expectation")
+
+
+class ExpectVisitor(NodeVisitor):
+    @staticmethod
+    def visit_expectation(node: Node) -> Expectation:
+        # The node is already parsed; skip re-validation.
+        return Expectation(node.value, parse=False)
+
+    def visit_expect(self, node: Node) -> list[Expectation]:
+        return [x for x in map(self.visit, node.children) if x is not None]
+
+
+@dataclass(frozen=True)
+class Expect(Header):
+    """Expect header, as defined by RFC 9110 (in practice almost always ``100-continue``)."""
+
+    name: ClassVar[str] = "Expect"
+    rule: ClassVar[Rule] = rfc9110.Rule("Expect")
+    visitor: ClassVar[ExpectVisitor] = ExpectVisitor()
+
+    expectations: tuple[Expectation, ...]
+
+    def __init__(self, *expectations: Expectation) -> None:
+        # Store already-parsed Expectation values (each validated itself on creation).
+        # The base runtime check enforces the field type; build from a string with
+        # Expect.parse().
+        object.__setattr__(self, "expectations", tuple(expectations))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(self.expectations)

http_fields/expires.py

@@ -0,0 +1,17 @@
+"""Expires header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9111
+
+from http_fields.dateheader import DateHeader
+from http_fields.visitors.rfc9111 import ExpiresVisitor
+
+
+class Expires(DateHeader):
+    """Expires header, as defined by RFC 9111."""
+
+    name: ClassVar[str] = "expires"
+    rule: ClassVar[Rule] = rfc9111.Rule("Expires")
+    visitor = ExpiresVisitor()

http_fields/forwarded.py

@@ -0,0 +1,36 @@
+"""Forwarded header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc7239
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc7239 import ForwardedElement, ForwardedVisitor
+
+
+@dataclass(frozen=True)
+class Forwarded(Header):
+    """Forwarded header, as defined by RFC 7239 (the standardized replacement for the de-facto
+    ``X-Forwarded-*`` headers)."""
+
+    name: ClassVar[str] = "Forwarded"
+    rule: ClassVar[Rule] = rfc7239.Rule("Forwarded")
+    visitor: ClassVar[ForwardedVisitor] = ForwardedVisitor()
+
+    elements: tuple[ForwardedElement, ...]
+
+    def __init__(self, *elements: ForwardedElement) -> None:
+        # Each ForwardedElement self-validates (Param pairs), 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)

http_fields/fromheader.py

@@ -0,0 +1,42 @@
+"""From 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.parsedobjs import ParsedStr
+
+
+class Mailbox(ParsedStr):
+    """A From-header mailbox (RFC 9110 / RFC 5322 addr-spec). Self-validating."""
+
+    parser = rfc9110.Rule("From")
+
+
+@dataclass(frozen=True)
+class From(Header):
+    """From header, as defined by RFC 9110: the mailbox of the user controlling the client.
+
+    The mailbox is validated against RFC 9110 (RFC 5322 addr-spec) on construction.
+    """
+
+    name: ClassVar[str] = "From"
+    rule: ClassVar[Rule] = rfc9110.Rule("From")
+
+    mailbox: Mailbox
+
+    def __init__(self, mailbox: str) -> None:
+        # The mailbox self-validates as a leaf; build from a string via From(...).
+        object.__setattr__(self, "mailbox", Mailbox(mailbox))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(value)
+
+    @property
+    def value(self) -> str:
+        return self.mailbox

http_fields/header.py

@@ -0,0 +1,250 @@
+"""HTTP header abstract base class and the generic custom-header class."""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+import types
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from functools import cached_property, wraps
+from typing import Any, ClassVar, Union, get_args, get_origin
+
+from abnf import Node, ParseError, Rule
+from abnf.grammars import rfc9110
+
+from http_fields.visitors.rfc9110 import FieldName, FieldValue
+
+
+def _matches_type(value: object, hint: object) -> bool:
+    """A small, deterministic runtime type check covering the field-annotation shapes
+    headers actually use: a concrete type, ``tuple[X, ...]``/``tuple[X, Y]``, unions
+    (``X | Y``, ``Optional``), and ``None``. Every element is checked (no sampling).
+    Unrecognised shapes are not blocked."""
+    origin = get_origin(hint)
+    if origin is tuple:
+        args = get_args(hint)
+        if not isinstance(value, tuple):
+            return False
+        if len(args) == 2 and args[1] is Ellipsis:  # tuple[X, ...]
+            return all(_matches_type(v, args[0]) for v in value)
+        return len(value) == len(args) and all(
+            _matches_type(v, a) for v, a in zip(value, args, strict=True)
+        )
+    if origin is Union or origin is types.UnionType:
+        return any(_matches_type(value, a) for a in get_args(hint))
+    if hint is type(None):
+        return value is None
+    if isinstance(hint, type):
+        return isinstance(value, hint)
+    return True  # unrecognised annotation shape: don't block
+
+
+class Header(ABC):
+    """Abstract base for HTTP headers.
+
+    Known headers are frozen dataclasses whose fields are the structured components of the
+    header value. Each sets ``name`` (and usually ``rule``/``visitor``) as a ClassVar,
+    implements a ``parse(value)`` classmethod, and exposes a derived ``value`` property.
+    Arbitrary headers (e.g. ``X-Request-Id``) are represented by :class:`CustomHeader`.
+    """
+
+    encoding: ClassVar[str] = "ISO-8859-1"
+    rule: ClassVar[Rule]  # abnf rule for the header value; provided by subclasses
+    name: ClassVar[str]  # field name; a class constant on known headers,
+    # overridden by a per-instance property on CustomHeader.
+    # Maximum accepted length of a value passed to parse(). Parsing is super-linear
+    # in the length for some grammars, so an oversized value is a CPU-exhaustion
+    # vector; reject it up front. Override per subclass where larger values are
+    # legitimate (e.g. cookie-heavy deployments).
+    max_length: ClassVar[int] = 8192
+    # Per-class cache of resolved field-annotation hints (populated on first use).
+    _field_hints_cache: ClassVar[dict[str, object] | None] = None
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        # Headers (and every value-object they hold) are immutable, so the serialized
+        # value is stable: cache it per instance with functools.cached_property, so it
+        # is computed at most once (str/bytes/asgi_value/__eq__/__hash__ and direct
+        # access all share it). We swap the descriptor in here, at class creation,
+        # rather than decorating each subclass's `value` -- a cached_property directly
+        # overriding the abstract `value` property trips reportIncompatibleMethodOverride,
+        # so subclasses keep a plain @property. cached_property writes to the instance
+        # __dict__, bypassing the frozen __setattr__. Only the class that *defines*
+        # value is wrapped; subclasses inherit the cached descriptor.
+        prop = cls.__dict__.get("value")
+        if isinstance(prop, property) and prop.fget is not None:
+            cached = cached_property(prop.fget)
+            cached.__set_name__(cls, "value")
+            cls.value = cached  # type: ignore[assignment]
+
+        # Wrap a custom __init__ so field types are checked after construction. The
+        # type checker still reads the source __init__ signature for argument
+        # checking; this only adds the runtime guard. (A dataclass-generated __init__
+        # isn't present yet at __init_subclass__ time and is not wrapped.)
+        user_init = cls.__dict__.get("__init__")
+        if callable(user_init):
+
+            @wraps(user_init)
+            def checked_init(
+                self: Header,
+                *args: object,
+                _init: Callable[..., object] = user_init,
+                **kwargs: object,
+            ) -> None:
+                _init(self, *args, **kwargs)
+                self._check_field_types()
+
+            cls.__init__ = checked_init  # type: ignore[assignment]
+
+    @property
+    @abstractmethod
+    def value(self) -> str:
+        """The serialized header field value (without the name)."""
+
+    def __str__(self) -> str:
+        """Return the full ``Name: value`` header field."""
+        return f"{self.name}: {self.value}"
+
+    def __bytes__(self) -> bytes:
+        return str(self).encode(self.encoding)
+
+    @property
+    def asgi_value(self) -> tuple[bytes, bytes]:
+        """Return a ``(name, value)`` pair of latin-1 bytes for an ASGI send dict.
+
+        ASGI encodes header values as ISO-8859-1 (latin-1); using the class
+        encoding keeps this consistent with ``__bytes__`` and accepts obs-text.
+        """
+        return (self.name.encode(self.encoding), self.value.encode(self.encoding))
+
+    def __eq__(self, other: object, /) -> bool:
+        if isinstance(other, Header) and type(other) is type(self):
+            return (self.name, self.value) == (other.name, other.value)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((self.name, self.value))
+
+    @classmethod
+    def _field_hints(cls) -> dict[str, object]:
+        """Resolved ``{field_name: type_hint}`` for this header's dataclass fields,
+        cached per class. Annotations are resolved per class across the MRO (so an
+        unresolvable annotation on one class doesn't disable the check for others)."""
+        cached = cls.__dict__.get("_field_hints_cache")
+        if cached is None:
+            merged: dict[str, Any] = {}
+            for klass in reversed(cls.__mro__):  # base -> derived; derived wins
+                try:
+                    merged.update(inspect.get_annotations(klass, eval_str=True))
+                except Exception:
+                    continue
+            cached = {
+                f.name: merged[f.name]
+                for f in dataclasses.fields(cls)  # type: ignore[arg-type]
+                if f.name in merged
+            }
+            cls._field_hints_cache = cached
+        return cached
+
+    def __post_init__(self) -> None:
+        # Field-type check for headers with a dataclass-generated __init__ (which
+        # calls __post_init__). Custom __init__s are wrapped in __init_subclass__
+        # instead. A subclass overriding __post_init__ should call super() to keep
+        # this guard (or it must validate its fields another way).
+        self._check_field_types()
+
+    def _check_field_types(self) -> None:
+        """Runtime enforcement of the construction contract: every field must match
+        its declared type. Because each field type validates itself on creation, a
+        type check is a complete guarantee -- no grammar re-parse. Raises TypeError
+        (pointing to :meth:`parse`) on a mismatch."""
+        for name, hint in type(self)._field_hints().items():
+            value = getattr(self, name)
+            if not _matches_type(value, hint):
+                cls_name = type(self).__name__
+                shown = repr(value)
+                if len(shown) > 60:
+                    shown = shown[:57] + "..."
+                raise TypeError(
+                    f"{cls_name}.{name} expects {hint!r}; got {shown}. Use "
+                    f"{cls_name}.parse() to build a {cls_name} from a string."
+                )
+
+    @classmethod
+    def _check_length(cls, value: str) -> None:
+        """Reject an oversized parse() input before the (super-linear) grammar runs."""
+        if len(value) > cls.max_length:
+            raise ValueError(
+                f"{cls.__name__} value of {len(value)} chars exceeds the maximum "
+                f"of {cls.max_length}."
+            )
+
+    @classmethod
+    def _node(cls, value: str) -> Node:
+        """Parse ``value`` against ``cls.rule``, translating a ParseError to a ValueError."""
+        cls._check_length(value)
+        try:
+            return cls.rule.parse_all(value)
+        except ParseError as exc:
+            raise ValueError(f'Invalid {cls.__name__} value "{value}".') from exc
+
+    @classmethod
+    def _prefixed_node(cls, value: str) -> Node:
+        """Like :meth:`_node`, but for grammar rules that match the whole header line (name
+        included); prepend ``"<name>: "`` before parsing."""
+        cls._check_length(value)
+        try:
+            return cls.rule.parse_all(f"{cls.name}: {value}")
+        except ParseError as exc:
+            raise ValueError(f'Invalid {cls.__name__} value "{value}".') from exc
+
+    @classmethod
+    def parse(cls, value: str) -> Header:
+        """Parse a header value into an instance. Every concrete known header overrides this
+        (CustomHeader carries an arbitrary name and is built via its constructor instead)."""
+        raise NotImplementedError
+
+    @classmethod
+    def create(cls, name: str, value: str) -> Header:
+        """Return a header for ``(name, value)``: a matching known subclass if one is
+        registered for ``name``, otherwise a :class:`CustomHeader`."""
+        lname = name.lower()
+        for subcls in cls.subclass_tree():
+            cls_name = getattr(subcls, "name", None)
+            if isinstance(cls_name, str) and cls_name.lower() == lname:
+                return subcls.parse(value)
+        return CustomHeader(name, value)
+
+    @classmethod
+    def subclass_tree(cls) -> Iterable[type[Header]]:
+        """Yield all Header subclasses, depth-first."""
+        for subcls in cls.__subclasses__():
+            yield subcls
+            yield from subcls.subclass_tree()
+
+
+@dataclass(frozen=True)
+class CustomHeader(Header):
+    """A header with an arbitrary field name, e.g. ``X-Request-Id``.
+
+    Both name and value are validated against RFC 9110 (``field-name`` / ``field-value``).
+    """
+
+    rule: ClassVar[Rule] = rfc9110.Rule("field-value")
+
+    field_name: FieldName
+    field_value: FieldValue
+
+    def __init__(self, name: str, value: str) -> None:
+        object.__setattr__(self, "field_name", FieldName(name))
+        object.__setattr__(self, "field_value", FieldValue(value))
+
+    @property
+    def name(self) -> str:  # pyright: ignore[reportIncompatibleVariableOverride]
+        return self.field_name
+
+    @property
+    def value(self) -> str:
+        return self.field_value