http-fields 0.1.1__py3-none-any.whl

http_fields/visitors/rfc9110/te.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+from http_fields.visitors.rfc9110.parameters import Parameter
+from http_fields.visitors.rfc9110.quotedstring import QuotedStringVisitor
+from http_fields.visitors.rfc9110.token import Token, TokenVisitor
+from http_fields.visitors.rfc9110.weight import Weight, WeightVisitor, as_qvalue
+
+__all__ = ["TCoding", "TEVisitor"]
+
+
+@dataclass(frozen=True)
+class TCoding:
+    """A single TE t-coding: a transfer-coding (or "trailers") with an optional weight and
+    transfer-parameters."""
+
+    coding: Token
+    weight: Weight | None = None
+    parameters: tuple[Parameter, ...] = ()
+
+    def __init__(
+        self,
+        coding: str,
+        weight: Weight | None = None,
+        parameters: tuple[Parameter, ...] = (),
+    ) -> None:
+        # coding self-validates as a Token; weight and Parameter are already safe.
+        object.__setattr__(self, "coding", Token(coding))
+        object.__setattr__(self, "weight", weight)
+        object.__setattr__(self, "parameters", tuple(parameters))
+
+    def __str__(self) -> str:
+        parts = [self.coding, *(str(p) for p in self.parameters)]
+        if self.weight is not None:
+            parts.append(str(self.weight))
+        return ";".join(parts)
+
+
+class TEVisitor(NodeVisitor):
+    visit_token = TokenVisitor()
+    visit_quoted_string = QuotedStringVisitor()
+    visit_weight = WeightVisitor()
+
+    def visit_transfer_parameter(self, node: Node) -> Parameter:
+        items = [x for x in map(self.visit, node.children) if x is not None]
+        return Parameter(str(items[0]), str(items[-1]))
+
+    def visit_transfer_coding(self, node: Node) -> tuple[Token, list[Parameter]]:
+        coding: Token | None = None
+        params: list[Parameter] = []
+        for child in node.children:
+            result = self.visit(child)
+            if isinstance(result, Parameter):
+                params.append(result)
+            elif isinstance(result, Token):
+                coding = result
+        assert coding is not None
+        return (coding, params)
+
+    def visit_t_codings(self, node: Node) -> TCoding:
+        if node.value.strip().lower() == "trailers":
+            return TCoding("trailers")
+        coding = ""
+        weight: Weight | None = None
+        params: list[Parameter] = []
+        for child in node.children:
+            result = self.visit(child)
+            if isinstance(result, tuple):
+                coding, params = result
+            elif isinstance(result, Weight):
+                weight = result
+        # the parser usually captures "q=..." as a transfer-parameter rather than a weight.
+        # Only treat it as a weight if it is an unquoted, in-range qvalue.
+        if weight is None and params and str(params[-1].name).lower() == "q":
+            qvalue = as_qvalue(params[-1].value)
+            if qvalue is not None:
+                weight = Weight(qvalue=qvalue)
+                params = params[:-1]
+        return TCoding(coding, weight, tuple(params))
+
+    def visit_te(self, node: Node) -> list[TCoding]:
+        return [x for x in map(self.visit, node.children) if isinstance(x, TCoding)]

http_fields/visitors/rfc9110/token.py

@@ -0,0 +1,18 @@
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import CaselessMixin, ParsedStr
+
+
+class Token(CaselessMixin, ParsedStr):
+    """Represents an RFC 9110 token."""
+
+    parser = rfc9110.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/rfc9110/token68.py

@@ -0,0 +1,18 @@
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import CaselessMixin, ParsedStr
+
+
+class Token68(CaselessMixin, ParsedStr):
+    """Represents an RFC 9110 token68."""
+
+    parser = rfc9110.Rule("token68")
+
+
+class Token68Visitor(NodeVisitor):
+    """Visits a token68 node."""
+
+    @staticmethod
+    def visit_token68(node: Node) -> Token68:
+        return Token68(node.value, parse=False)

