http-fields 0.1.1__py3-none-any.whl

http_fields/visitors/__init__.py

@@ -0,0 +1 @@
+

http_fields/visitors/rfc3986.py

@@ -0,0 +1,195 @@
+import ipaddress
+import itertools
+
+from abnf import Node, NodeVisitor, ParseError
+from abnf.grammars import rfc3986
+
+
+class URI(str):
+    """Represents an RFC 3986 URI or relative URI."""
+
+    def __new__(cls, s: str, parse: bool = True):
+        if isinstance(s, cls):
+            return s
+        else:
+            try:
+                return super().__new__(
+                    cls, rfc3986.Rule("URI").parse_all(s).value if parse else s
+                )
+            except ParseError as exc:
+                raise ValueError(f'Invalid token value "{s}".') from exc
+
+    def pct_decoded(self):
+        pass
+
+
+class Scheme(str):
+    """Represents an RFC 3986 URL scheme.
+    Case normalization per RFC 3986 section 6.2.2.1 is performed."""
+
+    def __new__(cls, s: str, parse: bool = True):
+        if isinstance(s, cls):
+            return s
+        else:
+            try:
+                return super().__new__(
+                    cls,
+                    (rfc3986.Rule("scheme").parse_all(s).value if parse else s).lower(),
+                )
+            except ParseError as exc:
+                raise ValueError(f'Invalid scheme value "{s}".') from exc
+
+    def __eq__(self, __x: object) -> bool:
+        # scheme comparison should be case-insensitive.
+        if isinstance(__x, str):
+            return self.casefold() == __x.casefold()
+        else:
+            return NotImplemented
+
+    def __hash__(self) -> int:
+        # and because we redefined __eq__, we need to redefine __hash__ for consistency.
+        return hash(self.casefold())
+
+
+class SchemeVisitor(NodeVisitor):
+    def visit_scheme(self, node: Node):
+        return Scheme(node.value, parse=False)
+
+
+class PctEncodedVisitor(NodeVisitor):
+    unreserved_chars = set(
+        itertools.chain(
+            range(48, 58),
+            range(65, 91),
+            range(97, 123),
+            [ord(x) for x in ["-", ".", "_", "~"]],
+        )
+    )
+
+    @staticmethod
+    def visit_hex_digit(node: Node):
+        # perform case normalization per RFC 3986 section 6.2.2.1,
+        return node.value.upper()
+
+    @staticmethod
+    def visit_literal(node: Node):
+        # node.value can only be "%", assuming correct parsing.
+        return node.value
+
+    def visit_pct_encoded(self, node: Node):
+        # perform percent-encoding normalization per RFC 3986 section 6.2.2.2,
+        pct_char = "".join(filter(None, map(self.visit, node.children)))
+        code = int(pct_char[1:], 16)
+        return chr(code) if code in self.unreserved_chars else pct_char
+
+
+class UserInfo(str):
+    def __new__(cls, s: str, parse: bool = True):
+        if isinstance(s, cls):
+            return s
+        else:
+            try:
+                return super().__new__(
+                    cls, rfc3986.Rule("userinfo").parse_all(s).value if parse else s
+                )
+            except ParseError as exc:
+                raise ValueError(f'Invalid userinfo value "{s}".') from exc
+
+
+class UserInfoVisitor(NodeVisitor):
+    @staticmethod
+    def visit_userinfo(node: Node):
+        return UserInfo(node.value, parse=False)
+
+
+class IPvFuture(str):
+    def __new__(cls, s: str, parse: bool = True):
+        if isinstance(s, cls):
+            return s
+        else:
+            try:
+                return super().__new__(
+                    cls, rfc3986.Rule("IPvFuture").parse_all(s).value if parse else s
+                )
+            except ParseError as exc:
+                raise ValueError(f'Invalid IPvFuture value "{s}".') from exc
+
+
+class IPLiteralVisitor(NodeVisitor):
+    def visit_ip_literal(self, node: Node) -> ipaddress.IPv6Address | IPvFuture:
+        return next(filter(None, map(self.visit, node.children)))
+
+    @staticmethod
+    def visit_ipv6address(node: Node):
+        return ipaddress.IPv6Address(node.value)
+
+    @staticmethod
+    def visit_ipvfuture(node: Node):
+        return IPvFuture(node.value, parse=False)
+
+
+class IPv4AddressVisitor(NodeVisitor):
+    @staticmethod
+    def visit_ipv4address(node: Node):
+        return ipaddress.IPv4Address(node.value)
+
+
+class RegName(str):
+    """Represents an RFC 3986 registered-name, more commonly known as hostname.
+    Case normalization per RFC 3986 section 6.2.2.1 is performed."""
+
+    def __new__(cls, s: str, parse: bool = True):
+        if isinstance(s, cls):
+            return s
+        else:
+            try:
+                return super().__new__(
+                    cls,
+                    rfc3986.Rule("reg-name").parse_all(s).value.lower() if parse else s,
+                )
+            except ParseError as exc:
+                raise ValueError(f'Invalid reg-name value "{s}".') from exc
+
+
+class RegNameVisitor(NodeVisitor):
+    visit_pct_encoded = PctEncodedVisitor()
+
+    @staticmethod
+    def visit_unreserved(node: Node):
+        return node.value
+
+    @staticmethod
+    def visit_sub_delims(node: Node):
+        return node.value
+
+    def visit_reg_name(self, node: Node):
+        value = "".join(filter(None, map(self.visit, node.children)))
+        return RegName(value, parse=False)
+
+
+class HostVisitor(NodeVisitor):
+    visit_ip_literal = IPLiteralVisitor()
+    visit_ipv4address = IPv4AddressVisitor()
+    visit_regname = RegNameVisitor()
+
+    def visit_host(
+        self, node: Node
+    ) -> ipaddress.IPv6Address | IPvFuture | ipaddress.IPv4Address | RegName:
+        return next(filter(None, map(self.visit, node.children)))
+
+
+class Authority:
+    userinfo: UserInfo | None
+
+
+class AuthorityVisitor(NodeVisitor):
+    visit_userinfo = UserInfoVisitor()
+    visit_host = HostVisitor()
+
+    @staticmethod
+    def visit_port(node: Node):
+        return int(node.value)
+
+    def visit_authority(self, node: Node):
+
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc6265.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc6265
+
+from http_fields.parsedobjs import ParsedStr
+
+
+class CookieName(ParsedStr):
+    """Represents an RFC 6265 cookie-name. Cookie names are case-sensitive."""
+
+    parser = rfc6265.Rule("cookie-name")
+
+
+class CookieValue(ParsedStr):
+    """Represents a valid RFC 6265 cookie value."""
+
+    parser = rfc6265.Rule("cookie-value")
+
+
+@dataclass(frozen=True, slots=True)
+class CookiePair:
+    name: CookieName
+    value: CookieValue
+
+    def __init__(self, name: str, value: str) -> None:
+        assert isinstance(name, str), "name must be str."
+        assert isinstance(value, str), "value must be str."
+        object.__setattr__(self, "name", CookieName(name))
+        object.__setattr__(self, "value", CookieValue(value))
+
+
+class CookieNameVisitor(NodeVisitor):
+    @staticmethod
+    def visit_cookie_name(node: Node) -> str:
+        return CookieName(node.value, parse=False)
+
+
+class CookieValueVisitor(NodeVisitor):
+    @staticmethod
+    def visit_cookie_value(node: Node):
+        # Return the raw matched text so surrounding DQUOTEs (part of the value
+        # per RFC 6265) are preserved, and an empty value stays "".
+        return node.value
+
+
+class CookiePairVisitor(NodeVisitor):
+    visit_cookie_name = CookieNameVisitor()
+    visit_cookie_value = CookieValueVisitor()
+
+    def visit_cookie_pair(self, node: Node) -> CookiePair:
+        # The "=" separator visits to None; an empty cookie-value visits to ""
+        # (falsy but valid), so filter on identity, not truthiness.
+        name, value = (v for v in map(self.visit, node.children) if v is not None)
+        return CookiePair(name=name, value=value)
+
+
+class CookieStringVisitor(NodeVisitor):
+    visit_cookie_pair = CookiePairVisitor()
+
+    def visit_cookie_string(self, node: Node) -> list[CookiePair]:
+        return list(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc6266.py

@@ -0,0 +1,234 @@
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc6266
+
+from http_fields.parsedobjs import CaselessMixin, ParsedStr
+from http_fields.visitors.rfc7230 import (
+    QuotedString,
+    QuotedStringVisitor,
+    Token,
+    TokenVisitor,
+)
+
+
+class DispositionType(CaselessMixin, ParsedStr):
+    parser = rfc6266.Rule("disposition-type")
+
+
+class DispositionTypeVisitor(NodeVisitor):
+    @staticmethod
+    def visit_disposition_type(node: Node):
+        return DispositionType(node.value, parse=False)
+
+
+class ValueVisitor(NodeVisitor):
+    visit_quoted_string = QuotedStringVisitor()
+    visit_token = TokenVisitor()
+
+    def visit_value(self, node: Node) -> str:
+        return next(filter(None, map(self.visit, node.children)))
+
+
+def NotNone(x: Any) -> bool:
+    return x is not None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ExtValue:
+    charset: str = "utf-8"
+    language: str = ""
+    value: str
+
+    def parm_value(self) -> str:
+        # quote() defaults to safe="/", but "/" is not an RFC 5987 attr-char and
+        # must be percent-encoded; pass safe="" so nothing is left unencoded.
+        encoded = quote(self.value, safe="", encoding=self.charset)
+        return f"{self.charset}'{self.language}'{encoded}"
+
+    def __str__(self):
+        return self.parm_value()
+
+
+class ExtValueVisitor(NodeVisitor):
+    def visit_ext_value(self, node: Node) -> ExtValue:
+        items = list(filter(NotNone, map(self.visit, node.children)))
+        charset = items[0]
+        language = items[1] if len(items) == 3 else ""
+        # value_chars is already the fully pct-decoded byte string (visit_value_chars
+        # resolves pct-encoded octets); decode it once. Passing it through unquote a
+        # second time would re-decode any literal '%' the value legitimately contains.
+        value_chars = items[-1]
+        return ExtValue(
+            charset=charset,
+            language=language,
+            value=value_chars.decode(charset),
+        )
+
+    @staticmethod
+    def visit_charset(node: Node) -> str:
+        return node.value
+
+    @staticmethod
+    def visit_language(node: Node) -> str:
+        return node.value
+
+    @staticmethod
+    def visit_hexdig(node: Node) -> str:
+        return node.value
+
+    def visit_pct_encoded(self, node: Node) -> int:
+        hex = "".join(filter(None, map(self.visit, node.children)))
+        return int(hex, base=16)
+
+    @staticmethod
+    def visit_attr_char(node: Node) -> int:
+        return ord(node.value)
+
+    def visit_value_chars(self, node: Node) -> bytes:
+        return bytes(list(filter(None, map(self.visit, node.children))))
+
+
+class Filename(CaselessMixin, str):
+    """The filename parm names 'filename', 'filename*' are case-insenstive.  I tripped over this
+    once too often while testing, hence a class that removes the obstacle."""
+
+    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)
+            if _s.lower() not in {"filename", "filename*"}:
+                raise ValueError("Value must be 'filename' or 'filename*'.modulo case.")
+            return super().__new__(cls, _s)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({str.__repr__(str(self))})"
+
+
+@dataclass(frozen=True)
+class FilenameParm:
+    name: Filename
+    value: Token | QuotedString | ExtValue
+
+    def __init__(self, name: str, value: str | ExtValue):
+        object.__setattr__(self, "name", Filename(name))
+        if name[-1] == "*":
+            object.__setattr__(
+                self,
+                "value",
+                value if isinstance(value, ExtValue) else ExtValue(value=value),
+            )
+        else:
+            if not isinstance(value, str):
+                raise TypeError('value associated to "filename" must be a str.')
+            try:
+                object.__setattr__(self, "value", Token(value))
+            except ValueError:
+                try:
+                    object.__setattr__(self, "value", QuotedString(value))
+                except ValueError as exc:
+                    raise ValueError(
+                        f"Value {value} could not be parsed as a Token or QuotedString."
+                    ) from exc
+
+    def __str__(self):
+        return f"{self.name}={self.value}"
+
+
+class FilenameParmNodeVisitor(NodeVisitor):
+    visit_value = ValueVisitor()
+    visit_ext_value = ExtValueVisitor()
+
+    @staticmethod
+    def visit_literal(node: Node):
+        return node.value if node.value.lower() in {"filename", "filename*"} else None
+
+    def visit_filename_parm(self, node: Node):
+        assert len(node.children) == 3
+        filename = Filename(self.visit_literal(node.children[0]))
+        assert node.children[1].value == "="
+        if filename == "filename":
+            value = self.visit_value(node.children[2])
+        else:
+            value = self.visit_ext_value(node.children[2])
+        return FilenameParm(filename, value)
+
+
+@dataclass(frozen=True)
+class DispExtParm:
+    name: Token
+    value: Token | QuotedString | ExtValue
+
+    def __init__(self, name: str, value: str | ExtValue):
+        object.__setattr__(self, "name", Token(name))
+        if name[-1] == "*":
+            if isinstance(value, ExtValue):
+                object.__setattr__(self, "value", value)
+            else:
+                object.__setattr__(self, "value", ExtValue(value=value))
+        else:
+            if isinstance(value, str):
+                try:
+                    object.__setattr__(self, "value", Token(value))
+                except ValueError:
+                    try:
+                        object.__setattr__(self, "value", QuotedString(value))
+                    except ValueError as exc:
+                        raise ValueError(
+                            f'Unable to parse "{value}" as a Token or QuotedString.'
+                        ) from exc
+            else:
+                raise TypeError(
+                    f"Value for name {name} must be a string that parses as a "
+                    "Token or QuotedString."
+                )
+
+    def __str__(self):
+        return f"{self.name}={self.value}"
+
+
+class DispExtParmVisitor(NodeVisitor):
+    visit_token = TokenVisitor()
+    visit_value = ValueVisitor()
+    visit_ext_value = ExtValueVisitor()
+
+    def visit_disp_ext_parm(self, node: Node):
+        assert len(node.children) == 3
+        name = self.visit_token(node.children[0])
+        assert node.children[1].value == "="
+        # the RFC 6266 grammar is ambiguous here. The rule 'token' matches everything matched
+        # by 'ext-token', and the same is true for 'value' and 'ext-value'.  Thus we have to
+        # disambiguate here by checking the name for a trailing '*', which marks an ext-thing.
+        # In the case of an ext-name, we reparse the captured value as an ext-value.
+        if name[-1] == "*" and node.children[2].name == "value":
+            src = node.children[2].value
+            ext_node = rfc6266.Rule("ext-value").parse_all(src)
+            value = self.visit_ext_value(ext_node)
+        else:
+            value = self.visit(node.children[2])
+        assert value
+        return DispExtParm(name, value)
+
+
+class DispositionParmNodeVisitor(NodeVisitor):
+    visit_filename_parm = FilenameParmNodeVisitor()
+    visit_disp_ext_parm = DispExtParmVisitor()
+
+    def visit_disposition_parm(self, node: Node) -> tuple[str, str | ExtValue]:
+        parm = next(filter(None, map(self.visit, node.children)))
+        return parm
+
+
+class ContentDispositionNodeVisitor(NodeVisitor):
+    visit_disposition_type = DispositionTypeVisitor()
+    visit_disposition_parm = DispositionParmNodeVisitor()
+
+    def visit_content_disposition(self, node: Node):
+        items = filter(None, map(self.visit, node.children))
+        disposition_type: DispositionType = next(items)
+        disposition_parms: list[FilenameParm | DispExtParm] = [item for item in items]
+        return disposition_type, disposition_parms

