http-fields 0.1.1__py3-none-any.whl

http_fields/visitors/rfc7838.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc7838
+
+from http_fields.parsedobjs import ParsedStr
+from http_fields.visitors.rfc9110.parameters import (
+    Param,
+    ParamsInput,
+    as_params,
+    param_from_node,
+)
+
+__all__ = ["AltAuthority", "AltSvcVisitor", "AltValue", "ProtocolId"]
+
+
+class ProtocolId(ParsedStr):
+    """An RFC 7838 protocol-id (a percent-encoded ALPN protocol name). Self-validating."""
+
+    parser = rfc7838.Rule("protocol-id")
+
+
+class AltAuthority(ParsedStr):
+    """An RFC 7838 alt-authority: a quoted ``host:port`` (the enclosing quotes are part of
+    the value). Self-validating."""
+
+    parser = rfc7838.Rule("alt-authority")
+
+
+@dataclass(frozen=True)
+class AltValue:
+    """One RFC 7838 alt-value: a protocol-id, an alt-authority, and parameters."""
+
+    protocol_id: ProtocolId
+    authority: AltAuthority
+    params: tuple[Param, ...] = ()
+
+    def __init__(
+        self,
+        protocol_id: str,
+        authority: str,
+        params: ParamsInput = (),
+    ) -> None:
+        # Each part self-validates; an existing leaf/Param passes through unchanged.
+        object.__setattr__(self, "protocol_id", ProtocolId(protocol_id))
+        object.__setattr__(self, "authority", AltAuthority(authority))
+        object.__setattr__(self, "params", as_params(params))
+
+    def __str__(self) -> str:
+        out = f"{self.protocol_id}={self.authority}"
+        for p in self.params:
+            out += f"; {p}"
+        return out
+
+
+class AltSvcVisitor(NodeVisitor):
+    @staticmethod
+    def visit_alternative(node: Node) -> tuple[str, str]:
+        # protocol-id "=" alt-authority
+        return (node.children[0].value, node.children[-1].value)
+
+    def visit_alt_value(self, node: Node) -> AltValue:
+        protocol_id = authority = ""
+        params: list[Param] = []
+        for child in node.children:
+            if child.name == "alternative":
+                protocol_id, authority = self.visit_alternative(child)
+            elif child.name == "parameter":
+                params.append(param_from_node(child))
+        return AltValue(
+            ProtocolId(protocol_id, parse=False),
+            AltAuthority(authority, parse=False),
+            params,
+        )
+
+    def visit_alt_svc(self, node: Node) -> list[AltValue]:
+        return [self.visit_alt_value(c) for c in node.children if c.name == "alt-value"]

http_fields/visitors/rfc8288.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc8288
+
+from http_fields.parsedobjs import ParsedStr
+from http_fields.visitors.rfc9110.parameters import (
+    Param,
+    ParamsInput,
+    as_params,
+    param_from_node,
+)
+
+__all__ = ["LinkValue", "LinkVisitor", "URIReference"]
+
+
+class URIReference(ParsedStr):
+    """An RFC 3986 URI-Reference, as used by RFC 8288's link target. Self-validating."""
+
+    parser = rfc8288.Rule("URI-Reference")
+
+
+@dataclass(frozen=True)
+class LinkValue:
+    """One RFC 8288 link-value: a target URI reference plus link-params."""
+
+    target: URIReference
+    params: tuple[Param, ...] = ()
+
+    def __init__(self, target: str, params: ParamsInput = ()) -> None:
+        # target and each Param self-validate; an existing leaf/Param passes through.
+        object.__setattr__(self, "target", URIReference(target))
+        object.__setattr__(self, "params", as_params(params))
+
+    def __str__(self) -> str:
+        out = f"<{self.target}>"
+        for p in self.params:
+            out += f"; {p}"
+        return out
+
+
+class LinkVisitor(NodeVisitor):
+    def visit_link_value(self, node: Node) -> LinkValue:
+        target = ""
+        params: list[Param] = []
+        for child in node.children:
+            if child.name == "URI-Reference":
+                target = child.value
+            elif child.name == "link-param":
+                params.append(param_from_node(child))
+        return LinkValue(URIReference(target, parse=False), params)
+
+    def visit_link(self, node: Node) -> list[LinkValue]:
+        return [
+            self.visit_link_value(c) for c in node.children if c.name == "link-value"
+        ]

