ref-id 0.7.0__py3-none-any.whl

ref_id/grammar.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Compiles every pattern the specification declares through this dialect's declared adaptations, and
+holds the only structural literals this package writes.
+
+Ported from `crates/ref-id/src/grammar.rs`.
+"""
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from .errors import SpecVersionError
+
+if TYPE_CHECKING:
+    from .spec import Spec
+
+__all__: list[str] = []
+
+# The dialect this port compiles for. Its adaptation list, when the spec declares one, is applied to
+# every pattern.
+_DIALECT = "python-re"
+
+# The structural literals of the scheme, each written exactly once, here. Their sources are
+# `spec.grammar.expression` (the field separator, the fragment introducer, the line breaks the character
+# classes exclude) and the two pair grammars (the key/value separator).
+FIELD = ":"
+FRAGMENT_INTRODUCER = "#"
+PAIR = "="
+LINE_BREAKS = ("\r", "\n")
+
+
+def scheme_prefix(spec: Spec) -> str:
+    return f"{spec.scheme()}{FIELD}"
+
+
+def _assert_structure(spec: Spec) -> None:
+    expression = spec.grammar_expression()
+    for literal in (f"^{scheme_prefix(spec)}", FRAGMENT_INTRODUCER, "\\r", "\\n"):
+        if literal not in expression:
+            raise SpecVersionError(f"spec.grammar.expression does not carry {literal!r}; this package's structural literals do not match")
+    for pair in (spec.get_str("grammar", "state", "pair"), spec.get_str("grammar", "fragment", "pair")):
+        if f"){PAIR}(" not in pair:
+            raise SpecVersionError(f"a pair grammar does not separate key and value with {PAIR!r}; this package's structural literals do not match")
+
+
+def compile_pattern(spec: Spec, pattern: str) -> re.Pattern[str]:
+    """Applies this dialect's declared adaptations — the replace pairs in order, then an `anchor` in place of
+    the `$` that ends the pattern — then compiles."""
+    adapted = pattern
+    replacements = spec.value("grammar", "adaptations", _DIALECT, "replace") or []
+    for pair in replacements:
+        if not (isinstance(pair, list) and len(pair) == 2):
+            continue
+        source, target = pair
+        if isinstance(source, str) and isinstance(target, str):
+            adapted = adapted.replace(source, target)
+    anchor = spec.value("grammar", "adaptations", _DIALECT, "anchor")
+    if isinstance(anchor, str) and adapted.endswith("$"):
+        adapted = adapted[:-1] + anchor
+    try:
+        return re.compile(adapted)
+    except re.error as error:
+        raise SpecVersionError(f"pattern {pattern} does not compile in {_DIALECT}: {error}") from error
+
+
+class Grammar:
+    """The compiled patterns every parse and build step needs, plus a lazily-compiled cache for every
+    other pattern the specification declares (a form, a dispatch entry, a refinement)."""
+
+    def __init__(self, top: re.Pattern[str], state_pair: re.Pattern[str], fragment_pair: re.Pattern[str]) -> None:
+        self.top = top
+        self.state_pair = state_pair
+        self.fragment_pair = fragment_pair
+        self._others: dict[str, re.Pattern[str]] = {}
+
+    @classmethod
+    def compile_for(cls, spec: Spec) -> Grammar:
+        _assert_structure(spec)
+        return cls(
+            top=compile_pattern(spec, spec.grammar_expression()),
+            state_pair=compile_pattern(spec, spec.get_str("grammar", "state", "pair")),
+            fragment_pair=compile_pattern(spec, spec.get_str("grammar", "fragment", "pair")),
+        )
+
+    def matches(self, spec: Spec, source: str, value: str) -> bool:
+        """Whether any other pattern the spec declares (a form, a dispatch entry, a refinement) matches
+        the whole value."""
+        compiled = self._others.get(source)
+        if compiled is None:
+            compiled = compile_pattern(spec, source)
+            self._others[source] = compiled
+        return compiled.fullmatch(value) is not None

ref_id/parse.py

@@ -0,0 +1,236 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Decomposes a `ref:` identifier string against the loaded spec. Order, and the precedence it
+produces: grammar -> version -> state and fragment decomposition, including the repeated-key policy ->
+(unsupported version stops here, decomposed and unvalidated) -> the two sides must not trade keys ->
+qualifier values against their forms -> refinement values against their patterns and range constraints ->
+dispatch: unknown type is `uncovered`, else the locator goes to its validator.
+
+Ported from `crates/ref-id/src/parse.rs`.
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any
+
+from .encoding import decode, strictly_encoded, table_for
+from .grammar import Grammar, scheme_prefix
+from .spec import Spec, load_spec
+from .types import Fragment, ParseResult
+from .validators import (
+    assert_implemented,
+    delegated_string,
+    range_holds,
+    validate_locator,
+)
+
+__all__ = ["parse"]
+
+
+def _bounded_int(text: str, maximum: int) -> int:
+    """A digit-only literal capped at `maximum`, without ever handing CPython's `int()` a literal longer
+    than `maximum` itself can be — which keeps this independent of `sys.get_int_max_str_digits()`. Leading
+    zeros are stripped first (`"007"` and `"7"` must compare the same); a literal whose stripped digit
+    count exceeds `str(maximum)`'s is above `maximum` on digit count alone, so it is never converted.
+    Whatever survives to `int()` is no longer than `maximum`'s own digit count, which is always small."""
+    stripped = text.lstrip("0") or "0"
+    if len(stripped) > len(str(maximum)):
+        return maximum
+    return min(int(stripped), maximum)
+
+
+class _Parser:
+    def __init__(self, spec: Spec, grammar: Grammar) -> None:
+        self.spec = spec
+        self.grammar = grammar
+
+    def _malformed(self, input_: str, part: str, head: ParseResult | None) -> ParseResult:
+        return self._malformed_at(input_, self.spec.part(part), head)
+
+    def _malformed_at(self, input_: str, part: str, head: ParseResult | None) -> ParseResult:
+        """Malformed at a key the identifier itself carries — reported verbatim, not checked against the
+        vocabulary this package names, because an undeclared key is carried through by policy."""
+        base = head if head is not None else ParseResult(
+            input="",
+            status="",
+            version=self.spec.get_int("version", "default"),
+            explicit_version=False,
+            type="",
+            locator="",
+        )
+        return replace(
+            base,
+            input=input_,
+            status=self.spec.status("malformed"),
+            delegated=None,
+            canonical=None,
+            nested=None,
+            part=part,
+        )
+
+    def _pairs(self, pattern: Any, segments: list[str], failed_part: str) -> tuple[str, Any]:
+        """Splits `key=value` segments with the given pair grammar; a repeated key is malformed at that
+        key. Returns `("ok", tuple[Pair, ...])`, `("failed", part)` or `("repeated", key)`."""
+        out: list[tuple[str, str]] = []
+        seen: set[str] = set()
+        for segment in segments:
+            match = pattern.fullmatch(segment)
+            if match is None:
+                return "failed", failed_part
+            key = match.group("key") or ""
+            if key in seen:
+                return "repeated", key
+            seen.add(key)
+            out.append((key, match.group("value") or ""))
+        return "ok", tuple(out)
+
+    def _state(self, raw: str) -> tuple[str, Any]:
+        segments = raw.split(self.spec.get_str("grammar", "state", "separator"))
+        return self._pairs(self.grammar.state_pair, segments, "state")
+
+    def _fragment(self, raw: str) -> tuple[str, Any]:
+        segments = raw.split(self.spec.get_str("grammar", "fragment", "separator"))
+        path = segments[0] if segments else ""
+        if not path:
+            return "failed", "fragment"
+        kind, value = self._pairs(self.grammar.fragment_pair, segments[1:], "fragment")
+        if kind == "ok":
+            return "ok", Fragment(path=path, refinements=value)
+        return kind, value
+
+    def _try_nested(self, form: dict[str, Any], value: str, depth: int) -> str | None:
+        """A qualifier value that nests an identifier: strictly encoded, decoded with the form's table,
+        parsed one level down."""
+        max_depth = form.get("depth", 0)
+        if not isinstance(max_depth, int) or depth >= max_depth or not value.startswith(scheme_prefix(self.spec)):
+            return None
+        table = table_for(self.spec, form)
+        if not strictly_encoded(value, table):
+            return None
+        decoded = decode(value, table)
+        inner = self.parse(decoded, depth + 1)
+        return None if inner.status == self.spec.status("malformed") else decoded
+
+    def _match_forms(self, names: list[str], value: str, depth: int) -> tuple[bool, str | None]:
+        forms = self.spec.get_object("forms") or {}
+        for name in names:
+            form = forms.get(name)
+            if not isinstance(form, dict):
+                continue
+            if form.get("nested") is True:
+                nested = self._try_nested(form, value, depth)
+                if nested is not None:
+                    return True, nested
+                continue
+            pattern = form.get("pattern")
+            if isinstance(pattern, str) and self.grammar.matches(self.spec, pattern, value):
+                return True, None
+        return False, None
+
+    def parse(self, input_: str, depth: int) -> ParseResult:
+        match = self.grammar.top.fullmatch(input_)
+        if match is None:
+            return self._malformed(input_, "grammar", None)
+
+        def opt(name: str) -> str | None:
+            return match.groupdict().get(name)
+
+        version_text = opt("version")
+        type_ = opt("type") or ""
+        locator = opt("locator") or ""
+        explicit_version = version_text is not None
+        # `[0-9]+` guarantees a digit-only literal, but `int()` on one long enough hits CPython's
+        # int-conversion digit-count guard (`sys.get_int_max_str_digits()`, 4300 by default and settable
+        # as low as 640) — a literal that long is already far above `version.maximum`, so `_bounded_int`
+        # decides by digit count before ever converting; `versionText` below keeps the literal exactly as
+        # written regardless.
+        version = self.spec.get_int("version", "default")
+        if version_text is not None:
+            maximum = self.spec.get_int("version", "maximum")
+            version = _bounded_int(version_text, maximum)
+
+        head = ParseResult(
+            input=input_,
+            status="",
+            version=version,
+            explicit_version=explicit_version,
+            type=type_,
+            locator=locator,
+            version_text=version_text,
+        )
+
+        state_raw = opt("state")
+        if state_raw is not None:
+            kind, value = self._state(state_raw)
+            if kind == "failed":
+                return self._malformed(input_, value, head)
+            if kind == "repeated":
+                return self._malformed_at(input_, value, head)
+            head = replace(head, qualifiers=value)
+
+        fragment_raw = opt("fragment")
+        if fragment_raw is not None:
+            kind, value = self._fragment(fragment_raw)
+            if kind == "failed":
+                return self._malformed(input_, value, head)
+            if kind == "repeated":
+                return self._malformed_at(input_, value, head)
+            head = replace(head, fragment=value)
+
+        base = replace(head, status=self.spec.status("ok"), delegated=delegated_string(self.spec, type_, locator))
+
+        if version not in self.spec.get_ints("version", "supported"):
+            return replace(base, status=self.spec.status("unsupported"))
+
+        refinements_table = self.spec.get_object("refinements") or {}
+        qualifiers_table = self.spec.get_object("qualifiers") or {}
+        for key, _value in head.qualifiers:
+            if key in refinements_table:
+                return self._malformed(input_, key, head)
+        if head.fragment is not None:
+            for key, _value in head.fragment.refinements:
+                if key in qualifiers_table:
+                    return self._malformed(input_, key, head)
+
+        nested: list[tuple[str, str]] = []
+        for key, value in head.qualifiers:
+            declared = qualifiers_table.get(key)
+            if not isinstance(declared, dict):
+                continue  # unknownKey: carry-through
+            forms = [name for name in declared.get("forms", []) if isinstance(name, str)]
+            matches, inner = self._match_forms(forms, value, depth)
+            if not matches:
+                return self._malformed(input_, key, head)
+            if inner is not None:
+                nested.append((key, inner))
+        if nested:
+            base = replace(base, nested=tuple(nested))
+
+        if head.fragment is not None:
+            for key, value in head.fragment.refinements:
+                declared = refinements_table.get(key)
+                if not isinstance(declared, dict):
+                    continue  # unknownRefinement: carry-through
+                pattern = declared.get("pattern", "")
+                if not self.grammar.matches(self.spec, pattern, value) or not range_holds(self.spec, declared, value):
+                    return self._malformed(input_, key, head)
+
+        dispatch = self.spec.get_object("dispatch") or {}
+        entry = dispatch.get(type_)
+        if not isinstance(entry, dict) or base.delegated is None:
+            return replace(base, status=self.spec.unknown_type())
+        validation = validate_locator(self.spec, entry, base.delegated)
+        if validation is None:
+            return replace(base, status=self.spec.unknown_type())
+        if not validation.ok:
+            return self._malformed(input_, "locator", head)
+        return replace(base, canonical=validation.canonical)
+
+
+def parse(input_: str, /) -> ParseResult:
+    """Parses a `ref:` identifier string against the embedded spec. Never raises for an identifier
+    problem; it raises only when the embedded specification itself cannot be honoured."""
+    if not isinstance(input_, str):
+        raise TypeError("parse() takes a string")
+    spec = load_spec()
+    assert_implemented(spec)
+    return _Parser(spec, spec.grammar()).parse(input_, 0)