http-fields 0.1.1__py3-none-any.whl

http_fields/altsvc.py

@@ -0,0 +1,70 @@
+"""Alt-Svc and Alt-Used header classes."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc7838
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.parsedobjs import ParsedStr
+from http_fields.visitors.rfc7838 import AltSvcVisitor, AltValue
+
+
+class AltUsedAuthority(ParsedStr):
+    """An Alt-Used authority (the alternative ``host[:port]`` actually used). Self-validating."""
+
+    parser = rfc7838.Rule("Alt-Used")
+
+
+@dataclass(frozen=True)
+class AltSvc(Header):
+    """Alt-Svc header, as defined by RFC 7838. The special value ``clear`` is represented by
+    ``clear=True`` with no ``values``."""
+
+    name: ClassVar[str] = "Alt-Svc"
+    rule: ClassVar[Rule] = rfc7838.Rule("Alt-Svc")
+    visitor: ClassVar[AltSvcVisitor] = AltSvcVisitor()
+
+    values: tuple[AltValue, ...] = ()
+    clear: bool = False
+
+    def __init__(self, *values: AltValue, clear: bool = False) -> None:
+        # Each AltValue self-validates (ProtocolId/AltAuthority/Param), so the field-type
+        # check fully guarantees a safe serialized value -- no re-parse.
+        object.__setattr__(self, "values", tuple(values))
+        object.__setattr__(self, "clear", clear)
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        if value.strip().lower() == "clear":
+            cls._node(value)  # validate
+            return cls(clear=True)
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return "clear" if self.clear else ", ".join(str(v) for v in self.values)
+
+
+@dataclass(frozen=True)
+class AltUsed(Header):
+    """Alt-Used header, as defined by RFC 7838: the alternative authority actually used."""
+
+    name: ClassVar[str] = "Alt-Used"
+    rule: ClassVar[Rule] = rfc7838.Rule("Alt-Used")
+
+    authority: AltUsedAuthority
+
+    def __init__(self, authority: str) -> None:
+        # The authority self-validates as a leaf; build from a string via AltUsed(...).
+        object.__setattr__(self, "authority", AltUsedAuthority(authority))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(value)
+
+    @property
+    def value(self) -> str:
+        return self.authority

http_fields/authbases.py

@@ -0,0 +1,79 @@
+"""Base classes for the authentication / authorization header families.
+
+These pair a request/response header with its proxy counterpart:
+``ChallengeListHeader`` (WWW-Authenticate / Proxy-Authenticate), ``CredentialsHeader``
+(Authorization / Proxy-Authorization), and ``AuthParamsHeader`` (Authentication-Info /
+Proxy-Authentication-Info). Concrete subclasses supply ``name``/``rule``/``visitor``.
+"""
+
+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 (
+    AuthParam,
+    AuthParamChallenge,
+    AuthParamCredentials,
+    TokenChallenge,
+    TokenCredentials,
+)
+
+
+@dataclass(frozen=True)
+class ChallengeListHeader(Header):
+    """Base for headers that are a list of authentication challenges."""
+
+    visitor: ClassVar[NodeVisitor]
+
+    challenges: tuple[TokenChallenge | AuthParamChallenge, ...]
+
+    def __init__(self, *challenges: TokenChallenge | AuthParamChallenge) -> None:
+        object.__setattr__(self, "challenges", tuple(challenges))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(challenge) for challenge in self.challenges)
+
+
+@dataclass(frozen=True)
+class CredentialsHeader(Header):
+    """Base for headers carrying a single credentials value."""
+
+    visitor: ClassVar[NodeVisitor]
+
+    credentials: TokenCredentials | AuthParamCredentials
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return str(self.credentials)
+
+
+@dataclass(frozen=True)
+class AuthParamsHeader(Header):
+    """Base for headers that are a list of auth-params."""
+
+    visitor: ClassVar[NodeVisitor]
+
+    auth_params: tuple[AuthParam, ...] = ()
+
+    def __init__(self, *auth_params: AuthParam) -> None:
+        object.__setattr__(self, "auth_params", tuple(auth_params))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ",".join(str(p) for p in self.auth_params)

http_fields/authenticationinfo.py

@@ -0,0 +1,19 @@
+"""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 AuthenticationInfoVisitor, AuthParam
+
+__all__ = ["AuthenticationInfo", "AuthParam"]
+
+
+class AuthenticationInfo(AuthParamsHeader):
+    """Authentication-Info header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "authentication-info"
+    rule: ClassVar[Rule] = rfc9110.Rule("Authentication-Info")
+    visitor = AuthenticationInfoVisitor()

http_fields/authorization.py

@@ -0,0 +1,23 @@
+"""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 (
+    AuthorizationVisitor,
+    AuthParamCredentials,
+    TokenCredentials,
+)
+
+__all__ = ["AuthParamCredentials", "Authorization", "TokenCredentials"]
+
+
+class Authorization(CredentialsHeader):
+    """Authorization header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "Authorization"
+    rule: ClassVar[Rule] = rfc9110.Rule("Authorization")
+    visitor = AuthorizationVisitor()

http_fields/cachecontrol.py

@@ -0,0 +1,119 @@
+"""Cache-Control header class."""
+
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9111
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.parsedobjs import NonNegativeInt
+from http_fields.visitors.rfc9111 import CacheControlVisitor, CacheDirective
+
+# directive-name -> field-name maps, shared by parse() and value.
+_BOOL = {
+    "immutable": "immutable",
+    "public": "public",
+    "no-store": "no_store",
+    "no-transform": "no_transform",
+    "must-revalidate": "must_revalidate",
+    "proxy-revalidate": "proxy_revalidate",
+    "only-if-cached": "only_if_cached",
+}
+_INT = {
+    "max-age": "max_age",
+    "max-stale": "max_stale",
+    "min-fresh": "min_fresh",
+    "s-maxage": "s_maxage",
+}
+_BOOL_OR_STR = {"no-cache": "no_cache", "private": "private"}
+
+
+@dataclass(frozen=True, kw_only=True)
+class CacheControl(Header):
+    """Cache-Control header, as defined by RFC 9111.
+
+    The ``no_cache`` and ``private`` directives may be ``True`` or a string of field names.
+    Non-standard directives are carried in ``cache_extension``.
+    """
+
+    name: ClassVar[str] = "Cache-Control"
+    rule: ClassVar[Rule] = rfc9111.Rule("Cache-Control")
+    visitor: ClassVar[CacheControlVisitor] = CacheControlVisitor()
+
+    immutable: bool = False
+    public: bool = False
+    private: bool | str = False
+    no_cache: bool | str = False
+    no_store: bool = False
+    no_transform: bool = False
+    must_revalidate: bool = False
+    proxy_revalidate: bool = False
+    max_age: int | None = None
+    # max_stale is None when absent, True when valueless ("stale of any age",
+    # RFC 9111 section 5.2.1.2), or an int delta-seconds bound.
+    max_stale: int | bool | None = None
+    min_fresh: int | None = None
+    only_if_cached: bool = False
+    s_maxage: int | None = None
+    cache_extension: tuple[CacheDirective, ...] = ()
+
+    def __post_init__(self) -> None:
+        # fail-fast coercion of the int-valued directives (frozen -> setattr).
+        for attr in ("max_age", "min_fresh", "s_maxage"):
+            v = getattr(self, attr)
+            if v is not None:
+                object.__setattr__(self, attr, NonNegativeInt(v))
+        # max-stale may be valueless (True); only coerce a delta-seconds bound.
+        if self.max_stale is not None and self.max_stale is not True:
+            object.__setattr__(self, "max_stale", NonNegativeInt(self.max_stale))
+        # Enforce the declared field types (e.g. no-cache/private must be bool | str, not a
+        # list that CacheDirective would silently swallow as a valueless directive).
+        super().__post_init__()
+        # Serializing builds a self-validating CacheDirective for each field (name -> Token,
+        # no-cache/private string -> QuotedString, ints -> NonNegativeInt), rejecting invalid
+        # content, 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:
+        kw: dict[str, Any] = {}
+        extension: list[CacheDirective] = []
+        for directive in cls.visitor.visit(cls._node(value)):
+            n = str(directive.name)
+            if n in _BOOL:
+                kw[_BOOL[n]] = True
+            elif n in _INT:
+                kw[_INT[n]] = directive.value
+            elif n in _BOOL_OR_STR:
+                kw[_BOOL_OR_STR[n]] = (
+                    directive.value if isinstance(directive.value, str) else True
+                )
+            else:
+                extension.append(directive)
+        return cls(**kw, cache_extension=tuple(extension))
+
+    @property
+    def value(self) -> str:
+        out: list[CacheDirective] = []
+        for n, attr in _BOOL.items():
+            if getattr(self, attr):
+                out.append(CacheDirective(n))
+        for n, attr in _INT.items():
+            v = getattr(self, attr)
+            if v is None:
+                continue
+            if attr == "max_stale" and v is True:  # valueless max-stale
+                out.append(CacheDirective(n))
+            else:  # keep 0, unlike a truthiness check
+                out.append(CacheDirective(n, v))
+        for n, attr in _BOOL_OR_STR.items():
+            v = getattr(self, attr)
+            if isinstance(v, str):
+                out.append(CacheDirective(n, v))
+            elif v:
+                out.append(CacheDirective(n))
+        out.extend(self.cache_extension)
+        return ",".join(str(directive) for directive in out)

http_fields/cachestatus.py

@@ -0,0 +1,12 @@
+"""Cache-Status header class."""
+
+from typing import ClassVar
+
+from http_fields.structuredheaders import StructuredListHeader
+
+
+class CacheStatus(StructuredListHeader):
+    """Cache-Status header, as defined by RFC 9211. Each ``members`` item identifies a cache
+    (its bare value) and carries parameters such as ``hit``, ``fwd``, ``ttl``, and ``detail``."""
+
+    name: ClassVar[str] = "cache-status"

http_fields/connection.py

@@ -0,0 +1,35 @@
+"""Connection 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 ConnectionVisitor, Token
+
+
+@dataclass(frozen=True)
+class Connection(Header):
+    """Connection header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "connection"
+    rule: ClassVar[Rule] = rfc9110.Rule("Connection")
+    visitor: ClassVar[ConnectionVisitor] = ConnectionVisitor()
+
+    directives: tuple[Token, ...]
+
+    def __init__(self, *directives: Token) -> None:
+        object.__setattr__(self, "directives", tuple(directives))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(
+            *(Token(d, parse=False) for d in cls.visitor.visit(cls._node(value)))
+        )
+
+    @property
+    def value(self) -> str:
+        return ",".join(self.directives)

http_fields/contentdigest.py

@@ -0,0 +1,19 @@
+"""Content-Digest and Repr-Digest header classes."""
+
+from typing import ClassVar
+
+from http_fields.structuredheaders import DigestHeader
+
+
+class ContentDigest(DigestHeader):
+    """Content-Digest header, as defined by RFC 9530: a Dictionary of algorithm name to the
+    byte-sequence digest of the message content."""
+
+    name: ClassVar[str] = "content-digest"
+
+
+class ReprDigest(DigestHeader):
+    """Repr-Digest header, as defined by RFC 9530: like Content-Digest, but over the selected
+    representation."""
+
+    name: ClassVar[str] = "repr-digest"

http_fields/contentdisposition.py

@@ -0,0 +1,66 @@
+"""Content-Disposition header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import ParseError, Rule
+from abnf.grammars import rfc6266
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc6266 import (
+    ContentDispositionNodeVisitor,
+    DispExtParm,
+    DispositionType,
+    ExtValue,
+    FilenameParm,
+)
+
+
+@dataclass(frozen=True)
+class ContentDisposition(Header):
+    """Content-Disposition header, as defined by RFC 6266."""
+
+    name: ClassVar[str] = "Content-Disposition"
+    rule: ClassVar[Rule] = rfc6266.Rule("content-disposition")
+    visitor: ClassVar[ContentDispositionNodeVisitor] = ContentDispositionNodeVisitor()
+
+    disposition_type: DispositionType
+    disposition_parms: tuple[FilenameParm | DispExtParm, ...] = ()
+
+    @classmethod
+    def build(
+        cls,
+        disposition_type: str,
+        disposition_parms: dict[str, str | ExtValue] | None = None,
+    ) -> Self:
+        """Build a Content-Disposition from a disposition type and a parameter mapping.
+
+        A parameter named ``filename`` or ``filename*`` (case-insensitive) becomes a
+        FilenameParm; anything else becomes a DispExtParm.
+        """
+        parms = tuple(
+            FilenameParm(pname, pvalue)
+            if pname.lower() in {"filename", "filename*"}
+            else DispExtParm(pname, pvalue)
+            for pname, pvalue in (disposition_parms or {}).items()
+        )
+        return cls(DispositionType(disposition_type), parms)
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        # unlike most header rules, 'content-disposition' matches the whole header line, so
+        # we prepend the field name before parsing.
+        cls._check_length(value)
+        try:
+            node = cls.rule.parse_all(f"content-disposition: {value}")
+        except ParseError as exc:
+            raise ValueError(f'Invalid {cls.__name__} value "{value}".') from exc
+        disposition_type, parms = cls.visitor.visit(node)
+        return cls(disposition_type, tuple(parms))
+
+    @property
+    def value(self) -> str:
+        return str(self.disposition_type) + "".join(
+            f";{parm}" for parm in self.disposition_parms
+        )

