http-fields 0.1.1__py3-none-any.whl

http_fields/host.py

@@ -0,0 +1,44 @@
+"""Host 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 NonNegativeInt
+from http_fields.visitors.rfc9110 import Hostname, HostVisitor
+
+
+@dataclass(frozen=True)
+class Host(Header):
+    """Host header, as defined by RFC 9110.
+
+    Host: www.example.com
+    """
+
+    name: ClassVar[str] = "host"
+    rule: ClassVar[Rule] = rfc9110.Rule("Host")
+    visitor: ClassVar[HostVisitor] = HostVisitor()
+
+    hostname: Hostname
+    port: NonNegativeInt | None = None
+
+    def __init__(self, hostname: str, port: int | None = None) -> None:
+        # hostname/port self-validate as leaves (an already-parsed value passes through),
+        # so a valid uri-host and numeric port serialize to a valid Host -- no re-parse.
+        object.__setattr__(self, "hostname", Hostname(hostname))
+        object.__setattr__(
+            self, "port", NonNegativeInt(port) if port is not None else None
+        )
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        hostname, port = cls.visitor.visit(cls._node(value))
+        return cls(hostname, port)
+
+    @property
+    def value(self) -> str:
+        return self.hostname + (f":{self.port}" if self.port is not None else "")

http_fields/ifmatch.py

@@ -0,0 +1,24 @@
+"""If-Match header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.entitytaglist import EntityTagListHeader
+from http_fields.visitors.rfc9110 import EntityTag, IfMatchVisitor
+
+
+class IfMatch(EntityTagListHeader):
+    """If-Match header, as defined by RFC 9110. ``wildcard`` (``*``) matches any current
+    representation."""
+
+    name: ClassVar[str] = "If-Match"
+    rule: ClassVar[Rule] = rfc9110.Rule("If-Match")
+    visitor = IfMatchVisitor()
+
+    def matches(self, entity_tag: EntityTag) -> bool:
+        """Return True if ``entity_tag`` strongly matches, or this header is ``*``."""
+        if self.wildcard:
+            return True
+        return any(entity_tag.compare(tag, weak=False) for tag in self.entity_tags)

http_fields/ifmodifiedsince.py

@@ -0,0 +1,17 @@
+"""IfModifiedSince 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 IfModifiedSinceVisitor
+
+
+class IfModifiedSince(DateHeader):
+    """If-Modified-Since header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "If-Modified-Since"
+    rule: ClassVar[Rule] = rfc9110.Rule("If-Modified-Since")
+    visitor = IfModifiedSinceVisitor()

http_fields/ifnonematch.py

