http-fields 0.1.1__py3-none-any.whl

http_fields/visitors/rfc9110/authorization.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.authparam as authparam
+import http_fields.visitors.rfc9110.token68 as token68
+from http_fields.visitors.rfc9110.authscheme import AuthScheme
+
+
+@dataclass(frozen=True)
+class AuthParamCredentials:
+    scheme: AuthScheme
+    auth_params: tuple[authparam.AuthParam, ...]
+
+    def __init__(self, scheme: str, auth_params: list[authparam.AuthParam]):
+        object.__setattr__(self, "scheme", AuthScheme(scheme))
+        object.__setattr__(self, "auth_params", tuple(auth_params))
+
+    def __str__(self):
+        params = ",".join([str(param) for param in self.auth_params])
+        return f"{self.scheme}{' ' + params if params else ''}"
+
+
+@dataclass(frozen=True)
+class TokenCredentials:
+    scheme: AuthScheme
+    token: token68.Token68 | None
+
+    def __init__(self, scheme: str, token: str | None):
+        object.__setattr__(self, "scheme", AuthScheme(scheme))
+        object.__setattr__(self, "token", token68.Token68(token) if token else None)
+
+    def __str__(self):
+        return f"{self.scheme}{' ' + self.token if self.token else ''}"
+
+
+class CredentialsVisitor(NodeVisitor):
+    visit_token68 = token68.Token68Visitor()
+    visit_auth_param = authparam.AuthParamVisitor()
+
+    def visit_auth_scheme(self, node: Node):
+        return AuthScheme(node.value)
+
+    def visit_credentials(self, node: Node):
+        items = filter(None, map(self.visit, node.children))
+        auth_scheme = next(items)
+        assert isinstance(auth_scheme, AuthScheme)
+        try:
+            next_item = next(items)
+        except StopIteration:
+            return TokenCredentials(scheme=auth_scheme, token=None)
+        else:
+            if isinstance(next_item, token68.Token68):
+                return TokenCredentials(scheme=auth_scheme, token=next_item)
+            elif isinstance(next_item, authparam.AuthParam):
+                auth_params = [next_item] + list(items)
+                return AuthParamCredentials(scheme=auth_scheme, auth_params=auth_params)
+            else:  # pragma: no cover
+                raise AssertionError()
+
+
+class AuthorizationVisitor(NodeVisitor):
+    """NodeVisitor subclass for authorization header value."""
+
+    visit_credentials = CredentialsVisitor()
+
+    def visit_authorization(self, node: Node):
+        return next(filter(None, map(self.visit, node.children)))
+
+
+class ProxyAuthorizationVisitor(NodeVisitor):
+    """NodeVisitor subclass for the Proxy-Authorization header value."""
+
+    visit_credentials = CredentialsVisitor()
+
+    def visit_proxy_authorization(self, node: Node):
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/authparam.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.quotedstring as quotedstring
+import http_fields.visitors.rfc9110.token as token
+
+
+@dataclass(frozen=True)
+class AuthParam:
+    name: token.Token
+    value: token.Token | quotedstring.QuotedString
+
+    def __init__(self, name: str, value: str):
+        object.__setattr__(self, "name", token.Token(name))
+
+        if name.lower() == "realm":
+            # realm value should be quoted.  See https://tools.ietf.org/html/rfc7235#section-2.2.
+            object.__setattr__(self, "value", quotedstring.QuotedString(value))
+        else:
+            try:
+                object.__setattr__(self, "value", token.Token(value))
+            except ValueError:
+                object.__setattr__(self, "value", quotedstring.QuotedString(value))
+
+    def __str__(self):
+        return f"{self.name}={self.value}"
+
+
+class AuthParamVisitor(NodeVisitor):
+    visit_token = token.TokenVisitor()
+    visit_quoted_string = quotedstring.QuotedStringVisitor()
+
+    def visit_auth_param(self, node: Node):
+        name: token.Token
+        value: token.Token | quotedstring.QuotedString
+        name, value = filter(None, map(self.visit, node.children))
+        assert isinstance(name, token.Token)
+        assert isinstance(value, token.Token | quotedstring.QuotedString)
+        return AuthParam(name=name, value=value)