http_fields/contentencoding.py

@@ -0,0 +1,45 @@
+"""ContentEncoding header class."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+from abnf.parser import Node, NodeVisitor
+from typing_extensions import Self
+
+from http_fields.header import Header
+from http_fields.visitors.rfc9110 import Token
+
+
+class ContentEncodingVisitor(NodeVisitor):
+    def visit_content_encoding(self, node: Node) -> list[str]:
+        return list(filter(None, map(self.visit, node.children)))
+
+    @staticmethod
+    def visit_content_coding(node: Node) -> str:
+        return node.value
+
+
+@dataclass(frozen=True)
+class ContentEncoding(Header):
+    """Content-Encoding header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "content-encoding"
+    rule: ClassVar[Rule] = rfc9110.Rule("Content-Encoding")
+    visitor: ClassVar[ContentEncodingVisitor] = ContentEncodingVisitor()
+
+    codings: tuple[Token, ...]
+
+    def __init__(self, *codings: Token) -> None:
+        object.__setattr__(self, "codings", tuple(codings))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(
+            *(Token(c, parse=False) for c in cls.visitor.visit(cls._node(value)))
+        )
+
+    @property
+    def value(self) -> str:
+        return ", ".join(self.codings)

http_fields/contentlanguage.py

@@ -0,0 +1,38 @@
+"""Content-Language 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.contentlanguage import (
+    ContentLanguageVisitor,
+    LanguageTag,
+)
+
+
+@dataclass(frozen=True)
+class ContentLanguage(Header):
+    """Content-Language header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "content-language"
+    rule: ClassVar[Rule] = rfc9110.Rule("Content-Language")
+    visitor: ClassVar[ContentLanguageVisitor] = ContentLanguageVisitor()
+
+    languages: tuple[LanguageTag, ...]
+
+    def __init__(self, *languages: LanguageTag) -> None:
+        object.__setattr__(self, "languages", tuple(languages))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(
+            *(LanguageTag(x, parse=False) for x in cls.visitor.visit(cls._node(value)))
+        )
+
+    @property
+    def value(self) -> str:
+        return ", ".join(self.languages)