@@ -0,0 +1,24 @@
+"""If-None-Match header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.entitytaglist import EntityTagListHeader
+from http_fields.visitors.rfc9110 import EntityTag, IfNoneMatchVisitor
+
+
+class IfNoneMatch(EntityTagListHeader):
+    """If-None-Match header, as defined by RFC 9110. ``wildcard`` (``*``) matches if any
+    current representation exists."""
+
+    name: ClassVar[str] = "If-None-Match"
+    rule: ClassVar[Rule] = rfc9110.Rule("If-None-Match")
+    visitor = IfNoneMatchVisitor()
+
+    def matches(self, entity_tag: EntityTag) -> bool:
+        """Return True if ``entity_tag`` weakly matches none of the tags; False if ``*``."""
+        if self.wildcard:
+            return False
+        return not any(entity_tag.compare(tag, weak=True) for tag in self.entity_tags)

http_fields/ifrange.py

@@ -0,0 +1,49 @@
+"""If-Range header class."""
+
+from dataclasses import dataclass
+from datetime import datetime
+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 EntityTag, HttpDateVisitor, imf_fixdate
+from http_fields.visitors.rfc9110.entitytag import EntityTagVisitor
+
+
+class IfRangeVisitor(NodeVisitor):
+    visit_entity_tag = EntityTagVisitor()
+    visit_http_date = HttpDateVisitor()
+
+    def visit_if_range(self, node: Node) -> EntityTag | datetime:
+        return next(filter(None, map(self.visit, node.children)))
+
+
+@dataclass(frozen=True)
+class IfRange(Header):
+    """If-Range header, as defined by RFC 9110. The condition is an entity-tag or an
+    HTTP-date."""
+
+    name: ClassVar[str] = "If-Range"
+    rule: ClassVar[Rule] = rfc9110.Rule("If-Range")
+    visitor: ClassVar[IfRangeVisitor] = IfRangeVisitor()
+
+    condition: EntityTag | datetime
+
+    def __init__(self, condition: EntityTag | datetime) -> None:
+        # Runtime guard for callers that ignore the type annotation.
+        if not isinstance(condition, (EntityTag, datetime)):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise TypeError("condition must be an EntityTag or datetime.")
+        object.__setattr__(self, "condition", condition)
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        if isinstance(self.condition, datetime):
+            return imf_fixdate(self.condition)
+        return str(self.condition)

http_fields/ifunmodifiedsince.py

@@ -0,0 +1,17 @@
+"""IfUnmodifiedSince 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 IfUnmodifiedSinceVisitor
+
+
+class IfUnmodifiedSince(DateHeader):
+    """If-Unmodified-Since header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "If-Unmodified-Since"
+    rule: ClassVar[Rule] = rfc9110.Rule("If-Unmodified-Since")
+    visitor = IfUnmodifiedSinceVisitor()

http_fields/lastmodified.py

@@ -0,0 +1,17 @@
+"""LastModified 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 LastModifiedVisitor
+
+
+class LastModified(DateHeader):
+    """Last-Modified header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "last-modified"
+    rule: ClassVar[Rule] = rfc9110.Rule("Last-Modified")
+    visitor = LastModifiedVisitor()

http_fields/link.py

@@ -0,0 +1,35 @@
+"""Link header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc8288
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc8288 import LinkValue, LinkVisitor
+
+
+@dataclass(frozen=True)
+class Link(Header):
+    """Link header, as defined by RFC 8288 (Web Linking)."""
+
+    name: ClassVar[str] = "Link"
+    rule: ClassVar[Rule] = rfc8288.Rule("Link")
+    visitor: ClassVar[LinkVisitor] = LinkVisitor()
+
+    links: tuple[LinkValue, ...]
+
+    def __init__(self, *links: LinkValue) -> None:
+        # Each LinkValue self-validates (URIReference target, Param params), so the
+        # field-type check fully guarantees a safe serialized value -- no re-parse.
+        object.__setattr__(self, "links", tuple(links))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(link) for link in self.links)

http_fields/location.py

@@ -0,0 +1,24 @@
+"""Location header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import ParsedStr
+from http_fields.uriheader import UriHeader
+
+
+class LocationUri(ParsedStr):
+    """A Location URI reference (RFC 9110). Self-validating."""
+
+    parser = rfc9110.Rule("Location")
+
+
+class Location(UriHeader):
+    """Location header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "Location"
+    rule: ClassVar[Rule] = rfc9110.Rule("Location")
+    uri_type: ClassVar[type[ParsedStr]] = LocationUri
+    uri: LocationUri

http_fields/maxforwards.py

@@ -0,0 +1,32 @@
+"""Max-Forwards 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 NonNegativeInt
+
+
+@dataclass(frozen=True)
+class MaxForwards(Header):
+    """Max-Forwards header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "Max-Forwards"
+    rule: ClassVar[Rule] = rfc9110.Rule("Max-Forwards")
+
+    forwards: NonNegativeInt
+
+    def __init__(self, forwards: int) -> None:
+        object.__setattr__(self, "forwards", NonNegativeInt(forwards))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(NonNegativeInt(cls._node(value).value))
+
+    @property
+    def value(self) -> str:
+        return str(self.forwards)

http_fields/origin.py