http_fields/visitors/rfc9110/__init__.py

@@ -0,0 +1,117 @@
+"""Visitors and dataclasses from RFC9110."""
+
+# There are many classes and functions, so manageabilty has led to
+# many modules,
+
+from http_fields.visitors.rfc9110._base import imf_fixdate
+from http_fields.visitors.rfc9110.accept import AcceptType, AcceptVisitor
+from http_fields.visitors.rfc9110.acceptcharset import AcceptCharsetVisitor
+from http_fields.visitors.rfc9110.acceptencoding import (
+    AcceptEncodingVisitor,
+    WeightedCoding,
+)
+from http_fields.visitors.rfc9110.acceptlanguage import (
+    AcceptLanguageVisitor,
+    WeightedLanguageRange,
+)
+from http_fields.visitors.rfc9110.acceptranges import AcceptRangesVisitor
+from http_fields.visitors.rfc9110.allow import AllowVisitor
+from http_fields.visitors.rfc9110.authenticationinfo import (
+    AuthenticationInfoVisitor,
+    ProxyAuthenticationInfoVisitor,
+)
+from http_fields.visitors.rfc9110.authorization import (
+    AuthorizationVisitor,
+    AuthParamCredentials,
+    ProxyAuthorizationVisitor,
+    TokenCredentials,
+)
+from http_fields.visitors.rfc9110.authparam import AuthParam
+from http_fields.visitors.rfc9110.challenge import AuthParamChallenge, TokenChallenge
+from http_fields.visitors.rfc9110.comment import Comment
+from http_fields.visitors.rfc9110.connection import ConnectionVisitor
+from http_fields.visitors.rfc9110.contentlength import ContentLengthVisitor
+from http_fields.visitors.rfc9110.contentrange import ContentRangeVisitor
+from http_fields.visitors.rfc9110.contenttype import ContentTypeVisitor, MediaType
+from http_fields.visitors.rfc9110.date import DateVisitor
+from http_fields.visitors.rfc9110.entitytag import EntityTag
+from http_fields.visitors.rfc9110.etag import ETagVisitor
+from http_fields.visitors.rfc9110.field import FieldName, FieldValue
+from http_fields.visitors.rfc9110.host import Hostname, HostVisitor
+from http_fields.visitors.rfc9110.httpdate import HttpDateVisitor
+from http_fields.visitors.rfc9110.ifmatch import IfMatchVisitor
+from http_fields.visitors.rfc9110.ifmodifiedsince import IfModifiedSinceVisitor
+from http_fields.visitors.rfc9110.ifnonematch import IfNoneMatchVisitor
+from http_fields.visitors.rfc9110.ifunmodifiedsince import IfUnmodifiedSinceVisitor
+from http_fields.visitors.rfc9110.lastmodified import LastModifiedVisitor
+from http_fields.visitors.rfc9110.location import LocationVisitor
+from http_fields.visitors.rfc9110.parameters import Parameter
+from http_fields.visitors.rfc9110.product import Product
+from http_fields.visitors.rfc9110.quotedstring import QuotedString, QuotedStringVisitor
+from http_fields.visitors.rfc9110.rangeunit import RangeUnit
+from http_fields.visitors.rfc9110.retryafter import RetryAfterVisitor
+from http_fields.visitors.rfc9110.server import ServerVisitor
+from http_fields.visitors.rfc9110.token import Token, TokenVisitor
+from http_fields.visitors.rfc9110.useragent import UserAgentVisitor
+from http_fields.visitors.rfc9110.vary import VaryVisitor
+from http_fields.visitors.rfc9110.weight import Weight
+from http_fields.visitors.rfc9110.wwwauthenticate import (
+    ProxyAuthenticateVisitor,
+    WWWAuthenticateVisitor,
+)
+
+__all__ = [
+    "imf_fixdate",
+    "AcceptCharsetVisitor",
+    "AcceptEncodingVisitor",
+    "AcceptLanguageVisitor",
+    "AcceptRangesVisitor",
+    "AcceptType",
+    "AcceptVisitor",
+    "AllowVisitor",
+    "AuthenticationInfoVisitor",
+    "AuthorizationVisitor",
+    "AuthParam",
+    "AuthParamCredentials",
+    "AuthParamChallenge",
+    "Comment",
+    "ConnectionVisitor",
+    "ContentLengthVisitor",
+    "ContentRangeVisitor",
+    "ContentTypeVisitor",
+    "DateVisitor",
+    "EntityTag",
+    "ETagVisitor",
+    "FieldName",
+    "FieldValue",
+    "HostVisitor",
+    "Hostname",
+    "HttpDateVisitor",
+    "IfMatchVisitor",
+    "IfModifiedSinceVisitor",
+    "IfNoneMatchVisitor",
+    "IfUnmodifiedSinceVisitor",
+    "LastModifiedVisitor",
+    "LocationVisitor",
+    "MediaType",
+    "Parameter",
+    "Product",
+    "ProxyAuthenticateVisitor",
+    "ProxyAuthenticationInfoVisitor",
+    "ProxyAuthorizationVisitor",
+    "QuotedString",
+    "QuotedStringVisitor",
+    "RangeUnit",
+    "RetryAfterVisitor",
+    "ServerVisitor",
+    "Token",
+    "TokenChallenge",
+    "TokenCredentials",
+    "TokenVisitor",
+    "UserAgentVisitor",
+    "VaryVisitor",
+    "Weight",
+    "WeightedCoding",
+    "WeightedLanguageRange",
+    "WWWAuthenticateVisitor",
+]