http_fields/contentlength.py

@@ -0,0 +1,34 @@
+"""ContentLength 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 ContentLengthVisitor
+
+
+@dataclass(frozen=True)
+class ContentLength(Header):
+    """Content-Length header."""
+
+    name: ClassVar[str] = "content-length"
+    rule: ClassVar[Rule] = rfc9110.Rule("Content-Length")
+    visitor: ClassVar[ContentLengthVisitor] = ContentLengthVisitor()
+
+    length: NonNegativeInt
+
+    def __init__(self, length: int) -> None:
+        object.__setattr__(self, "length", NonNegativeInt(length))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return str(self.length)

http_fields/contentlocation.py

@@ -0,0 +1,24 @@
+"""Content-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 ContentLocationUri(ParsedStr):
+    """A Content-Location URI reference (RFC 9110). Self-validating."""
+
+    parser = rfc9110.Rule("Content-Location")
+
+
+class ContentLocation(UriHeader):
+    """Content-Location header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "content-location"
+    rule: ClassVar[Rule] = rfc9110.Rule("Content-Location")
+    uri_type: ClassVar[type[ParsedStr]] = ContentLocationUri
+    uri: ContentLocationUri

http_fields/contentrange.py

@@ -0,0 +1,74 @@
+"""Content-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.parsedobjs import NonNegativeInt
+from http_fields.visitors.rfc9110 import ContentRangeVisitor, RangeUnit
+from http_fields.visitors.rfc9110.contentrange import RangeResp
+
+
+@dataclass(frozen=True)
+class ContentRange(Header):
+    """Content-Range header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "content-range"
+    rule: ClassVar[Rule] = rfc9110.Rule("Content-Range")
+    visitor: ClassVar[ContentRangeVisitor] = ContentRangeVisitor()
+
+    range_unit: RangeUnit
+    first_pos: NonNegativeInt | None
+    last_pos: NonNegativeInt | None
+    complete_length: NonNegativeInt | None
+
+    def __init__(
+        self,
+        range_unit: str,
+        *,
+        first_pos: int | None = None,
+        last_pos: int | None = None,
+        complete_length: int | None = None,
+    ) -> None:
+        if (first_pos is None) != (last_pos is None):
+            raise ValueError(
+                "Both first_pos and last_pos must be given, or both omitted."
+            )
+        if first_pos is None and complete_length is None:
+            raise ValueError(
+                "complete_length is required when first_pos and last_pos are omitted."
+            )
+        object.__setattr__(self, "range_unit", RangeUnit(range_unit))
+        object.__setattr__(
+            self, "first_pos", None if first_pos is None else NonNegativeInt(first_pos)
+        )
+        object.__setattr__(
+            self, "last_pos", None if last_pos is None else NonNegativeInt(last_pos)
+        )
+        object.__setattr__(
+            self,
+            "complete_length",
+            None if complete_length is None else NonNegativeInt(complete_length),
+        )
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        range_unit, rng = cls.visitor.visit(cls._node(value))
+        satisfied = isinstance(rng, RangeResp)
+        return cls(
+            range_unit,
+            first_pos=rng.first_pos if satisfied else None,
+            last_pos=rng.last_pos if satisfied else None,
+            complete_length=rng.complete_length,
+        )
+
+    @property
+    def value(self) -> str:
+        if self.first_pos is not None and self.last_pos is not None:
+            length = self.complete_length if self.complete_length is not None else "*"
+            return f"{self.range_unit} {self.first_pos}-{self.last_pos}/{length}"
+        return f"{self.range_unit} */{self.complete_length}"