@@ -0,0 +1,42 @@
+"""Origin header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import cors
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.parsedobjs import ParsedStr
+
+
+class OriginValue(ParsedStr):
+    """An Origin value (``scheme://host[:port]`` or ``null``). Self-validating."""
+
+    parser = cors.Rule("Origin")
+
+
+@dataclass(frozen=True)
+class Origin(Header):
+    """Origin header, as defined by RFC 6454 / the Fetch standard.
+
+    The origin (``scheme://host[:port]`` or ``null``) is validated on construction.
+    """
+
+    name: ClassVar[str] = "origin"
+    rule: ClassVar[Rule] = cors.Rule("Origin")
+
+    origin: OriginValue
+
+    def __init__(self, origin: str) -> None:
+        # The origin self-validates as a leaf; build from a string via Origin(...).
+        object.__setattr__(self, "origin", OriginValue(origin))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(value)
+
+    @property
+    def value(self) -> str:
+        return self.origin

http_fields/parsedobjs.py

@@ -0,0 +1,62 @@
+"""A few classes that parse or otherwise check values."""
+
+from typing import Any
+
+from abnf import ParseError, Rule
+
+
+class ParsedStr(str):
+    """str subclass that supports parsing at object creation. Subclasses of ParsedStr
+    supply an abnf Rule used to parse the passed string."""
+
+    parser: Rule
+
+    def __new__(cls, s: Any, parse: bool = True):
+        if isinstance(s, cls):
+            return s
+        else:
+            # if s can't be converted to str, this should fail.
+            _s = str(s)
+            try:
+                return super().__new__(
+                    cls, cls.parser.parse_all(_s).value if parse else _s
+                )
+            except ParseError as exc:
+                raise ValueError(f'Invalid {cls.parser.name} "{s}".') from exc
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({str.__repr__(str(self))})"
+
+
+class CaselessMixin:
+    """Used to define case-insensitive matching for str subclasses."""
+
+    def __eq__(self, __o: object) -> bool:
+        # comparison should be case-insensitive.
+        return (
+            self.casefold() == __o.casefold()
+            if isinstance(self, str) and isinstance(__o, str)
+            else NotImplemented
+        )
+
+    def __hash__(self) -> int:
+        # and because we redefined __eq__, we need to redefine __hash__ for consistency.
+        assert isinstance(self, str)
+        return hash(self.casefold())
+
+
+class NonNegativeInt(int):
+    """Non-negative int type."""
+
+    def __new__(cls, value: Any):
+        if isinstance(value, cls):
+            return value
+        else:
+            if isinstance(value, float) and not value.is_integer():
+                # int(3.7) would silently truncate; reject non-integral input.
+                raise ValueError("Value must be a whole number.")
+            val = super().__new__(cls, value)
+            if val >= 0:
+                return val
+            else:
+                raise ValueError("Value must be non-negative.")

http_fields/prefer.py

@@ -0,0 +1,64 @@
+"""Prefer and Preference-Applied header classes."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc7240
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc7240 import (
+    Preference,
+    PreferenceAppliedVisitor,
+    PreferVisitor,
+)
+
+
+@dataclass(frozen=True)
+class Prefer(Header):
+    """Prefer header, as defined by RFC 7240."""
+
+    name: ClassVar[str] = "Prefer"
+    rule: ClassVar[Rule] = rfc7240.Rule("Prefer")
+    visitor: ClassVar[PreferVisitor] = PreferVisitor()
+
+    preferences: tuple[Preference, ...]
+
+    def __init__(self, *preferences: Preference) -> None:
+        # Each Preference self-validates (Token name, leaf value, Param parameters), so
+        # the field-type check fully guarantees a safe serialized value -- no re-parse.
+        object.__setattr__(self, "preferences", tuple(preferences))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        # the grammar rule matches the whole header line, so prepend the field name.
+        return cls(*cls.visitor.visit(cls._prefixed_node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(pref) for pref in self.preferences)
+
+
+@dataclass(frozen=True)
+class PreferenceApplied(Header):
+    """Preference-Applied header, as defined by RFC 7240."""
+
+    name: ClassVar[str] = "Preference-Applied"
+    rule: ClassVar[Rule] = rfc7240.Rule("Preference-Applied")
+    visitor: ClassVar[PreferenceAppliedVisitor] = PreferenceAppliedVisitor()
+
+    preferences: tuple[Preference, ...]
+
+    def __init__(self, *preferences: Preference) -> None:
+        # Each Preference self-validates (Token name, leaf value, Param parameters), so
+        # the field-type check fully guarantees a safe serialized value -- no re-parse.
+        object.__setattr__(self, "preferences", tuple(preferences))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._prefixed_node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(pref) for pref in self.preferences)

http_fields/priority.py

@@ -0,0 +1,55 @@
+"""Priority header class."""
+
+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 Item, parse_dictionary, serialize_dictionary
+
+
+@dataclass(frozen=True)
+class Priority(Header):
+    """Priority header, as defined by RFC 9218: a Structured Fields Dictionary with an
+    ``urgency`` (0-7, default 3) and an ``incremental`` flag (default False). Default values
+    are omitted from the serialized value."""
+
+    name: ClassVar[str] = "priority"
+    rule: ClassVar[Rule] = rfc9651.Rule("sf-dictionary")
+
+    urgency: int = 3
+    incremental: bool = False
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        cls._check_length(value)
+        try:
+            members = dict(parse_dictionary(value))
+        except ParseError as exc:
+            raise ValueError(f'Invalid {cls.__name__} value "{value}".') from exc
+        urgency = 3
+        incremental = False
+        u = members.get("u")
+        if (
+            isinstance(u, Item)
+            and isinstance(u.value, int)
+            and not isinstance(u.value, bool)
+            and 0 <= u.value <= 7
+        ):
+            urgency = u.value
+        i = members.get("i")
+        if isinstance(i, Item) and isinstance(i.value, bool):
+            incremental = i.value
+        return cls(urgency, incremental)
+
+    @property
+    def value(self) -> str:
+        members: list[tuple[str, Item]] = []
+        if self.urgency != 3:
+            members.append(("u", Item(self.urgency)))
+        if self.incremental:
+            members.append(("i", Item(True)))
+        return serialize_dictionary(tuple(members))

http_fields/productlistheader.py

@@ -0,0 +1,33 @@
+"""Base class for headers that are a list of products and comments."""
+
+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 Comment, Product
+
+
+@dataclass(frozen=True)
+class ProductListHeader(Header):
+    """Base for headers that are a whitespace-separated list of Product/Comment items
+    (User-Agent, Server). Concrete subclasses supply ``name``/``rule``/``visitor``."""
+
+    visitor: ClassVar[NodeVisitor]
+
+    items: tuple[Product | Comment, ...]
+
+    def __init__(self, *items: Product | Comment) -> None:
+        object.__setattr__(self, "items", tuple(items))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        # the grammar requires at least one SP/TAB between items, so a source with multiple
+        # spaces between items is not reassembled identically.
+        return " ".join(str(item) for item in self.items)

http_fields/proxyauthenticate.py

@@ -0,0 +1,17 @@
+"""Proxy-Authenticate header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.authbases import ChallengeListHeader
+from http_fields.visitors.rfc9110 import ProxyAuthenticateVisitor
+
+
+class ProxyAuthenticate(ChallengeListHeader):
+    """Proxy-Authenticate header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "proxy-authenticate"
+    rule: ClassVar[Rule] = rfc9110.Rule("Proxy-Authenticate")
+    visitor = ProxyAuthenticateVisitor()

http_fields/proxyauthenticationinfo.py

@@ -0,0 +1,17 @@
+"""Proxy-Authentication-Info header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.authbases import AuthParamsHeader
+from http_fields.visitors.rfc9110 import ProxyAuthenticationInfoVisitor
+
+
+class ProxyAuthenticationInfo(AuthParamsHeader):
+    """Proxy-Authentication-Info header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "proxy-authentication-info"
+    rule: ClassVar[Rule] = rfc9110.Rule("Proxy-Authentication-Info")
+    visitor = ProxyAuthenticationInfoVisitor()

http_fields/proxyauthorization.py

@@ -0,0 +1,17 @@
+"""Proxy-Authorization header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.authbases import CredentialsHeader
+from http_fields.visitors.rfc9110 import ProxyAuthorizationVisitor
+
+
+class ProxyAuthorization(CredentialsHeader):
+    """Proxy-Authorization header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "proxy-authorization"
+    rule: ClassVar[Rule] = rfc9110.Rule("Proxy-Authorization")
+    visitor = ProxyAuthorizationVisitor()

http_fields/proxystatus.py

@@ -0,0 +1,12 @@
+"""Proxy-Status header class."""
+
+from typing import ClassVar
+
+from http_fields.structuredheaders import StructuredListHeader
+
+
+class ProxyStatus(StructuredListHeader):
+    """Proxy-Status header, as defined by RFC 9209. Each ``members`` item identifies an
+    intermediary (its bare value) and carries parameters such as ``error`` and ``next-hop``."""
+
+    name: ClassVar[str] = "proxy-status"

http_fields/range.py

@@ -0,0 +1,37 @@
+"""Range 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 RangeUnit
+from http_fields.visitors.rfc9110.range import IntRange, RangeVisitor, SuffixRange
+
+
+@dataclass(frozen=True)
+class Range(Header):
+    """Range header, as defined by RFC 9110, e.g. ``bytes=0-499,-500``."""
+
+    name: ClassVar[str] = "Range"
+    rule: ClassVar[Rule] = rfc9110.Rule("Range")
+    visitor: ClassVar[RangeVisitor] = RangeVisitor()
+
+    range_unit: RangeUnit
+    ranges: tuple[IntRange | SuffixRange, ...]
+
+    def __init__(self, range_unit: str, *ranges: IntRange | SuffixRange) -> None:
+        object.__setattr__(self, "range_unit", RangeUnit(range_unit))
+        object.__setattr__(self, "ranges", tuple(ranges))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        range_unit, ranges = cls.visitor.visit(cls._node(value))
+        return cls(range_unit, *ranges)
+
+    @property
+    def value(self) -> str:
+        return f"{self.range_unit}={','.join(str(r) for r in self.ranges)}"