http-fields 0.1.1__py3-none-any.whl

http_fields/visitors/rfc9110/httpdate.py

@@ -0,0 +1,167 @@
+from datetime import date, datetime, time, timezone
+from typing import Any
+
+from abnf import Node, NodeVisitor
+
+
+class MonthVisitor(NodeVisitor):
+    months = {
+        "Jan": 1,
+        "Feb": 2,
+        "Mar": 3,
+        "Apr": 4,
+        "May": 5,
+        "Jun": 6,
+        "Jul": 7,
+        "Aug": 8,
+        "Sep": 9,
+        "Oct": 10,
+        "Nov": 11,
+        "Dec": 12,
+    }
+
+    def visit_month(self, node: Node) -> int:
+        return self.months[node.value]
+
+
+class DayVisitor(NodeVisitor):
+    def visit_day(self, node: Node) -> int:
+        return int(node.value)
+
+
+class YearVisitor(NodeVisitor):
+    def visit_year(self, node: Node) -> int:
+        return int(node.value)
+
+
+class Date1Visitor(NodeVisitor):
+    visit_month = MonthVisitor()
+    visit_day = DayVisitor()
+    visit_year = YearVisitor()
+
+    def visit_date1(self, node: Node) -> date:
+        day: int
+        month: int
+        year: int
+        day, month, year = filter(None, map(self.visit, node.children))
+        return date(year=year, month=month, day=day)
+
+
+class Date2Visitor(NodeVisitor):
+    visit_day = DayVisitor()
+    visit_month = MonthVisitor()
+
+    def visit_date2(self, node: Node) -> date:
+        day: int
+        month: int
+        digit1: str
+        digit2: str
+        day, month, digit1, digit2 = filter(None, map(self.visit, node.children))
+        year = int("20" + digit1 + digit2)
+        date2 = date(year=year, month=month, day=day)
+
+        # From RFC 2616 <https://tools.ietf.org/html/rfc2616#section-19.3>:
+        #
+        # "HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date
+        # which appears to be more than 50 years in the future is in fact
+        # in the past (this helps solve the "year 2000" problem).
+        #
+        # So, on the off chance that we are parsing and RFC 850 date, we'll use this
+        # suggestion to resolve the 2-digit date.
+
+        today = datetime.now(timezone.utc).date()
+        if date2 > today.replace(year=today.year + 50):
+            date2 = date2.replace(year=date2.year - 100)
+        return date2
+
+    @staticmethod
+    def visit_digit(node: Node) -> str:
+        return node.value
+
+
+class Date3Visitor(NodeVisitor):
+    visit_month = MonthVisitor()
+
+    def visit_date3(self, node: Node) -> tuple[int, int]:
+        values: list[Any] = list(filter(None, map(self.visit, node.children)))
+        month: int = values[0]
+        day = int("".join(values[1:]))
+        return month, day
+
+    @staticmethod
+    def visit_digit(node: Node) -> str:
+        return node.value
+
+
+class TimeOfDayVisitor(NodeVisitor):
+    def visit_time_of_day(self, node: Node) -> time:
+        hour, minute, second = filter(
+            lambda x: x is not None, map(self.visit, node.children)
+        )
+        return time(hour=hour, minute=minute, second=second)
+
+    def visit_hour(self, node: Node) -> int:
+        return int(node.value)
+
+    def visit_minute(self, node: Node) -> int:
+        return int(node.value)
+
+    def visit_second(self, node: Node) -> int:
+        return int(node.value)
+
+
+class IMfFixDateVisitor(NodeVisitor):
+    visit_date1 = Date1Visitor()
+    visit_time_of_day = TimeOfDayVisitor()
+
+    def visit_imf_fixdate(self, node: Node) -> datetime:
+        date_: date
+        time_of_day: time
+        date_, time_of_day = filter(None, map(self.visit, node.children))
+        return datetime.combine(date=date_, time=time_of_day).replace(
+            tzinfo=timezone.utc
+        )
+
+
+class RFC850DateVisitor(NodeVisitor):
+    visit_date2 = Date2Visitor()
+    visit_time_of_day = TimeOfDayVisitor()
+
+    def visit_rfc850_date(self, node: Node) -> datetime:
+        date_: date
+        time_of_day: time
+        date_, time_of_day = filter(None, map(self.visit, node.children))
+        return datetime.combine(date=date_, time=time_of_day).replace(
+            tzinfo=timezone.utc
+        )
+
+
+class AscTimeDateVisitor(NodeVisitor):
+    visit_date3 = Date3Visitor()
+    visit_time_of_day = TimeOfDayVisitor()
+    visit_year = YearVisitor()
+
+    def visit_asctime_date(self, node: Node) -> datetime:
+        date3: tuple[int, int]
+        time_of_day: time
+        year: int
+        date3, time_of_day, year = filter(None, map(self.visit, node.children))
+        return datetime.combine(
+            date(year=year, month=date3[0], day=date3[1]), time=time_of_day
+        ).replace(tzinfo=timezone.utc)
+
+
+class ObsDateVisitor(NodeVisitor):
+    visit_rfc850_date = RFC850DateVisitor()
+    visit_asctime_date = AscTimeDateVisitor()
+
+    def visit_obs_date(self, node: Node):
+        return next(filter(None, map(self.visit, node.children)))
+
+
+class HttpDateVisitor(NodeVisitor):
+    visit_imf_fixdate = IMfFixDateVisitor()
+    visit_obs_date = ObsDateVisitor()
+
+    def visit_http_date(self, node: Node) -> datetime:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/ifmatch.py