http_fields/visitors/rfc7230.py

@@ -0,0 +1,80 @@
+from abnf.grammars import rfc7230
+from abnf.parser import LiteralNode, Node, NodeVisitor
+
+from http_fields.parsedobjs import CaselessMixin, ParsedStr
+
+
+class QuotedPairVisitor(NodeVisitor):
+    def visit_quoted_pair(self, node: Node) -> str:
+        assert (
+            isinstance(node.children[0], LiteralNode) and node.children[0].value == "\\"
+        )
+        return self.visit(node.children[1])
+
+    @staticmethod
+    def visit_htab(node: Node) -> str:
+        return node.value
+
+    @staticmethod
+    def visit_sp(node: Node) -> str:
+        return node.value
+
+    @staticmethod
+    def visit_vchar(node: Node) -> str:
+        return node.value
+
+    @staticmethod
+    def visit_obs_text(node: Node) -> str:
+        return node.value
+
+
+class QuotedString(ParsedStr):
+    """Represents an RFC 7230 quoted-string.
+    A QuotedString can be created either double-quoted or not; the result will be a double-quoted
+    string, escaped as needed."""
+
+    parser = rfc7230.Rule("quoted-string")
+
+    def __new__(cls, s: str, parse: bool = True):
+        assert isinstance(s, str)
+        if isinstance(s, cls):
+            return s
+        else:
+            # if s is double-quoted, we parse as is.  if not, we escape what needs to be escaped,
+            # wrap in double quotes, and parse that.
+            if s == "":
+                dquoted_value = '""'
+            elif len(s) > 1 and s[0] == '"' and s[-1] == '"':
+                dquoted_value = s
+            else:
+                escaped_value = "".join(f"\\{x}" if x in ["\\", '"'] else x for x in s)
+                dquoted_value = f'"{escaped_value}"'
+            return super().__new__(cls, dquoted_value)
+
+
+class QuotedStringVisitor(NodeVisitor):
+    """Visits an RFC7230 quoted-string."""
+
+    visit_quoted_pair = QuotedPairVisitor()
+
+    def visit_quoted_string(self, node: Node) -> QuotedString:
+        value = "".join(x for x in map(self.visit, node.children) if x is not None)
+        return QuotedString(value, parse=False)
+
+    @staticmethod
+    def visit_qdtext(node: Node) -> str:
+        return node.value
+
+
+class Token(CaselessMixin, ParsedStr):
+    """Represents an RFC 7230 token."""
+
+    parser = rfc7230.Rule("token")
+
+
+class TokenVisitor(NodeVisitor):
+    """Visits a token node."""
+
+    @staticmethod
+    def visit_token(node: Node) -> Token:
+        return Token(node.value, parse=False)