http_fields/visitors/rfc9110/type.py

@@ -0,0 +1,17 @@
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.token as token
+
+
+class TypeVisitor(NodeVisitor):
+    visit_token = token.TokenVisitor()
+
+    def visit_type(self, node: Node):
+        return next(filter(None, map(self.visit, node.children)))
+
+
+class SubtypeVisitor(NodeVisitor):
+    visit_token = token.TokenVisitor()
+
+    def visit_subtype(self, node: Node):
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/upgrade.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import ParsedStr
+
+__all__ = ["Protocol", "ProtocolName", "ProtocolVersion", "UpgradeVisitor"]
+
+
+class ProtocolName(ParsedStr):
+    """An RFC 9110 protocol-name token. Self-validating."""
+
+    parser = rfc9110.Rule("protocol-name")
+
+
+class ProtocolVersion(ParsedStr):
+    """An RFC 9110 protocol-version token. Self-validating."""
+
+    parser = rfc9110.Rule("protocol-version")
+
+
+@dataclass(frozen=True)
+class Protocol:
+    """An RFC 9110 protocol: a name with an optional version, e.g. ``HTTP/2``."""
+
+    name: ProtocolName
+    version: ProtocolVersion | None = None
+
+    def __init__(self, name: str, version: str | None = None) -> None:
+        # Coerce str -> leaf (which validates); an existing leaf passes through
+        # unchanged, so a value from the visitor is not re-parsed.
+        object.__setattr__(self, "name", ProtocolName(name))
+        object.__setattr__(
+            self, "version", ProtocolVersion(version) if version is not None else None
+        )
+
+    def __str__(self) -> str:
+        return self.name + (f"/{self.version}" if self.version else "")
+
+
+class UpgradeVisitor(NodeVisitor):
+    @staticmethod
+    def visit_protocol_name(node: Node) -> str:
+        return node.value
+
+    @staticmethod
+    def visit_protocol_version(node: Node) -> str:
+        return node.value
+
+    def visit_protocol(self, node: Node) -> Protocol:
+        items = [x for x in map(self.visit, node.children) if x is not None]
+        version = ProtocolVersion(items[1], parse=False) if len(items) == 2 else None
+        return Protocol(ProtocolName(items[0], parse=False), version)
+
+    def visit_upgrade(self, node: Node) -> list[Protocol]:
+        return [x for x in map(self.visit, node.children) if isinstance(x, Protocol)]

http_fields/visitors/rfc9110/useragent.py