http_fields/visitors/rfc9110/authscheme.py

@@ -0,0 +1,17 @@
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import CaselessMixin, ParsedStr
+
+
+class AuthScheme(CaselessMixin, ParsedStr):
+    """Represents an RFC 9110 auth-scheme. Schemes are case-insensitive
+    (RFC 9110 section 11.1), so two schemes differing only in case compare equal;
+    the original casing is preserved on serialization."""
+
+    parser = rfc9110.Rule("auth-scheme")
+
+
+class AuthSchemeVisitor(NodeVisitor):
+    def visit_auth_scheme(self, node: Node):
+        return AuthScheme(node.value)

http_fields/visitors/rfc9110/challenge.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.authparam as authparam
+import http_fields.visitors.rfc9110.authscheme as authscheme
+import http_fields.visitors.rfc9110.token68 as token68
+
+
+@dataclass(frozen=True)
+class TokenChallenge:
+    scheme: authscheme.AuthScheme
+    token: token68.Token68 | None
+
+    def __init__(self, scheme: str, token: str | None):
+        object.__setattr__(self, "scheme", authscheme.AuthScheme(scheme))
+        object.__setattr__(self, "token", token68.Token68(token) if token else None)
+
+    def __str__(self):
+        return f"{self.scheme}{' ' + self.token if self.token else ''}"
+
+
+@dataclass(frozen=True)
+class AuthParamChallenge:
+    scheme: authscheme.AuthScheme
+    auth_params: tuple[authparam.AuthParam, ...]
+
+    def __init__(self, scheme: str, auth_params: list[authparam.AuthParam]):
+        object.__setattr__(self, "scheme", authscheme.AuthScheme(scheme))
+        object.__setattr__(self, "auth_params", tuple(auth_params))
+
+    def __str__(self):
+        params = ",".join([str(param) for param in self.auth_params])
+        return f"{self.scheme}{' ' + params if params else ''}"
+
+
+class ChallengeVisitor(NodeVisitor):
+    visit_token68 = token68.Token68Visitor()
+    visit_auth_param = authparam.AuthParamVisitor()
+    visit_auth_scheme = authscheme.AuthSchemeVisitor()
+
+    def visit_challenge(self, node: Node):
+        items = filter(None, map(self.visit, node.children))
+        auth_scheme = next(items)
+        assert isinstance(auth_scheme, authscheme.AuthScheme)
+        try:
+            next_item = next(items)
+        except StopIteration:
+            return TokenChallenge(scheme=auth_scheme, token=None)
+        else:
+            if isinstance(next_item, token68.Token68):
+                return TokenChallenge(scheme=auth_scheme, token=next_item)
+            elif isinstance(next_item, authparam.AuthParam):
+                auth_params = [next_item] + list(items)
+                return AuthParamChallenge(scheme=auth_scheme, auth_params=auth_params)
+            else:  # pragma: no cover
+                raise AssertionError()