@@ -0,0 +1,24 @@
+from typing import Literal
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.entitytag as entitytag
+
+
+class IfMatchVisitor(NodeVisitor):
+    visit_entity_tag = entitytag.EntityTagVisitor()
+
+    @staticmethod
+    def visit_literal(node: Node):
+        return "*" if node.value == "*" else None
+
+    def visit_if_match(self, node: Node) -> Literal["*"] | list[entitytag.EntityTag]:
+        items = list(filter(None, map(self.visit, node.children)))
+        if not items:
+            empty_list: list[entitytag.EntityTag] = []
+            return empty_list
+
+        if items[0] == "*":
+            return "*"
+        else:
+            return items

http_fields/visitors/rfc9110/ifmodifiedsince.py

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

http_fields/visitors/rfc9110/ifnonematch.py

@@ -0,0 +1,26 @@
+from typing import Literal
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.entitytag as entitytag
+
+
+class IfNoneMatchVisitor(NodeVisitor):
+    visit_entity_tag = entitytag.EntityTagVisitor()
+
+    @staticmethod
+    def visit_literal(node: Node):
+        return "*" if node.value == "*" else None
+
+    def visit_if_none_match(
+        self, node: Node
+    ) -> Literal["*"] | list[entitytag.EntityTag]:
+        items = list(filter(None, map(self.visit, node.children)))
+        if not items:
+            empty_list: list[entitytag.EntityTag] = []
+            return empty_list
+
+        if items[0] == "*":
+            return "*"
+        else:
+            return items

http_fields/visitors/rfc9110/ifunmodifiedsince.py

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

http_fields/visitors/rfc9110/lastmodified.py

@@ -0,0 +1,14 @@
+from datetime import datetime
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.httpdate as httpdate
+
+__all__ = ["LastModifiedVisitor"]
+
+
+class LastModifiedVisitor(NodeVisitor):
+    visit_http_date = httpdate.HttpDateVisitor()
+
+    def visit_last_modified(self, node: Node) -> datetime:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/location.py

@@ -0,0 +1,9 @@
+from abnf import Node, NodeVisitor
+
+__all__ = ["LocationVisitor"]
+
+
+class LocationVisitor(NodeVisitor):
+    def visit_location(self, node: Node):
+        # in the future, this might be replaced with a more detailed uri object.
+        return node.value