@@ -0,0 +1,16 @@
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.comment as comment
+import http_fields.visitors.rfc9110.product as product
+import http_fields.visitors.rfc9110.token as token
+
+__all__ = ["UserAgentVisitor"]
+
+
+class UserAgentVisitor(NodeVisitor):
+    visit_comment = comment.CommentVisitor()
+    visit_product = product.ProductVisitor()
+    visit_token = token.TokenVisitor()
+
+    def visit_user_agent(self, node: Node) -> list[product.Product | comment.Comment]:
+        return list(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/vary.py

@@ -0,0 +1,10 @@
+from abnf import Node, NodeVisitor
+
+
+class VaryVisitor(NodeVisitor):
+    def visit_vary(self, node: Node) -> list[str]:
+        return list(filter(None, map(self.visit, node.children)))
+
+    @staticmethod
+    def visit_field_name(node: Node):
+        return node.value

http_fields/visitors/rfc9110/via.py

@@ -0,0 +1,86 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import ParsedStr
+
+__all__ = ["Comment", "ReceivedBy", "ReceivedProtocol", "ViaElement", "ViaVisitor"]
+
+
+class ReceivedProtocol(ParsedStr):
+    """An RFC 9110 received-protocol (e.g. ``HTTP/1.1``). Self-validating."""
+
+    parser = rfc9110.Rule("received-protocol")
+
+
+class ReceivedBy(ParsedStr):
+    """An RFC 9110 received-by (a host[:port] or pseudonym). Self-validating."""
+
+    parser = rfc9110.Rule("received-by")
+
+
+class Comment(ParsedStr):
+    """An RFC 9110 comment, including its enclosing parentheses. Self-validating."""
+
+    parser = rfc9110.Rule("comment")
+
+
+@dataclass(frozen=True)
+class ViaElement:
+    """One hop in a Via header: a received-protocol, a received-by, and an optional comment."""
+
+    received_protocol: ReceivedProtocol
+    received_by: ReceivedBy
+    comment: Comment | None = None
+
+    def __init__(
+        self,
+        received_protocol: str,
+        received_by: str,
+        comment: str | None = None,
+    ) -> None:
+        # Each field self-validates as a leaf; an existing leaf passes through unchanged.
+        object.__setattr__(
+            self, "received_protocol", ReceivedProtocol(received_protocol)
+        )
+        object.__setattr__(self, "received_by", ReceivedBy(received_by))
+        object.__setattr__(
+            self, "comment", Comment(comment) if comment is not None else None
+        )
+
+    def __str__(self) -> str:
+        text = f"{self.received_protocol} {self.received_by}"
+        if self.comment:
+            text += f" {self.comment}"
+        return text
+
+
+def _element(proto: str, by: str, comment: str | None) -> ViaElement:
+    # Build from already-validated node text (parse=False), so construction does not re-parse.
+    return ViaElement(
+        ReceivedProtocol(proto, parse=False),
+        ReceivedBy(by, parse=False),
+        Comment(comment, parse=False) if comment is not None else None,
+    )
+
+
+class ViaVisitor(NodeVisitor):
+    def visit_via(self, node: Node) -> list[ViaElement]:
+        # the Via node is a flat sequence; each element starts at a received-protocol.
+        elements: list[ViaElement] = []
+        proto: str | None = None
+        by: str = ""
+        comment: str | None = None
+        for child in node.children:
+            if child.name == "received-protocol":
+                if proto is not None:
+                    elements.append(_element(proto, by, comment))
+                proto, by, comment = child.value, "", None
+            elif child.name == "received-by":
+                by = child.value
+            elif child.name == "comment":
+                comment = child.value
+        if proto is not None:
+            elements.append(_element(proto, by, comment))
+        return elements

http_fields/visitors/rfc9110/weight.py

@@ -0,0 +1,40 @@
+import re
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+__all__ = ["Weight", "WeightVisitor", "as_qvalue"]
+
+# qvalue = ( "0" [ "." 0*3DIGIT ] ) / ( "1" [ "." 0*3("0") ] ) -- unquoted, 0..1.
+_QVALUE_RE = re.compile(r"^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$")
+
+
+def as_qvalue(value: object) -> float | None:
+    """Return the float weight if ``value`` is a syntactically valid, unquoted
+    qvalue in [0, 1]; otherwise None (so a quoted or out-of-range "q" stays an
+    ordinary parameter rather than crashing or being silently clamped)."""
+    text = str(value)
+    return float(text) if _QVALUE_RE.match(text) else None
+
+
+@dataclass(frozen=True)
+class Weight:
+    qvalue: float
+
+    def __str__(self):
+        return f"q={self.qvalue:.3f}".rstrip("0").rstrip(".")
+
+
+class WeightVisitor(NodeVisitor):
+    def visit_weight(self, node: Node) -> Weight:
+        # We ignore everything other than the qvalue. Filter on "is not None"
+        # rather than truthiness: a qvalue of 0.0 is valid ("not acceptable")
+        # but falsy, so filter(None, ...) would wrongly discard it.
+        qvalue: float = next(
+            value for value in map(self.visit, node.children) if value is not None
+        )
+        return Weight(qvalue=qvalue)
+
+    @staticmethod
+    def visit_qvalue(node: Node):
+        return float(node.value)

http_fields/visitors/rfc9110/wwwauthenticate.py

@@ -0,0 +1,21 @@
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.challenge as challenge
+
+
+class WWWAuthenticateVisitor(NodeVisitor):
+    visit_challenge = challenge.ChallengeVisitor()
+
+    def visit_www_authenticate(
+        self, node: Node
+    ) -> list[challenge.TokenChallenge | challenge.AuthParamChallenge]:
+        return list(filter(None, map(self.visit, node.children)))
+
+
+class ProxyAuthenticateVisitor(NodeVisitor):
+    visit_challenge = challenge.ChallengeVisitor()
+
+    def visit_proxy_authenticate(
+        self, node: Node
+    ) -> list[challenge.TokenChallenge | challenge.AuthParamChallenge]:
+        return list(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9111.py

@@ -0,0 +1,92 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from abnf import Node, NodeVisitor
+
+from http_fields.parsedobjs import NonNegativeInt
+from http_fields.visitors.rfc9110 import (
+    HttpDateVisitor,
+    QuotedString,
+    QuotedStringVisitor,
+    Token,
+    TokenVisitor,
+)
+
+
+class AgeVisitor(NodeVisitor):
+    @staticmethod
+    def visit_age(node: Node):
+        return NonNegativeInt(node.value)
+
+
+@dataclass(frozen=True)
+class CacheDirective:
+    name: Token
+    value: Any = True
+
+    def __init__(self, name: str, value: Any = True) -> None:
+        object.__setattr__(self, "name", Token(name))
+        resolved: Any
+        if name == "max-stale":
+            # RFC 9111 section 5.2.1.2: max-stale may be used with no value,
+            # meaning "stale responses of any age".
+            resolved = True if value is None or value is True else NonNegativeInt(value)
+        elif name in ["max-age", "s-maxage", "min-fresh"]:
+            if value is None:
+                raise ValueError(f"Cache directive '{name}' requires a value.")
+            resolved = NonNegativeInt(value)
+        elif name in [
+            "immutable",
+            "must-revalidate",
+            "must-understand",
+            "no-store",
+            "no-transform",
+            "only-if-cached",
+            "proxy-revalidate",
+            "public",
+        ]:
+            # immutable is defined in RFC 8246, a proposed standard.  But the directive appears to be in use.
+            resolved = True
+        elif name in ["no-cache", "private"]:
+            # should consider parsing value to ensure it matches #field-name.
+            resolved = QuotedString(value) if isinstance(value, str) else True
+        else:
+            # extension (non-standard) directive: keep any value it carries.
+            if isinstance(value, str):
+                try:
+                    resolved = Token(value)
+                except ValueError:
+                    resolved = QuotedString(value)
+            else:
+                resolved = True
+        object.__setattr__(self, "value", resolved)
+
+    def __str__(self):
+        return str(self.name) if self.value is True else f"{self.name}={self.value}"
+
+
+class CacheDirectiveVisitor(NodeVisitor):
+    visit_quoted_string = QuotedStringVisitor()
+    visit_token = TokenVisitor()
+
+    def visit_cache_directive(self, node: Node) -> CacheDirective:
+        items = filter(None, map(self.visit, node.children))
+        name = next(items)
+        value = next(items, None)
+        return CacheDirective(name, value)
+
+
+class CacheControlVisitor(NodeVisitor):
+    visit_cache_directive = CacheDirectiveVisitor()
+
+    def visit_cache_control(self, node: Node) -> list[CacheDirective]:
+        directives = list(filter(None, map(self.visit, node.children)))
+        return directives
+
+
+class ExpiresVisitor(NodeVisitor):
+    visit_http_date = HttpDateVisitor()
+
+    def visit_expires(self, node: Node) -> datetime:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/wwwauthenticate.py

@@ -0,0 +1,24 @@
+"""WWW-Authenticate header class."""
+
+from typing import ClassVar
+
+from abnf import Rule
+from abnf.grammars import rfc9110
+
+from http_fields.authbases import ChallengeListHeader
+from http_fields.visitors.rfc9110 import (
+    AuthParam,
+    AuthParamChallenge,
+    TokenChallenge,
+    WWWAuthenticateVisitor,
+)
+
+__all__ = ["AuthParam", "AuthParamChallenge", "TokenChallenge", "WWWAuthenticate"]
+
+
+class WWWAuthenticate(ChallengeListHeader):
+    """WWW-Authenticate header, as defined by RFC 9110."""
+
+    name: ClassVar[str] = "www-authenticate"
+    rule: ClassVar[Rule] = rfc9110.Rule("WWW-Authenticate")
+    visitor = WWWAuthenticateVisitor()

http_fields-0.1.1.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: http-fields
+Version: 0.1.1
+Summary: Typed, immutable HTTP header fields for Python, parsed and validated against RFC ABNF grammars
+Project-URL: Homepage, https://github.com/declaresub/http-fields
+Project-URL: Documentation, https://http-fields.readthedocs.io/
+Project-URL: Repository, https://github.com/declaresub/http-fields
+Project-URL: Changelog, https://github.com/declaresub/http-fields/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/declaresub/http-fields/issues
+Author-email: Charles Yeomans <charles@declaresub.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: abnf,generator,headers,http,parser
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: abnf>=2.6.0
+Requires-Dist: typing-extensions>=4.0
+Description-Content-Type: text/markdown
+
+# http-fields
+
+Typed, validated HTTP headers for Python. Each header is an immutable
+[dataclass](https://docs.python.org/3/library/dataclasses.html) whose fields are the structured
+components of the header. [abnf](https://pypi.org/project/abnf/) grammars are used both to
+**parse** incoming header strings and to **validate** field values, so a constructed header is
+always well-formed.
+
+Requires Python 3.10+.
+
+```python
+from http_fields import ContentType, Header
+
+ct = ContentType.parse("text/html; charset=UTF-8")
+ct.type, ct.subtype, ct.charset          # ('text', 'html', 'UTF-8')
+str(ct)                                   # 'Content-Type: text/html;charset=UTF-8'
+
+ContentType.of(type="text", subtype="html", charset="utf-8")   # build from pieces
+Header.create("x-request-id", "abc123")                         # dispatch by name
+```
+
+## Install
+
+```sh
+uv add http-fields
+# or: pip install http-fields
+```
+
+## Documentation
+
+Full documentation: **<https://http-fields.readthedocs.io/>**
+
+It follows the [Diátaxis](https://diataxis.fr/) model:
+
+- **Tutorial:**
+  [Getting started](https://http-fields.readthedocs.io/en/latest/tutorials/getting-started.html)
+- **How-to guides:**
+  [parse & build](https://http-fields.readthedocs.io/en/latest/how-to/parse-and-build-headers.html) ·
+  [custom / unknown headers](https://http-fields.readthedocs.io/en/latest/how-to/custom-and-unknown-headers.html) ·
+  [Structured Fields](https://http-fields.readthedocs.io/en/latest/how-to/structured-fields.html)
+- **Reference:**
+  [header catalog](https://http-fields.readthedocs.io/en/latest/reference/headers.html) ·
+  [`structuredfields` API](https://http-fields.readthedocs.io/en/latest/reference/structured-fields.html)
+- **Explanation:**
+  [the header model](https://http-fields.readthedocs.io/en/latest/explanation/design.html)
+
+The sources live in [`docs/`](docs/index.md).
+
+## Development
+
+```sh
+uv sync                       # create the environment
+uv run pytest                 # run the tests
+uv run ruff check .           # lint
+uv run ruff format .          # format
+uv run basedpyright           # type-check
+
+uv sync --group docs          # add the docs toolchain
+uv run sphinx-build -b html docs docs/_build/html   # build the docs locally
+```