http_fields/visitors/rfc7239.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+from http_fields.visitors.rfc9110.parameters import (
+    Param,
+    ParamsInput,
+    as_params,
+    parsed_param,
+)
+
+__all__ = ["ForwardedElement", "ForwardedVisitor"]
+
+
+@dataclass(frozen=True)
+class ForwardedElement:
+    """One Forwarded element (RFC 7239): an ordered sequence of ``name=value`` pairs,
+    e.g. ``for=192.0.2.60;proto=http``."""
+
+    pairs: tuple[Param, ...]
+
+    def __init__(self, pairs: ParamsInput) -> None:
+        # Each pair is a self-validating Param; raw (name, value) tuples are coerced.
+        object.__setattr__(self, "pairs", as_params(pairs))
+
+    def __str__(self) -> str:
+        return ";".join(str(p) for p in self.pairs)
+
+
+class ForwardedVisitor(NodeVisitor):
+    @staticmethod
+    def visit_forwarded_pair(node: Node) -> Param:
+        # forwarded-pair = token "=" value
+        return parsed_param(node.children[0].value, node.children[-1].value)
+
+    def visit_forwarded_element(self, node: Node) -> ForwardedElement:
+        pairs = [x for x in map(self.visit, node.children) if isinstance(x, Param)]
+        return ForwardedElement(pairs)
+
+    def visit_forwarded(self, node: Node) -> list[ForwardedElement]:
+        return [
+            x for x in map(self.visit, node.children) if isinstance(x, ForwardedElement)
+        ]