http_fields/visitors/rfc9110/parameters.py

@@ -0,0 +1,124 @@
+from collections.abc import Iterable
+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
+
+__all__ = [
+    "Param",
+    "ParamsInput",
+    "Parameter",
+    "ParameterVisitor",
+    "ParametersVisitor",
+    "as_params",
+    "param_from_node",
+    "parsed_param",
+    "value_leaf",
+]
+
+
+Token = token.Token
+TokenVisitor = token.TokenVisitor
+QuotedString = quotedstring.QuotedString
+QuotedStringVisitor = quotedstring.QuotedStringVisitor
+
+
+def value_leaf(value: str) -> "Token | QuotedString":
+    """Coerce a parameter value to the right self-validating leaf: a Token if it is one,
+    otherwise a (double-quoted, escaped) QuotedString. An existing leaf passes through."""
+    try:
+        return Token(value)
+    except ValueError:
+        return QuotedString(value)
+
+
+@dataclass(frozen=True)
+class Parameter:
+    name: Token
+    value: Token | QuotedString
+
+    def __init__(self, name: str, value: str):
+        object.__setattr__(self, "name", Token(name))
+        object.__setattr__(self, "value", value_leaf(value))
+
+    def __str__(self):
+        return f"{self.name}={self.value}"
+
+
+@dataclass(frozen=True)
+class Param:
+    """A generic ``name`` or ``name=value`` parameter: a token name with an optional
+    token / quoted-string value. Used by headers (Link, Prefer, Alt-Svc, ...) whose
+    parameters may be valueless. Self-validating: an invalid name or value cannot be built."""
+
+    name: Token
+    value: Token | QuotedString | None = None
+
+    def __init__(self, name: str, value: str | None = None) -> None:
+        object.__setattr__(self, "name", Token(name))
+        object.__setattr__(
+            self, "value", value_leaf(value) if value is not None else None
+        )
+
+    def __str__(self) -> str:
+        return str(self.name) if self.value is None else f"{self.name}={self.value}"
+
+
+# What a value object's constructor accepts for its params: ready-made Param objects
+# or raw ``(name[, value])`` tuples (coerced by as_params).
+ParamsInput = Iterable[Param | tuple[str, ...]]
+
+
+def as_params(items: ParamsInput) -> tuple[Param, ...]:
+    """Coerce an iterable of ``Param`` (kept as-is) or raw ``(name[, value])`` tuples into a
+    tuple of validated ``Param``. Lets value-object constructors accept either form."""
+    return tuple(p if isinstance(p, Param) else Param(*p) for p in items)
+
+
+def parsed_param(name: str, value: str | None) -> Param:
+    """Build a ``Param`` from already-parsed node text, wrapping the parts as leaves with
+    ``parse=False`` so the parse() path does not re-parse (QuotedString still validates)."""
+    if value is None:
+        return Param(Token(name, parse=False))
+    leaf = QuotedString(value) if value[:1] == '"' else Token(value, parse=False)
+    return Param(Token(name, parse=False), leaf)
+
+
+def param_from_node(node: Node) -> Param:
+    """Build a ``Param`` from a ``token [ "=" ( token / quoted-string ) ]`` node (the shape
+    shared by Link-, Prefer-, and Alt-Svc-style parameters)."""
+    name = node.children[0].value
+    value: str | None = None
+    seen_eq = False
+    for child in node.children[1:]:
+        if child.name == "literal" and child.value == "=":
+            seen_eq = True
+        elif seen_eq and child.name not in ("BWS", "OWS"):
+            value = child.value
+    return parsed_param(name, value)
+
+
+class ParameterVisitor(NodeVisitor):
+    visit_quoted_string = QuotedStringVisitor()
+    visit_token = TokenVisitor()
+
+    def visit_parameter(self, node: Node):
+        name: Token
+        value: Token | QuotedString
+        name, value = filter(None, map(self.visit, node.children))
+        return Parameter(name, value)
+
+    def visit_parameter_name(self, node: Node) -> Token:
+        return next(filter(None, map(self.visit, node.children)))
+
+    def visit_parameter_value(self, node: Node) -> Token | QuotedString:
+        return next(filter(None, map(self.visit, node.children)))
+
+
+class ParametersVisitor(NodeVisitor):
+    visit_parameter = ParameterVisitor()
+
+    def visit_parameters(self, node: Node) -> list[Parameter]:
+        return list(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/product.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.comment as comment
+import http_fields.visitors.rfc9110.token as token
+
+Token = token.Token
+TokenVisitor = token.TokenVisitor
+
+
+__all__ = ["Product", "ProductVisitor"]
+
+
+@dataclass(frozen=True)
+class Product:
+    name: Token
+    version: Token | None
+
+    def __init__(self, name: str, version: str | None = None):
+        object.__setattr__(self, "name", Token(name))
+        object.__setattr__(self, "version", Token(version) if version else None)
+
+    def __str__(self):
+        return str(self.name) + (f"/{self.version}" if self.version else "")
+
+
+class ProductVisitor(NodeVisitor):
+    visit_comment = comment.CommentVisitor()
+    visit_token = TokenVisitor()
+
+    def visit_product(self, node: Node):
+        items = filter(None, map(self.visit, node.children))
+        name = next(items)
+        version = next(items, None)
+        return Product(name, version)
+
+    def visit_product_version(self, node: Node) -> Token:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/quotedstring.py

@@ -0,0 +1,66 @@
+from abnf import LiteralNode, Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+from http_fields.parsedobjs import 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 9110 quoted-string.
+    A QuotedString can be created either double-quoted or not; the result will be a double-quoted
+    string, escaped as needed."""
+
+    parser = rfc9110.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 RFC 9110 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

http_fields/visitors/rfc9110/range.py

@@ -0,0 +1,100 @@
+from dataclasses import dataclass
+
+from abnf import Node, NodeVisitor
+
+from http_fields.parsedobjs import NonNegativeInt
+from http_fields.visitors.rfc9110.rangeunit import RangeUnit
+
+__all__ = ["IntRange", "RangeVisitor", "SuffixRange"]
+
+
+@dataclass(frozen=True)
+class IntRange:
+    """An RFC 9110 int-range, e.g. ``0-499`` or ``500-`` (open-ended)."""
+
+    first_pos: NonNegativeInt
+    last_pos: NonNegativeInt | None = None
+
+    def __init__(self, first_pos: int, last_pos: int | None = None) -> None:
+        first = NonNegativeInt(first_pos)
+        last = None if last_pos is None else NonNegativeInt(last_pos)
+        if last is not None and last < first:
+            # RFC 9110 section 14.1.2: an int-range with last-pos < first-pos is invalid.
+            raise ValueError("last-pos must not be less than first-pos.")
+        object.__setattr__(self, "first_pos", first)
+        object.__setattr__(self, "last_pos", last)
+
+    def __str__(self) -> str:
+        last = "" if self.last_pos is None else str(self.last_pos)
+        return f"{self.first_pos}-{last}"
+
+
+@dataclass(frozen=True)
+class SuffixRange:
+    """An RFC 9110 suffix-range, e.g. ``-500`` (the final N units)."""
+
+    suffix_length: NonNegativeInt
+
+    def __init__(self, suffix_length: int) -> None:
+        object.__setattr__(self, "suffix_length", NonNegativeInt(suffix_length))
+
+    def __str__(self) -> str:
+        return f"-{self.suffix_length}"
+
+
+class RangeVisitor(NodeVisitor):
+    @staticmethod
+    def visit_range_unit(node: Node) -> RangeUnit:
+        return RangeUnit(node.value, parse=False)
+
+    @staticmethod
+    def visit_first_pos(node: Node) -> NonNegativeInt:
+        return NonNegativeInt(node.value)
+
+    @staticmethod
+    def visit_last_pos(node: Node) -> NonNegativeInt:
+        return NonNegativeInt(node.value)
+
+    @staticmethod
+    def visit_suffix_length(node: Node) -> NonNegativeInt:
+        return NonNegativeInt(node.value)
+
+    def visit_int_range(self, node: Node) -> IntRange:
+        items = [x for x in map(self.visit, node.children) if x is not None]
+        return IntRange(items[0], items[1] if len(items) == 2 else None)
+
+    def visit_suffix_range(self, node: Node) -> SuffixRange:
+        items = [x for x in map(self.visit, node.children) if x is not None]
+        return SuffixRange(items[0])
+
+    def visit_range_spec(self, node: Node) -> IntRange | SuffixRange:
+        # range-spec is int-range / suffix-range / other-range. This model only
+        # represents byte ranges, so reject other-range explicitly rather than
+        # letting it drop out silently (it visits to None).
+        result = self.visit(node.children[0])
+        if not isinstance(result, (IntRange, SuffixRange)):
+            raise ValueError("Unsupported range-spec (other-range).")
+        return result
+
+    def visit_range_set(self, node: Node) -> list[IntRange | SuffixRange]:
+        return [
+            x
+            for x in map(self.visit, node.children)
+            if isinstance(x, (IntRange, SuffixRange))
+        ]
+
+    def visit_ranges_specifier(
+        self, node: Node
+    ) -> tuple[RangeUnit, list[IntRange | SuffixRange]]:
+        range_unit = RangeUnit("bytes", parse=False)
+        ranges: list[IntRange | SuffixRange] = []
+        for child in node.children:
+            result = self.visit(child)
+            if isinstance(result, RangeUnit):
+                range_unit = result
+            elif isinstance(result, list):
+                ranges = result
+        return (range_unit, ranges)
+
+    def visit_range(self, node: Node) -> tuple[RangeUnit, list[IntRange | SuffixRange]]:
+        return next(filter(None, map(self.visit, node.children)))

http_fields/visitors/rfc9110/rangeunit.py

@@ -0,0 +1,17 @@
+from abnf import Node, NodeVisitor
+from abnf.grammars import rfc9110
+
+import http_fields.visitors.rfc9110.token as token
+from http_fields.parsedobjs import CaselessMixin, ParsedStr
+
+
+class RangeUnit(CaselessMixin, ParsedStr):
+    parser = rfc9110.Rule("range-unit")
+
+
+class RangeUnitVisitor(NodeVisitor):
+    visit_token = token.TokenVisitor()
+
+    def visit_range_unit(self, node: Node):
+        item = next(filter(None, map(self.visit, node.children)))
+        return RangeUnit(item, parse=False)

http_fields/visitors/rfc9110/retryafter.py

@@ -0,0 +1,20 @@
+from datetime import datetime
+
+from abnf import Node, NodeVisitor
+
+import http_fields.visitors.rfc9110.httpdate as httpdate
+
+
+class RetryAfterVisitor(NodeVisitor):
+    """NodeVisitor subclass for retry-after."""
+
+    visit_http_date = httpdate.HttpDateVisitor()
+
+    def visit_retry_after(self, node: Node) -> datetime | int:
+        return self.visit(node.children[0])
+
+    @staticmethod
+    def visit_delay_seconds(node: Node) -> int:
+        delay_seconds = int(node.value)
+        assert delay_seconds >= 0  # if not, there is a parser issue.
+        return delay_seconds

http_fields/visitors/rfc9110/server.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__ = ["ServerVisitor"]
+
+
+class ServerVisitor(NodeVisitor):
+    visit_comment = comment.CommentVisitor()
+    visit_product = product.ProductVisitor()
+    visit_token = token.TokenVisitor()
+
+    def visit_server(self, node: Node) -> list[product.Product | comment.Comment]:
+        return list(filter(None, map(self.visit, node.children)))