http_fields/visitors/rfc9110/comment.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor, ParseError
+from abnf.grammars import rfc9110
+
+import http_fields.visitors.rfc9110.quotedstring as quotedstring
+
+
+def _escape_ctext(text: str) -> str:
+    # ctext excludes "(", ")" and "\"; these appear in parsed text only because a
+    # quoted-pair was unescaped, so re-escape them to keep the comment parseable.
+    return "".join("\\" + c if c in "()\\" else c for c in text)
+
+
+@dataclass(frozen=True)
+class Comment:
+    """An RFC 9110 comment: a parenthesised sequence of text runs and nested comments.
+
+    Frozen so it stays immutable (and stably hashable) while embedded in a frozen
+    User-Agent/Server/Via header. ``__eq__``/``__hash__``/``__repr__`` are generated;
+    ``__str__`` re-escapes text runs so the serialized comment round-trips.
+
+    Each string argument is parsed as comment *content* (``*( ctext / quoted-pair /
+    comment )``): embedded ``(...)`` become nested Comment objects, ``\\)`` is a
+    quoted-pair, and invalid content (CR/LF/NUL or an unescaped/unbalanced parenthesis)
+    raises ``ValueError``. So ``Comment(s)`` accepts exactly what the parser produces.
+    """
+
+    items: tuple[str | Comment, ...] = ()
+
+    def __init__(self, *items: str | Comment) -> None:
+        parsed: list[str | Comment] = []
+        for item in items:
+            if isinstance(item, Comment):
+                parsed.append(item)
+            else:
+                parsed.extend(_parse_content(item))
+        object.__setattr__(self, "items", tuple(parsed))
+
+    @classmethod
+    def _from_items(cls, items: tuple[str | Comment, ...]) -> Comment:
+        # Build from already-structured, already-unescaped items (the visitor's
+        # output), bypassing the string-parsing done by __init__.
+        obj = object.__new__(cls)
+        object.__setattr__(obj, "items", items)
+        return obj
+
+    def __str__(self) -> str:
+        return (
+            "("
+            + "".join(
+                str(item) if isinstance(item, Comment) else _escape_ctext(str(item))
+                for item in self.items
+            )
+            + ")"
+        )
+
+
+def _parse_content(content: str) -> tuple[str | Comment, ...]:
+    """Parse a comment-content string into its (text-run / nested-Comment) items."""
+    try:
+        node = rfc9110.Rule("comment").parse_all(f"({content})")
+    except ParseError as exc:
+        raise ValueError(f"Invalid comment content: {content!r}.") from exc
+    return _CONTENT_VISITOR.visit(node).items
+
+
+class CommentVisitor(NodeVisitor):
+    visit_quoted_pair = quotedstring.QuotedPairVisitor()
+
+    @staticmethod
+    def visit_ctext(node: Node):
+        return node.value
+
+    def visit_comment(self, node: Node):
+        items = filter(None, map(self.visit, node.children))
+        comment_items: list[str | Comment] = []
+
+        text: list[str] = []
+        for item in items:
+            if isinstance(item, str):
+                text.append(item)
+            elif isinstance(item, Comment):
+                comment_items.append("".join(text))
+                text = []
+                comment_items.append(item)
+            else:  # pragma: no cover
+                raise AssertionError()
+        if text:
+            comment_items.append("".join(text))
+        # Build directly from the (already-unescaped) items; passing them back
+        # through Comment.__init__ would try to re-parse them as content. This is the
+        # module's own internal factory (same file), not cross-module private access.
+        return Comment._from_items(tuple(comment_items))  # pyright: ignore[reportPrivateUsage]
+
+
+_CONTENT_VISITOR = CommentVisitor()

http_fields/visitors/rfc9110/connection.py

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

http_fields/visitors/rfc9110/contentlanguage.py

@@ -0,0 +1,21 @@
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import CaselessMixin, ParsedStr
+
+__all__ = ["ContentLanguageVisitor", "LanguageTag"]
+
+
+class LanguageTag(CaselessMixin, ParsedStr):
+    """Represents an RFC 9110 language-tag (BCP 47), matched case-insensitively."""
+
+    parser = rfc9110.Rule("language-tag")
+
+
+class ContentLanguageVisitor(NodeVisitor):
+    @staticmethod
+    def visit_language_tag(node: Node) -> str:
+        return LanguageTag(node.value, parse=False)
+
+    def visit_content_language(self, node: Node) -> list[str]:
+        return [x for x in map(self.visit, node.children) if x is not None]

http_fields/visitors/rfc9110/contentlength.py

@@ -0,0 +1,9 @@
+from abnf import Node, NodeVisitor
+
+from http_fields.parsedobjs import NonNegativeInt
+
+
+class ContentLengthVisitor(NodeVisitor):
+    @staticmethod
+    def visit_content_length(node: Node):
+        return NonNegativeInt(node.value)

http_fields/visitors/rfc9110/contentrange.py