http_fields/visitors/rfc7240.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+from http_fields.visitors.rfc9110.parameters import (
+    Param,
+    ParamsInput,
+    QuotedString,
+    Token,
+    as_params,
+    param_from_node,
+    parsed_param,
+    value_leaf,
+)
+
+__all__ = ["Preference", "PreferVisitor", "PreferenceAppliedVisitor"]
+
+
+@dataclass(frozen=True)
+class Preference:
+    """One RFC 7240 preference: a token, an optional value, and optional parameters.
+    Self-validating: an invalid name, value, or parameter cannot be built."""
+
+    name: Token
+    value: Token | QuotedString | None = None
+    parameters: tuple[Param, ...] = ()
+
+    def __init__(
+        self,
+        name: str,
+        value: str | None = None,
+        parameters: ParamsInput = (),
+    ) -> None:
+        object.__setattr__(self, "name", Token(name))
+        object.__setattr__(
+            self, "value", value_leaf(value) if value is not None else None
+        )
+        object.__setattr__(self, "parameters", as_params(parameters))
+
+    def __str__(self) -> str:
+        out = str(self.name) if self.value is None else f"{self.name}={self.value}"
+        for p in self.parameters:
+            out += f"; {p}"
+        return out
+
+
+class PreferVisitor(NodeVisitor):
+    def visit_preference(self, node: Node) -> Preference:
+        # token [ "=" word ] *( ";" parameter )
+        name = node.children[0].value
+        value: str | None = None
+        params: list[Param] = []
+        seen_eq = False
+        for child in node.children[1:]:
+            if child.name == "parameter":
+                params.append(param_from_node(child))
+            elif child.name == "literal" and child.value == "=" and not params:
+                seen_eq = True
+            elif seen_eq and value is None and child.name not in ("BWS", "OWS"):
+                value = child.value
+        # Build the head (name + optional value) trusted, then hand its leaves to
+        # Preference, whose coercion passes them through unchanged.
+        head = parsed_param(name, value)
+        return Preference(head.name, head.value, params)
+
+    def visit_prefer(self, node: Node) -> list[Preference]:
+        return [
+            self.visit_preference(c) for c in node.children if c.name == "preference"
+        ]
+
+
+class PreferenceAppliedVisitor(PreferVisitor):
+    # RFC 7240's abnf uses the same `preference` production for Preference-Applied.
+    def visit_preference_applied(self, node: Node) -> list[Preference]:
+        return [
+            self.visit_preference(c) for c in node.children if c.name == "preference"
+        ]