http_fields/visitors/rfc9110/_base.py

@@ -0,0 +1,71 @@
+"""A few functions used here and there in this package."""
+
+from collections.abc import Iterator
+from datetime import datetime, timezone
+from typing import TypeVar, cast
+
+S = TypeVar("S")
+T = TypeVar("T")
+
+
+def transform(
+    items: Iterator[S | T], type_s: type[S], type_t: type[T]
+) -> Iterator[tuple[S, T | None]]:
+    """Pair each ``type_s`` item with the optional ``type_t`` item that follows it.
+
+    Iterative (not recursive) so an arbitrarily long stream — e.g. a very long
+    ``Accept`` header — cannot exhaust the call stack.
+    """
+    pending: S | None = None
+    for item in items:
+        if isinstance(item, type_t):
+            if pending is None:  # pragma: no cover - a type_t with no preceding type_s
+                raise AssertionError()
+            yield (pending, cast(T, item))
+            pending = None
+        elif isinstance(item, type_s):
+            if pending is not None:
+                yield (pending, None)
+            pending = item
+        else:  # pragma: no cover
+            raise AssertionError()
+    if pending is not None:
+        yield (pending, None)
+
+
+def imf_fixdate(pydate: datetime):
+    """
+    Converts a datetime object to a fixdate string.
+    """
+
+    # HTTP dates are expressed in GMT/UTC. Convert tz-aware datetimes to UTC so the
+    # printed wall-clock fields match the "GMT" label; naive datetimes are assumed
+    # to already be UTC.
+    if pydate.tzinfo is not None:
+        pydate = pydate.astimezone(timezone.utc)
+
+    day_name = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+    month_name = [
+        "Jan",
+        "Feb",
+        "Mar",
+        "Apr",
+        "May",
+        "Jun",
+        "Jul",
+        "Aug",
+        "Sep",
+        "Oct",
+        "Nov",
+        "Dec",
+    ]
+    fixdate_fmt = "%s, %02d %s %04d %02d:%02d:%02d GMT"
+    return fixdate_fmt % (
+        day_name[pydate.weekday()],
+        pydate.day,
+        month_name[pydate.month - 1],
+        pydate.year,
+        pydate.hour,
+        pydate.minute,
+        pydate.second,
+    )