@@ -0,0 +1,70 @@
+from dataclasses import dataclass
+from typing import Literal
+
+from abnf import Node, NodeVisitor
+
+from http_fields.parsedobjs import NonNegativeInt
+from http_fields.visitors.rfc9110.rangeunit import RangeUnit, RangeUnitVisitor
+
+
+@dataclass(frozen=True)
+class RangeResp:
+    first_pos: NonNegativeInt
+    last_pos: NonNegativeInt
+    complete_length: NonNegativeInt | None
+
+
+@dataclass(frozen=True)
+class UnsatisfiedRange:
+    complete_length: NonNegativeInt | None
+
+
+class ContentRangeVisitor(NodeVisitor):
+    visit_range_unit = RangeUnitVisitor()
+
+    @staticmethod
+    def visit_literal(node: Node):
+        return "*" if node.value == "*" else None
+
+    @staticmethod
+    def visit_complete_length(node: Node):
+        return NonNegativeInt(node.value)
+
+    def visit_unsatisfied_range(self, node: Node) -> UnsatisfiedRange:
+        item = next(x for x in map(self.visit, node.children) if x is not None)
+        return UnsatisfiedRange(item if isinstance(item, NonNegativeInt) else None)
+
+    @staticmethod
+    def visit_first_pos(node: Node):
+        return NonNegativeInt(node.value)
+
+    @staticmethod
+    def visit_last_pos(node: Node):
+        return NonNegativeInt(node.value)
+
+    def visit_incl_range(self, node: Node):
+        first_pos: NonNegativeInt
+        last_pos: NonNegativeInt
+        first_pos, last_pos = (
+            x for x in map(self.visit, node.children) if x is not None
+        )
+        return (first_pos, last_pos)
+
+    def visit_range_resp(self, node: Node):
+        incl_range: tuple[NonNegativeInt, NonNegativeInt]
+        complete_length: NonNegativeInt | Literal["*"]
+        incl_range, complete_length = (
+            x for x in map(self.visit, node.children) if x is not None
+        )
+        return RangeResp(
+            *incl_range,
+            complete_length=complete_length
+            if isinstance(complete_length, NonNegativeInt)
+            else None,
+        )
+
+    def visit_content_range(self, node: Node):
+        range_unit: RangeUnit
+        range: RangeResp | UnsatisfiedRange
+        range_unit, range = (x for x in map(self.visit, node.children) if x is not None)
+        return range_unit, range

