http-fields 0.1.1__py3-none-any.whl

http_fields/__init__.py

@@ -0,0 +1,193 @@
+"""Header classes.  All classes intended for public use are imported here."""
+
+__all__ = [
+    "Accept",
+    "AcceptCharset",
+    "AcceptLanguage",
+    "AcceptEncoding",
+    "AcceptRanges",
+    "AccessControlAllowCredentials",
+    "AccessControlAllowHeaders",
+    "AccessControlAllowMethods",
+    "AccessControlAllowOrigin",
+    "AccessControlExposeHeaders",
+    "AccessControlMaxAge",
+    "AccessControlRequestHeaders",
+    "AccessControlRequestMethod",
+    "Age",
+    "Allow",
+    "AltSvc",
+    "AltUsed",
+    "AuthenticationInfo",
+    "Authorization",
+    "AuthParam",
+    "CacheControl",
+    "CacheDirective",
+    "CacheStatus",
+    "Connection",
+    "ContentDigest",
+    "ContentDisposition",
+    "ContentEncoding",
+    "ContentLanguage",
+    "ContentLength",
+    "ContentLocation",
+    "ContentRange",
+    "ContentType",
+    "Cookie",
+    "CustomHeader",
+    "Date",
+    "EntityTag",
+    "ETag",
+    "Expect",
+    "Expires",
+    "Forwarded",
+    "From",
+    "Header",
+    "Host",
+    "IfMatch",
+    "IfModifiedSince",
+    "IfNoneMatch",
+    "IfRange",
+    "IfUnmodifiedSince",
+    "LanguageTag",
+    "LastModified",
+    "Link",
+    "Location",
+    "MaxForwards",
+    "MediaType",
+    "Origin",
+    "Prefer",
+    "PreferenceApplied",
+    "Priority",
+    "RangeUnit",
+    "NonNegativeInt",
+    "Protocol",
+    "ProxyAuthenticate",
+    "ProxyAuthenticationInfo",
+    "ProxyAuthorization",
+    "ProxyStatus",
+    "Range",
+    "Referer",
+    "ReprDigest",
+    "RetryAfter",
+    "Server",
+    "SetCookie",
+    "StrictTransportSecurity",
+    "TCoding",
+    "TE",
+    "Trailer",
+    "Upgrade",
+    "UserAgent",
+    "Vary",
+    "Via",
+    "WWWAuthenticate",
+    "ExtValue",
+    "CookiePair",
+    "AltValue",
+    "ForwardedElement",
+    "IntRange",
+    "LinkValue",
+    "Preference",
+    "SuffixRange",
+    "ViaElement",
+    "WeightedCoding",
+    "WeightedLanguageRange",
+    # Leaf types for strict list-header construction (e.g. Connection(Token("keep-alive"))).
+    "CorsFieldName",
+    "CorsMethod",
+    "Expectation",
+    "FieldName",
+    "Method",
+    "Token",
+]
+
+from http_fields.accept import Accept
+from http_fields.acceptcharset import AcceptCharset
+from http_fields.acceptencoding import AcceptEncoding, WeightedCoding
+from http_fields.acceptlanguage import AcceptLanguage
+from http_fields.acceptranges import AcceptRanges
+from http_fields.accesscontrol import (
+    AccessControlAllowCredentials,
+    AccessControlAllowHeaders,
+    AccessControlAllowMethods,
+    AccessControlAllowOrigin,
+    AccessControlExposeHeaders,
+    AccessControlMaxAge,
+    AccessControlRequestHeaders,
+    AccessControlRequestMethod,
+    CorsFieldName,
+    CorsMethod,
+)
+from http_fields.age import Age
+from http_fields.allow import Allow, Method
+from http_fields.altsvc import AltSvc, AltUsed
+from http_fields.authenticationinfo import AuthenticationInfo
+from http_fields.authorization import Authorization
+from http_fields.cachecontrol import CacheControl, CacheDirective
+from http_fields.cachestatus import CacheStatus
+from http_fields.connection import Connection
+from http_fields.contentdigest import ContentDigest, ReprDigest
+from http_fields.contentdisposition import ContentDisposition, ExtValue
+from http_fields.contentencoding import ContentEncoding
+from http_fields.contentlanguage import ContentLanguage
+from http_fields.contentlength import ContentLength
+from http_fields.contentlocation import ContentLocation
+from http_fields.contentrange import ContentRange
+from http_fields.contenttype import ContentType
+from http_fields.cookie import Cookie, CookiePair
+from http_fields.date import Date
+from http_fields.etag import ETag
+from http_fields.expect import Expect, Expectation
+from http_fields.expires import Expires
+from http_fields.forwarded import Forwarded
+from http_fields.fromheader import From
+from http_fields.header import CustomHeader, Header
+from http_fields.host import Host
+from http_fields.ifmatch import IfMatch
+from http_fields.ifmodifiedsince import IfModifiedSince
+from http_fields.ifnonematch import IfNoneMatch
+from http_fields.ifrange import IfRange
+from http_fields.ifunmodifiedsince import IfUnmodifiedSince
+from http_fields.lastmodified import LastModified
+from http_fields.link import Link
+from http_fields.location import Location
+from http_fields.maxforwards import MaxForwards
+from http_fields.origin import Origin
+from http_fields.parsedobjs import NonNegativeInt
+from http_fields.prefer import Prefer, PreferenceApplied
+from http_fields.priority import Priority
+from http_fields.proxyauthenticate import ProxyAuthenticate
+from http_fields.proxyauthenticationinfo import ProxyAuthenticationInfo
+from http_fields.proxyauthorization import ProxyAuthorization
+from http_fields.proxystatus import ProxyStatus
+from http_fields.range import Range
+from http_fields.referer import Referer
+from http_fields.retryafter import RetryAfter
+from http_fields.server import Server
+from http_fields.setcookie import SetCookie
+from http_fields.stricttransportsecurity import StrictTransportSecurity
+from http_fields.te import TE
+from http_fields.trailer import Trailer
+from http_fields.upgrade import Upgrade
+from http_fields.useragent import UserAgent
+from http_fields.vary import Vary
+from http_fields.via import Via
+from http_fields.visitors.rfc7239 import ForwardedElement
+from http_fields.visitors.rfc7240 import Preference
+from http_fields.visitors.rfc7838 import AltValue
+from http_fields.visitors.rfc8288 import LinkValue
+from http_fields.visitors.rfc9110 import (
+    AuthParam,
+    EntityTag,
+    FieldName,
+    MediaType,
+    RangeUnit,
+    Token,
+    WeightedLanguageRange,
+)
+from http_fields.visitors.rfc9110.contentlanguage import LanguageTag
+from http_fields.visitors.rfc9110.range import IntRange, SuffixRange
+from http_fields.visitors.rfc9110.te import TCoding
+from http_fields.visitors.rfc9110.upgrade import Protocol
+from http_fields.visitors.rfc9110.via import ViaElement
+from http_fields.wwwauthenticate import WWWAuthenticate