http_fields/visitors/rfc9110/accept.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110._base as base
+import http_fields.visitors.rfc9110.parameters as parameters
+import http_fields.visitors.rfc9110.token as token
+import http_fields.visitors.rfc9110.type as type_grammar
+import http_fields.visitors.rfc9110.weight as weight
+
+# NB: do not alias the "type" grammar module as `type` -- it would shadow the
+# builtin, which a frozen dataclass's generated __setattr__ (`type(self)`) needs.
+Parameter = parameters.Parameter
+ParametersVisitor = parameters.ParametersVisitor
+SubtypeVisitor = type_grammar.SubtypeVisitor
+Token = token.Token
+TypeVisitor = type_grammar.TypeVisitor
+Weight = weight.Weight
+WeightVisitor = weight.WeightVisitor
+as_qvalue = weight.as_qvalue
+
+
+@dataclass(frozen=True)
+class MediaRange:
+    type: Token
+    subtype: Token
+    params: tuple[Parameter, ...]
+
+    def __init__(self, type: str, subtype: str, params: list[Parameter] | None = None):
+        object.__setattr__(self, "type", Token(type))
+        object.__setattr__(self, "subtype", Token(subtype))
+        object.__setattr__(self, "params", tuple(params) if params else ())
+
+    def __str__(self) -> str:
+        return f"{self.type}/{self.subtype}" + (
+            (";" + ";".join(str(p) for p in self.params)) if self.params else ""
+        )
+
+
+class MediaRangeVisitor(NodeVisitor):
+    visit_type = TypeVisitor()
+    visit_subtype = SubtypeVisitor()
+    visit_parameters = ParametersVisitor()
+
+    def visit_media_range(self, node: Node) -> MediaRange:
+        items = filter(None, map(self.visit, node.children))
+        item = next(items)
+        if item == "*/*":
+            type, subtype = tuple([Token(x) for x in item.split("/")])
+            # and anything else must be a param.
+        else:
+            type = item
+            item = next(items)
+            subtype = Token("*") if item == "/*" else item
+        params: list[Parameter] = next(items, [])
+        return MediaRange(type, subtype, params)
+
+    @staticmethod
+    def visit_literal(node: Node):
+        return node.value if node.value in ["*/*", "/*"] else None
+
+
+@dataclass(frozen=True)
+class AcceptType:
+    type: Token
+    subtype: Token
+    params: tuple[Parameter, ...] = ()
+    weight: Weight | None = None
+
+    def __init__(
+        self,
+        type: str,
+        subtype: str,
+        *,
+        params: list[tuple[str, str] | Parameter] | None = None,
+        weight: float | Weight | None = None,
+    ) -> None:
+        _params = (
+            [Parameter(*p) if isinstance(p, tuple) else p for p in params]
+            if params
+            else []
+        )
+        resolved_weight: Weight | None
+        if isinstance(weight, (float, Weight)):
+            resolved_weight = (
+                Weight(qvalue=weight) if isinstance(weight, float) else weight
+            )
+            resolved_params = tuple(_params)
+        elif _params:
+            # sometimes, weight was captured by parser as a parameter because abnf
+            # backtracking is somewhat arbitrary. A trailing "q" parameter is a weight
+            # only if its value is an unquoted, in-range qvalue (0..1); a quoted or
+            # out-of-range "q" is an ordinary parameter.
+            w = _params[-1]
+            qvalue = as_qvalue(w.value) if w.name == "q" else None
+            if qvalue is not None:
+                resolved_weight = Weight(qvalue=qvalue)
+                resolved_params = tuple(_params[:-1])
+            else:
+                resolved_weight = None
+                resolved_params = tuple(_params)
+        else:
+            resolved_weight = None
+            resolved_params = tuple(_params)
+        object.__setattr__(self, "type", Token(type))
+        object.__setattr__(self, "subtype", Token(subtype))
+        object.__setattr__(self, "params", resolved_params)
+        object.__setattr__(self, "weight", resolved_weight)
+
+    def __str__(self):
+        return (
+            f"{self.type}/{self.subtype}"
+            + ((";" + ";".join(str(p) for p in self.params)) if self.params else "")
+            + (";" + str(self.weight) if self.weight else "")
+        )
+
+
+class AcceptVisitor(NodeVisitor):
+    visit_media_range = MediaRangeVisitor()
+    visit_weight = WeightVisitor()
+
+    def visit_accept(self, node: Node):
+        items = filter(None, map(self.visit, node.children))
+        accept_types = [
+            AcceptType(
+                media_range.type,
+                media_range.subtype,
+                params=media_range.params,
+                weight=weight,
+            )
+            for media_range, weight in base.transform(items, MediaRange, Weight)
+        ]
+        return accept_types