http_fields/visitors/rfc9110/contenttype.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.parameters as parameters
+import http_fields.visitors.rfc9110.token as token
+
+# NB: do not alias the "type" grammar module as `type` -- it would shadow the
+# builtin, which MediaType's generated (frozen) __setattr__ (`type(self)`) needs.
+import http_fields.visitors.rfc9110.type as type_grammar
+
+
+@dataclass(frozen=True)
+class MediaType:
+    type: token.Token
+    subtype: token.Token
+    params: tuple[parameters.Parameter, ...]
+
+    def __init__(
+        self,
+        type: str,
+        subtype: str,
+        params: "list[parameters.Parameter] | tuple[parameters.Parameter, ...] | None" = None,
+    ):
+        object.__setattr__(self, "type", token.Token(type))
+        object.__setattr__(self, "subtype", token.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 MediaTypeVisitor(NodeVisitor):
+    visit_type = type_grammar.TypeVisitor()
+    visit_subtype = type_grammar.SubtypeVisitor()
+    visit_parameters = parameters.ParametersVisitor()
+
+    def visit_media_type(self, node: Node) -> MediaType:
+        items = filter(None, map(self.visit, node.children))
+        type = next(items)
+        subtype = next(items)
+        params: list[parameters.Parameter] = next(items, [])
+        return MediaType(type, subtype, params)
+
+
+class ContentTypeVisitor(NodeVisitor):
+    visit_media_type = MediaTypeVisitor()
+
+    def visit_content_type(self, node: Node):
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/date.py

@@ -0,0 +1,12 @@
+from datetime import datetime
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.httpdate as httpdate
+
+
+class DateVisitor(NodeVisitor):
+    visit_http_date = httpdate.HttpDateVisitor()
+
+    def visit_date(self, node: Node) -> datetime:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/entitytag.py

@@ -0,0 +1,66 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor, ParseError
+from abnf.grammars import rfc9110
+
+
+@dataclass(frozen=True)
+class EntityTag:
+    """An RFC 9110 entity-tag. ``__eq__``/``__hash__`` are exact (weak flag + opaque
+    tag); use :meth:`compare` for the RFC's weak/strong comparison semantics."""
+
+    opaque_tag: str
+    weak: bool = False
+
+    def __init__(self, tag: str, weak: bool = False) -> None:
+        # Double-quote the tag if it is not already, then validate.
+        opaque_tag = (
+            f'"{tag}"' if not tag or (tag[0] != '"' and tag[-1] != '"') else tag
+        )
+        entity_tag = f"W/{opaque_tag}" if weak else opaque_tag
+        try:
+            rfc9110.Rule("entity-tag").parse_all(entity_tag)
+        except ParseError as exc:
+            raise ValueError("Invalid character in value.") from exc
+        object.__setattr__(self, "opaque_tag", opaque_tag)
+        object.__setattr__(self, "weak", weak)
+
+    def __str__(self) -> str:
+        return f"W/{self.opaque_tag}" if self.weak else self.opaque_tag
+
+    def compare(self, __o: object, *, weak: bool) -> bool:
+        if not isinstance(__o, self.__class__):
+            raise TypeError(
+                f"EntityTag is not comparable to an instance of {__o.__class__.__name__}."
+            )
+
+        if weak:
+            return self.opaque_tag == __o.opaque_tag
+        else:
+            return not (self.weak or __o.weak) and self.opaque_tag == __o.opaque_tag
+
+
+class EntityTagVisitor(NodeVisitor):
+    def visit_entity_tag(self, node: Node) -> EntityTag:
+        # Match children by name: an empty opaque-tag ("") and an absent weak
+        # flag are both falsy, so a truthiness filter would lose them and shift
+        # the positional unpacking.
+        weak = False
+        tag = ""
+        for child in node.children:
+            if child.name == "weak":
+                weak = self.visit(child)
+            elif child.name == "opaque-tag":
+                tag = self.visit(child)
+        return EntityTag(tag, weak=weak)
+
+    def visit_opaque_tag(self, node: Node) -> str:
+        return "".join(filter(None, map(self.visit, node.children)))
+
+    @staticmethod
+    def visit_weak(node: Node):
+        return node.value != ""
+
+    @staticmethod
+    def visit_etagc(node: Node) -> str:
+        return node.value

http_fields/visitors/rfc9110/etag.py

@@ -0,0 +1,12 @@
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.entitytag as entitytag
+
+
+class ETagVisitor(NodeVisitor):
+    """Helper class for parsing ETag header value."""
+
+    visit_entity_tag = entitytag.EntityTagVisitor()
+
+    def visit_etag(self, node: Node) -> entitytag.EntityTag:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/field.py

@@ -0,0 +1,15 @@
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import CaselessMixin, ParsedStr
+
+
+class FieldName(CaselessMixin, ParsedStr):
+    """Represents an RFC 9110 field name."""
+
+    parser = rfc9110.Rule("field-name")
+
+
+class FieldValue(ParsedStr):
+    """Represents an RFC 9110 field value."""
+
+    parser = rfc9110.Rule("field-value")

http_fields/visitors/rfc9110/host.py

@@ -0,0 +1,32 @@
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import CaselessMixin, NonNegativeInt, ParsedStr
+
+
+class Hostname(CaselessMixin, ParsedStr):
+    """An RFC 9110 uri-host. Compares case-insensitively while preserving the original
+    text; self-validating."""
+
+    parser = rfc9110.Rule("uri-host")
+
+
+class HostVisitor(NodeVisitor):
+    def visit_host(self, node: Node) -> tuple[Hostname, NonNegativeInt | None]:
+        # Match children by name: an empty uri-host ("") is valid (reg-name is
+        # *(...)), and the ":" separator visits to None, so positional/truthiness
+        # handling would mis-assign the port as the hostname. The node is already
+        # parsed, so wrap its text as leaves untrusted-free (parse=False).
+        hostname = Hostname("", parse=False)
+        port: NonNegativeInt | None = None
+        for child in node.children:
+            if child.name == "uri-host":
+                hostname = Hostname(child.value, parse=False)
+            elif child.name == "port":
+                port = self.visit(child)
+        return (hostname, port)
+
+    @staticmethod
+    def visit_port(node: Node) -> NonNegativeInt | None:
+        # port = *DIGIT; an empty port ("example.com:") means no port.
+        return NonNegativeInt(node.value) if node.value else None