http_fields/accept.py

@@ -0,0 +1,37 @@
+"""Accept 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 AcceptType, AcceptVisitor
+
+
+@dataclass(frozen=True)
+class Accept(Header):
+    """Accept header, as defined by RFC 9110.
+
+    An Accept header may have an empty value (``Accept:``), which is treated as accepting
+    any media type. RFC 9110 no longer includes ext-params (accept-ext) in the grammar.
+    """
+
+    name: ClassVar[str] = "Accept"
+    rule: ClassVar[Rule] = rfc9110.Rule("Accept")
+    visitor: ClassVar[AcceptVisitor] = AcceptVisitor()
+
+    accept_types: tuple[AcceptType, ...]
+
+    def __init__(self, *accept_types: AcceptType) -> None:
+        object.__setattr__(self, "accept_types", tuple(accept_types))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(accept_type) for accept_type in self.accept_types)

http_fields/acceptcharset.py

@@ -0,0 +1,48 @@
+"""Accept-Charset 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 AcceptCharsetVisitor, Token, Weight
+
+
+def _as_weight(value: float | Weight | None) -> Weight | None:
+    """Normalize a weight argument to a Weight or None. A numeric 0 is a valid weight
+    ("not acceptable"), so only None means "no weight specified"."""
+    if isinstance(value, Weight):
+        return value
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return Weight(float(value))
+    return None
+
+
+@dataclass(frozen=True)
+class AcceptCharset(Header):
+    """Accept-Charset header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "accept-charset"
+    rule: ClassVar[Rule] = rfc9110.Rule("Accept-Charset")
+    visitor: ClassVar[AcceptCharsetVisitor] = AcceptCharsetVisitor()
+
+    charsets: tuple[tuple[Token, Weight | None], ...]
+
+    def __init__(self, *charsets: tuple[str, float | Weight | None]) -> None:
+        object.__setattr__(
+            self, "charsets", tuple((Token(c), _as_weight(w)) for c, w in charsets)
+        )
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(
+            f"{charset}" + (f";{weight}" if weight is not None else "")
+            for charset, weight in self.charsets
+        )

http_fields/acceptencoding.py

@@ -0,0 +1,42 @@
+"""Accept-Encoding 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 AcceptEncodingVisitor, Weight, WeightedCoding
+
+
+@dataclass(frozen=True)
+class AcceptEncoding(Header):
+    """Accept-Encoding header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "accept-encoding"
+    rule: ClassVar[Rule] = rfc9110.Rule("Accept-Encoding")
+    visitor: ClassVar[AcceptEncodingVisitor] = AcceptEncodingVisitor()
+
+    codings: tuple[WeightedCoding, ...]
+
+    def __init__(
+        self, *codings: WeightedCoding | tuple[str, float | Weight | None]
+    ) -> None:
+        object.__setattr__(
+            self,
+            "codings",
+            tuple(
+                c if isinstance(c, WeightedCoding) else WeightedCoding(*c)
+                for c in 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/acceptlanguage.py

@@ -0,0 +1,47 @@
+"""Accept-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 import (
+    AcceptLanguageVisitor,
+    Weight,
+    WeightedLanguageRange,
+)
+
+
+@dataclass(frozen=True)
+class AcceptLanguage(Header):
+    """Accept-Language header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "accept-language"
+    rule: ClassVar[Rule] = rfc9110.Rule("Accept-Language")
+    visitor: ClassVar[AcceptLanguageVisitor] = AcceptLanguageVisitor()
+
+    language_ranges: tuple[WeightedLanguageRange, ...]
+
+    def __init__(
+        self,
+        *language_ranges: WeightedLanguageRange | tuple[str, float | Weight | None],
+    ) -> None:
+        object.__setattr__(
+            self,
+            "language_ranges",
+            tuple(
+                r if isinstance(r, WeightedLanguageRange) else WeightedLanguageRange(*r)
+                for r in language_ranges
+            ),
+        )
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(*cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return ", ".join(str(r) for r in self.language_ranges)

http_fields/acceptranges.py

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

http_fields/accesscontrol.py

@@ -0,0 +1,197 @@
+"""Access-Control-* (CORS) header classes, as defined by the Fetch standard.
+
+The grammar comes from abnf's ``cors`` module.
+"""
+
+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 NonNegativeInt, ParsedStr
+
+
+class CorsMethod(ParsedStr):
+    """A CORS method token. Self-validating."""
+
+    parser = cors.Rule("method")
+
+
+class CorsFieldName(ParsedStr):
+    """A CORS field-name. Self-validating."""
+
+    parser = cors.Rule("field-name")
+
+
+class AllowedOrigin(ParsedStr):
+    """An Access-Control-Allow-Origin value (an origin, ``null``, or ``*``). Self-validating."""
+
+    parser = cors.Rule("Access-Control-Allow-Origin")
+
+
+class RequestedMethod(ParsedStr):
+    """An Access-Control-Request-Method value (a single method). Self-validating."""
+
+    parser = cors.Rule("Access-Control-Request-Method")
+
+
+__all__ = [
+    "AccessControlAllowCredentials",
+    "AccessControlAllowHeaders",
+    "AccessControlAllowMethods",
+    "AccessControlAllowOrigin",
+    "AccessControlExposeHeaders",
+    "AccessControlMaxAge",
+    "AccessControlRequestHeaders",
+    "AccessControlRequestMethod",
+]
+
+
+@dataclass(frozen=True)
+class _CorsList(Header):
+    """Base for CORS headers that are a comma-separated list of tokens (methods or
+    field-names). Subclasses set ``name``/``rule`` and ``item_type`` (the self-validating
+    ParsedStr type of each list item)."""
+
+    item_type: ClassVar[type[ParsedStr]]
+
+    # Subclasses narrow this to their item_type so the field-type check is strict.
+    items: tuple[ParsedStr, ...]
+
+    def __init__(self, *items: ParsedStr) -> None:
+        object.__setattr__(self, "items", tuple(items))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        node = cls._node(value)
+        it = cls.item_type
+        return cls(
+            *(
+                it(c.value, parse=False)
+                for c in node.children
+                if c.name == it.parser.name
+            )
+        )
+
+    @property
+    def value(self) -> str:
+        return ", ".join(self.items)
+
+
+class AccessControlAllowMethods(_CorsList):
+    """Access-Control-Allow-Methods header."""
+
+    name: ClassVar[str] = "access-control-allow-methods"
+    rule: ClassVar[Rule] = cors.Rule("Access-Control-Allow-Methods")
+    item_type = CorsMethod
+    items: tuple[CorsMethod, ...]
+
+
+class AccessControlAllowHeaders(_CorsList):
+    """Access-Control-Allow-Headers header."""
+
+    name: ClassVar[str] = "access-control-allow-headers"
+    rule: ClassVar[Rule] = cors.Rule("Access-Control-Allow-Headers")
+    item_type = CorsFieldName
+    items: tuple[CorsFieldName, ...]
+
+
+class AccessControlExposeHeaders(_CorsList):
+    """Access-Control-Expose-Headers header."""
+
+    name: ClassVar[str] = "access-control-expose-headers"
+    rule: ClassVar[Rule] = cors.Rule("Access-Control-Expose-Headers")
+    item_type = CorsFieldName
+    items: tuple[CorsFieldName, ...]
+
+
+class AccessControlRequestHeaders(_CorsList):
+    """Access-Control-Request-Headers header."""
+
+    name: ClassVar[str] = "access-control-request-headers"
+    rule: ClassVar[Rule] = cors.Rule("Access-Control-Request-Headers")
+    item_type = CorsFieldName
+    items: tuple[CorsFieldName, ...]
+
+
+@dataclass(frozen=True)
+class AccessControlAllowOrigin(Header):
+    """Access-Control-Allow-Origin header (an origin, ``null``, or ``*``)."""
+
+    name: ClassVar[str] = "access-control-allow-origin"
+    rule: ClassVar[Rule] = cors.Rule("Access-Control-Allow-Origin")
+
+    origin: AllowedOrigin
+
+    def __init__(self, origin: str) -> None:
+        object.__setattr__(self, "origin", AllowedOrigin(origin))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(value)
+
+    @property
+    def value(self) -> str:
+        return self.origin
+
+
+@dataclass(frozen=True)
+class AccessControlRequestMethod(Header):
+    """Access-Control-Request-Method header (a single method)."""
+
+    name: ClassVar[str] = "access-control-request-method"
+    rule: ClassVar[Rule] = cors.Rule("Access-Control-Request-Method")
+
+    method: RequestedMethod
+
+    def __init__(self, method: str) -> None:
+        object.__setattr__(self, "method", RequestedMethod(method))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(value)
+
+    @property
+    def value(self) -> str:
+        return self.method
+
+
+@dataclass(frozen=True)
+class AccessControlMaxAge(Header):
+    """Access-Control-Max-Age header (delta-seconds)."""
+
+    name: ClassVar[str] = "access-control-max-age"
+    rule: ClassVar[Rule] = cors.Rule("Access-Control-Max-Age")
+
+    max_age: NonNegativeInt
+
+    def __init__(self, max_age: int) -> None:
+        object.__setattr__(self, "max_age", NonNegativeInt(max_age))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(NonNegativeInt(cls._node(value).value))
+
+    @property
+    def value(self) -> str:
+        return str(self.max_age)
+
+
+@dataclass(frozen=True)
+class AccessControlAllowCredentials(Header):
+    """Access-Control-Allow-Credentials header (always the literal ``true``)."""
+
+    name: ClassVar[str] = "access-control-allow-credentials"
+    rule: ClassVar[Rule] = cors.Rule("Access-Control-Allow-Credentials")
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        cls._node(value)  # validates the value is "true"
+        return cls()
+
+    @property
+    def value(self) -> str:
+        return "true"

http_fields/age.py

@@ -0,0 +1,34 @@
+"""Age header class."""
+
+from dataclasses import dataclass
+from typing import 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 AgeVisitor
+
+
+@dataclass(frozen=True)
+class Age(Header):
+    """Age header, as defined by RFC 9111."""
+
+    name: ClassVar[str] = "age"
+    rule: ClassVar[Rule] = rfc9111.Rule("Age")
+    visitor: ClassVar[AgeVisitor] = AgeVisitor()
+
+    seconds: NonNegativeInt
+
+    def __init__(self, seconds: int) -> None:
+        object.__setattr__(self, "seconds", NonNegativeInt(seconds))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(cls.visitor.visit(cls._node(value)))
+
+    @property
+    def value(self) -> str:
+        return str(self.seconds)

http_fields/allow.py

@@ -0,0 +1,46 @@
+"""Allow 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
+from http_fields.visitors.rfc9110 import AllowVisitor
+
+
+class Method(ParsedStr):
+    """An HTTP method (a token). Methods are case-sensitive (RFC 9110 section 9.1),
+    unlike the caseless :class:`Token`."""
+
+    parser = rfc9110.Rule("token")
+
+
+@dataclass(frozen=True)
+class Allow(Header):
+    """Allow header, as defined by RFC 9110.
+
+    Allow: GET, POST, OPTIONS
+    """
+
+    name: ClassVar[str] = "Allow"
+    rule: ClassVar[Rule] = rfc9110.Rule("Allow")
+    visitor: ClassVar[AllowVisitor] = AllowVisitor()
+
+    methods: tuple[Method, ...]
+
+    def __init__(self, *methods: Method) -> None:
+        object.__setattr__(self, "methods", tuple(methods))
+
+    @classmethod
+    def parse(cls, value: str) -> Self:
+        return cls(
+            *(Method(m, parse=False) for m in cls.visitor.visit(cls._node(value)))
+        )
+
+    @property
+    def value(self) -> str:
+        return ",".join(self.methods)