http_fields/visitors/rfc9110/acceptcharset.py

@@ -0,0 +1,26 @@
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110._base as base
+import http_fields.visitors.rfc9110.token as token
+import http_fields.visitors.rfc9110.weight as weight
+
+Token = token.Token
+TokenVisitor = token.TokenVisitor
+Weight = weight.Weight
+WeightVisitor = weight.WeightVisitor
+
+
+class AcceptCharsetVisitor(NodeVisitor):
+    visit_token = TokenVisitor()
+    visit_weight = WeightVisitor()
+
+    def visit_accept_charset(self, node: Node):
+        items = filter(None, map(self.visit, node.children))
+        charsets = list(base.transform(items, Token, Weight))
+        return charsets
+
+    # the accept-charset value "*" is matched by the RFC 9110 rule 'token', so
+    # the parser will usually recognize it as a token in the alternation 'token / "*".
+    # we have this method just in case, but skip testing it.
+    def visit_literal(self, node: Node):  # pragma: no cover
+        return Token("*") if node.value == "*" else None

http_fields/visitors/rfc9110/acceptencoding.py

@@ -0,0 +1,76 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from abnf import Node
+from abnf import NodeVisitor as _NodeVisitor
+from abnf.grammars import rfc9110
+
+import http_fields.visitors.rfc9110._base as base
+import http_fields.visitors.rfc9110.token as token
+import http_fields.visitors.rfc9110.weight as weight
+from http_fields.parsedobjs import ParsedStr
+
+Token = token.Token
+TokenVisitor = token.TokenVisitor
+Weight = weight.Weight
+WeightVisitor = weight.WeightVisitor
+
+
+class NodeVisitor(_NodeVisitor):
+    def visit_children(self, node: Node, *, f: Callable[[Any], bool] | None = None):
+        for child in node.children:
+            result = self.visit(child)
+            if (f and f(result)) or result is not None:
+                yield result
+
+
+class Coding(ParsedStr):
+    """Represents an RFC 9110 codings thing."""
+
+    parser = rfc9110.Rule("codings")
+
+
+@dataclass(frozen=True)
+class WeightedCoding:
+    coding: Coding
+    weight: Weight | None
+
+    def __init__(self, coding: str, weight: float | (Weight | None) = None):
+        object.__setattr__(self, "coding", Coding(coding))
+        if isinstance(weight, Weight):
+            object.__setattr__(self, "weight", weight)
+        elif isinstance(weight, (int, float)) and not isinstance(weight, bool):
+            # Accept any real number, including 0 ("not acceptable"); a bare
+            # None means no weight was specified.
+            object.__setattr__(self, "weight", Weight(float(weight)))
+        else:
+            object.__setattr__(self, "weight", None)
+
+    def __str__(self):
+        return str(self.coding) + (f";{str(self.weight)}" if self.weight else "")
+
+
+class AcceptEncodingVisitor(NodeVisitor):
+    visit_weight = WeightVisitor()
+    visit_token = TokenVisitor()
+
+    @staticmethod
+    def visit_literal(node: Node):
+        return node.value if node.value in {"identity", "*"} else None
+
+    def visit_content_coding(self, node: Node):
+        item: Token = next(filter(None, map(self.visit, node.children)))
+        return Coding(item)
+
+    def visit_codings(self, node: Node):
+        item: Coding = next(filter(None, map(self.visit, node.children)))
+        return item
+
+    def visit_accept_encoding(self, node: Node):
+        # items = filter(None, map(self.visit, node.children))
+        items = self.visit_children(node)
+        return [
+            WeightedCoding(enc, weight)
+            for enc, weight in base.transform(items, Coding, Weight)
+        ]

http_fields/visitors/rfc9110/acceptlanguage.py

@@ -0,0 +1,55 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+import http_fields.visitors.rfc9110._base as base
+import http_fields.visitors.rfc9110.token as token
+import http_fields.visitors.rfc9110.weight as weight
+from http_fields.parsedobjs import ParsedStr
+
+__all__ = ["WeightedLanguageRange", "AcceptLanguageVisitor"]
+
+Token = token.Token
+Weight = weight.Weight
+WeightVisitor = weight.WeightVisitor
+
+
+class LanguageRange(ParsedStr):
+    """Represents an RFC 9110 language-range."""
+
+    parser = rfc9110.Rule("language-range")
+
+
+@dataclass(frozen=True)
+class WeightedLanguageRange:
+    language_range: LanguageRange
+    weight: Weight | None
+
+    def __init__(self, language_range: str, weight: float | Weight | None = None):
+        object.__setattr__(self, "language_range", LanguageRange(language_range))
+        if isinstance(weight, Weight):
+            object.__setattr__(self, "weight", weight)
+        elif isinstance(weight, (int, float)) and not isinstance(weight, bool):
+            # a numeric 0 is a valid weight ("not acceptable"); only None means unset.
+            object.__setattr__(self, "weight", Weight(float(weight)))
+        else:
+            object.__setattr__(self, "weight", None)
+
+    def __str__(self) -> str:
+        return str(self.language_range) + (f";{self.weight}" if self.weight else "")
+
+
+class AcceptLanguageVisitor(NodeVisitor):
+    visit_weight = WeightVisitor()
+
+    @staticmethod
+    def visit_language_range(node: Node):
+        return LanguageRange(node.value)
+
+    def visit_accept_language(self, node: Node):
+        items = filter(None, map(self.visit, node.children))
+        return [
+            WeightedLanguageRange(enc, weight)
+            for enc, weight in base.transform(items, LanguageRange, weight.Weight)
+        ]

http_fields/visitors/rfc9110/acceptranges.py

@@ -0,0 +1,13 @@
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.rangeunit as rangeunit
+
+
+class AcceptRangesVisitor(NodeVisitor):
+    visit_range_unit = rangeunit.RangeUnitVisitor()
+
+    def visit_acceptable_ranges(self, node: Node) -> list[rangeunit.RangeUnit]:
+        return list(filter(None, map(self.visit, node.children)))
+
+    def visit_accept_ranges(self, node: Node) -> list[rangeunit.RangeUnit]:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/allow.py

@@ -0,0 +1,13 @@
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.token as token
+
+
+class AllowVisitor(NodeVisitor):
+    visit_token = token.TokenVisitor()
+
+    def visit_allow(self, node: Node) -> list[token.Token]:
+        return list(filter(None, map(self.visit, node.children)))
+
+    def visit_method(self, node: Node) -> token.Token:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/authenticationinfo.py

@@ -0,0 +1,19 @@
+from abnf import Node, NodeVisitor
+
+from http_fields.visitors.rfc9110.authparam import AuthParam, AuthParamVisitor
+
+
+class AuthenticationInfoVisitor(NodeVisitor):
+    visit_auth_param = AuthParamVisitor()
+
+    def visit_authentication_info(self, node: Node) -> list[AuthParam]:
+        items = filter(None, map(self.visit, node.children))
+        return list(items)
+
+
+class ProxyAuthenticationInfoVisitor(NodeVisitor):
+    visit_auth_param = AuthParamVisitor()
+
+    def visit_proxy_authentication_info(self, node: Node) -> list[AuthParam]:
+        items = filter(None, map(self.visit, node.children))
+        return list(items)