ref-id 0.7.0__py3-none-any.whl

ref_id/spec/ref-id.json.sha256

@@ -0,0 +1 @@
+09a3a83486d77192e925b77f68826fa451d44006cdf5be0ef4bb2f19bda0e175

ref_id/spec.py

@@ -0,0 +1,192 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Loads the embedded `spec/ref-id.json`, verifies its digest against the sidecar, and checks the
+`specVersion` major. The specification's own data is never restated here: it is read dynamically from
+the parsed JSON through the accessors below.
+
+Ported from `crates/ref-id/src/spec.rs`.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from importlib import resources
+from typing import TYPE_CHECKING, Any
+
+from .canonical import canonicalise
+from .errors import SpecIntegrityError, SpecVersionError
+
+if TYPE_CHECKING:
+    from .grammar import Grammar
+
+__all__ = ["Spec", "embedded_spec_text", "load_spec", "load_spec_from"]
+
+# The major version this package was built against. Not spec data — the package's own contract.
+_SUPPORTED_SPEC_MAJOR = "1"
+
+
+class Spec:
+    """The `ref:` specification, read dynamically. Every table the code consults is looked up here."""
+
+    def __init__(self, root: dict[str, Any]) -> None:
+        self._root = root
+        self._grammar: Grammar | None = None
+
+    def value(self, *path: str) -> Any | None:
+        current: Any = self._root
+        for key in path:
+            if not isinstance(current, dict) or key not in current:
+                return None
+            current = current[key]
+        return current
+
+    def get_str(self, *path: str) -> str:
+        value = self.value(*path)
+        return value if isinstance(value, str) else ""
+
+    def get_int(self, *path: str) -> int:
+        value = self.value(*path)
+        return value if isinstance(value, int) and not isinstance(value, bool) else 0
+
+    def get_strings(self, *path: str) -> list[str]:
+        value = self.value(*path)
+        if not isinstance(value, list):
+            return []
+        return [item for item in value if isinstance(item, str)]
+
+    def get_object(self, *path: str) -> dict[str, Any] | None:
+        value = self.value(*path)
+        return value if isinstance(value, dict) else None
+
+    def get_ints(self, *path: str) -> list[int]:
+        value = self.value(*path)
+        if not isinstance(value, list):
+            return []
+        return [item for item in value if isinstance(item, int) and not isinstance(item, bool)]
+
+    def pointer(self, pointer: str, /) -> Any | None:
+        """Resolves a JSON Pointer (RFC 6901) against the raw document — `refinements.lines.maximum`
+        declares `"/version/maximum"` rather than a literal, so a refinement's bound is read from wherever
+        it points instead of being assumed to be one fixed key."""
+        if pointer == "":
+            return self._root
+        if not pointer.startswith("/"):
+            return None
+        segments = [segment.replace("~1", "/").replace("~0", "~") for segment in pointer[1:].split("/")]
+        return self.value(*segments)
+
+    def get_table(self, *path: str) -> list[tuple[str, str]]:
+        obj = self.get_object(*path)
+        if obj is None:
+            return []
+        return [(key, value) for key, value in obj.items() if isinstance(value, str)]
+
+    def spec_version(self) -> str:
+        return self.get_str("specVersion")
+
+    def scheme(self) -> str:
+        return self.get_str("scheme")
+
+    def unknown_type(self) -> str:
+        return self.get_str("unknownType")
+
+    def status(self, name: str) -> str:
+        """A status name this code needs, checked against the vocabulary the spec declares."""
+        if name in self.get_strings("statuses"):
+            return name
+        raise SpecVersionError(f'this package names the status "{name}", which spec {self.spec_version()} does not declare')
+
+    def part(self, name: str) -> str:
+        """A part name this code needs: one of `spec.parts`, or a declared qualifier or refinement key."""
+        qualifiers = self.get_object("qualifiers") or {}
+        refinements = self.get_object("refinements") or {}
+        if name in self.get_strings("parts") or name in qualifiers or name in refinements:
+            return name
+        raise SpecVersionError(f'this package names the part "{name}", which spec {self.spec_version()} does not declare')
+
+    def vectors(self, group: str) -> list[Any]:
+        """The vectors of one group, for a conformance runner."""
+        value = self.value("vectors", group)
+        return value if isinstance(value, list) else []
+
+    def vector_classes(self) -> list[str]:
+        """Every vector group name `spec.vectors` declares, so a runner can prove it executes all of them."""
+        groups = self.get_object("vectors") or {}
+        return list(groups.keys())
+
+    def grammar_expression(self) -> str:
+        """The canonical grammar expression, for a dialect measurement."""
+        return self.get_str("grammar", "expression")
+
+    def grammar(self) -> Grammar:
+        """The patterns this spec compiles to, lazily compiled and cached — every reader shares one
+        instance per loaded spec."""
+        from .grammar import Grammar
+
+        if self._grammar is None:
+            self._grammar = Grammar.compile_for(self)
+        return self._grammar
+
+
+def _validate(text: str, sidecar: str) -> Spec:
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError as error:
+        raise SpecIntegrityError(f"spec/ref-id.json is not JSON: {error}") from error
+    except (ValueError, RecursionError) as error:
+        # `json.loads` itself converts a number literal to `int`/`float` and recurses per nesting level:
+        # a literal long enough hits CPython's int-conversion digit-count guard (`ValueError`, not
+        # `json.JSONDecodeError`), and nesting deep enough hits its call-stack limit (`RecursionError`).
+        # Both are the document's shape being unreadable, reported the same way as malformed JSON rather
+        # than surfacing CPython's own exception kinds to a caller who would have to know to expect them.
+        raise SpecIntegrityError(f"spec/ref-id.json cannot be parsed: {error}") from error
+    canonical = canonicalise(parsed)
+    computed = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    expected = sidecar.strip()
+    if computed != expected:
+        raise SpecIntegrityError(f"spec/ref-id.json does not match its sidecar digest (expected {expected}, computed {computed})")
+    spec = Spec(parsed)
+    major = spec.spec_version().split(".")[0]
+    if major != _SUPPORTED_SPEC_MAJOR:
+        raise SpecVersionError(f"spec/ref-id.json declares specVersion {spec.spec_version()}; this package supports major {_SUPPORTED_SPEC_MAJOR}")
+    return spec
+
+
+def load_spec_from(directory: str | os.PathLike[str], /) -> Spec:
+    """Loads and validates a spec + sidecar pair from a directory; the integrity tests use this."""
+    directory = os.fspath(directory)
+    try:
+        with open(os.path.join(directory, "ref-id.json"), encoding="utf-8") as handle:
+            text = handle.read()
+        with open(os.path.join(directory, "ref-id.json.sha256"), encoding="utf-8") as handle:
+            sidecar = handle.read()
+    except (OSError, UnicodeDecodeError) as error:
+        # A missing file or directory raises `OSError`; a file that is not valid UTF-8 raises
+        # `UnicodeDecodeError` from `handle.read()` — neither belongs on a caller who was promised
+        # `SpecIntegrityError` for every way this pair can fail to be the specification it claims to be.
+        raise SpecIntegrityError(str(error)) from error
+    return _validate(text, sidecar)
+
+
+def embedded_spec_text() -> tuple[str, str]:
+    """The embedded specification's bytes, so a runner can prove them byte-identical to the repository's file."""
+    # `ref_id.spec` carries no `__init__.py` of its own — it is a byte-identical copy of `spec/`, not a
+    # subpackage — so the anchor is `ref_id` and `spec/` is addressed as a resource path under it.
+    # `Traversable.read_text` opens in text mode, which performs universal-newline translation; the
+    # digest covers the file's actual bytes, so this reads them raw and decodes them itself instead.
+    package = resources.files("ref_id").joinpath("spec")
+    json_text = package.joinpath("ref-id.json").read_bytes().decode("utf-8")
+    sidecar_text = package.joinpath("ref-id.json.sha256").read_bytes().decode("utf-8")
+    return json_text, sidecar_text
+
+
+_CACHED: Spec | None = None
+
+
+def load_spec() -> Spec:
+    """The validated spec this package embeds, loaded once."""
+    global _CACHED
+    if _CACHED is None:
+        json_text, sidecar_text = embedded_spec_text()
+        _CACHED = _validate(json_text, sidecar_text)
+    return _CACHED

ref_id/types.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The value types `parse`, `serialise`, `build` and `validate_envelope` exchange — frozen, slotted
+dataclasses with snake_case attributes. `to_json()` on `ParseResult` and `EnvelopeResult` returns the
+`openRPC` keys exactly (camelCase, optional keys omitted when unset); `BuildParts.from_json` reads the
+vector shape.
+
+Ported from `crates/ref-id/src/types.rs`.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .errors import BuildError
+
+__all__ = [
+    "BuildParts",
+    "EnvelopeResult",
+    "Fragment",
+    "NestedValue",
+    "ParseResult",
+    "QualifierRelation",
+    "RelateResult",
+    "Relation",
+    "VerdictContent",
+    "VerdictDecidedBy",
+    "VerdictIdentity",
+    "VerdictResult",
+]
+
+Pair = tuple[str, str]
+
+# `comparison.relate.relations` — one relation between two identifiers in one dimension.
+Relation = Literal["equal", "covers", "coveredBy", "differ"]
+
+# `comparison.verdict.axes.identity` and `.content`.
+VerdictIdentity = Literal["same", "covers", "coveredBy", "distinct", "undetermined"]
+VerdictContent = Literal["same", "different", "unknown"]
+
+
+def _pairs_json(pairs: tuple[Pair, ...]) -> list[list[str]]:
+    return [[key, value] for key, value in pairs]
+
+
+@dataclass(frozen=True, slots=True)
+class Fragment:
+    """The `#path;refinements` a parsed identifier carries, or the parts a producer hands `build`."""
+
+    path: str
+    refinements: tuple[Pair, ...] = ()
+
+    def to_json(self) -> dict[str, Any]:
+        return {"path": self.path, "refinements": _pairs_json(self.refinements)}
+
+
+@dataclass(frozen=True, slots=True)
+class NestedValue:
+    """`BuildParts`' `{"nested": <identifier>}` qualifier value."""
+
+    nested: str
+
+
+# The value a `BuildParts` qualifier carries: a plain string, or a nested identifier not yet encoded.
+QualifierValue = str | NestedValue
+
+# The fragment a producer hands `build`: a bare path, or the path with its refinements.
+FragmentParts = str | Fragment
+
+
+@dataclass(frozen=True, slots=True)
+class ParseResult:
+    """What `parse()` returns. `status` is one of `spec.statuses`; `part` one of `spec.parts` on
+    `malformed`."""
+
+    input: str
+    status: str
+    version: int
+    explicit_version: bool
+    type: str
+    locator: str
+    qualifiers: tuple[Pair, ...] = ()
+    fragment: Fragment | None = None
+    version_text: str | None = None
+    delegated: str | None = None
+    canonical: str | None = None
+    nested: tuple[Pair, ...] | None = None
+    part: str | None = None
+
+    def to_json(self) -> dict[str, Any]:
+        """The result as the JSON shape the specification's vectors describe — what a conformance test
+        compares."""
+        out: dict[str, Any] = {
+            "input": self.input,
+            "status": self.status,
+            "version": self.version,
+            "explicitVersion": self.explicit_version,
+            "type": self.type,
+            "locator": self.locator,
+            "qualifiers": _pairs_json(self.qualifiers),
+            "fragment": self.fragment.to_json() if self.fragment is not None else None,
+        }
+        if self.version_text is not None:
+            out["versionText"] = self.version_text
+        if self.delegated is not None:
+            out["delegated"] = self.delegated
+        if self.canonical is not None:
+            out["canonical"] = self.canonical
+        if self.nested is not None:
+            out["nested"] = {key: value for key, value in self.nested}
+        if self.part is not None:
+            out["part"] = self.part
+        return out
+
+
+def _refusal(part: str, why: str) -> BuildError:
+    """A `BuildError` whose part the specification names, through the same path `build()` refuses by."""
+    from .build import _refuse
+    from .spec import load_spec
+
+    return _refuse(load_spec(), part, why)
+
+
+@dataclass(frozen=True, slots=True)
+class BuildParts:
+    """What `build()` takes. `location` never reaches the identifier, so it is read by `from_json` and
+    discarded rather than carried as a field."""
+
+    type: str
+    locator: str
+    qualifiers: tuple[tuple[str, QualifierValue], ...] = ()
+    fragment: FragmentParts | None = None
+
+    @classmethod
+    def from_json(cls, obj: Mapping[str, Any], /) -> BuildParts:
+        """Reads the vector shape: `qualifiers` a list of `[key, value]` pairs whose value is a string or
+        `{"nested": <identifier>}`; `fragment` a string or `{path, refinements}`. A shape this cannot
+        read raises `BuildError` naming the part, never `IndexError`/`KeyError`/`TypeError` — the same
+        kind `build()` itself raises for a badly typed part (`crates/ref-id/src/build.rs` has no
+        equivalent step; the TypeScript reference takes the JSON shape directly as `BuildParts`, so this
+        naming is this port's own)."""
+        type_ = obj.get("type")
+        if not isinstance(type_, str):
+            raise _refusal("type", "parts must have a string type")
+        locator = obj.get("locator")
+        if not isinstance(locator, str):
+            raise _refusal("locator", "parts must have a string locator")
+
+        qualifiers: list[tuple[str, QualifierValue]] = []
+        for pair in obj.get("qualifiers", []):
+            if not isinstance(pair, (list, tuple)) or len(pair) != 2 or not isinstance(pair[0], str):
+                raise _refusal("state", "a qualifier is a [key, value] pair with a string key")
+            key, raw_value = pair[0], pair[1]
+            value: QualifierValue
+            if isinstance(raw_value, str):
+                value = raw_value
+            elif isinstance(raw_value, Mapping) and "nested" in raw_value:
+                # `build()` raises `BuildError` at this same key if `nested` is not a string.
+                value = NestedValue(raw_value["nested"])
+            else:
+                raise _refusal(key, 'a qualifier value is a string or {"nested": string}')
+            qualifiers.append((key, value))
+
+        fragment_json = obj.get("fragment")
+        fragment: FragmentParts | None
+        if fragment_json is None:
+            fragment = None
+        elif isinstance(fragment_json, str):
+            fragment = fragment_json
+        elif isinstance(fragment_json, Mapping) and isinstance(fragment_json.get("path"), str):
+            refinements = tuple((pair[0], pair[1]) for pair in fragment_json.get("refinements", []))
+            fragment = Fragment(path=fragment_json["path"], refinements=refinements)
+        else:
+            raise _refusal("fragment", "a fragment is a string or {path, refinements}")
+
+        return cls(
+            type=type_,
+            locator=locator,
+            qualifiers=tuple(qualifiers),
+            fragment=fragment,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class EnvelopeResult:
+    """Whether an envelope is admissible for the identifier it was requested under."""
+
+    admissible: bool
+    reason: str | None = None
+
+    def to_json(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"admissible": self.admissible}
+        if self.reason is not None:
+            out["reason"] = self.reason
+        return out
+
+
+@dataclass(frozen=True, slots=True)
+class QualifierRelation:
+    """One qualifier member of a `RelateResult`: its own relation, and — only where both sides' values are
+    a nested `ref:` identifier this operation accepts — the nested pair's own `RelateResult`."""
+
+    relation: Relation
+    nested: RelateResult | None = None
+
+    def to_json(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"relation": self.relation}
+        if self.nested is not None:
+            out["nested"] = self.nested.to_json()
+        return out
+
+
+@dataclass(frozen=True, slots=True)
+class RelateResult:
+    """What `relate()` returns for a pair it accepts — `comparison.relate.result`: the five fixed
+    dimensions always, and a keyed dimension (`fragment_refinements`, `qualifiers`) only for the keys at
+    least one side declares."""
+
+    type: Relation
+    version: Relation
+    locator_stem: Relation
+    locator_version: Relation
+    fragment_path: Relation
+    fragment_refinements: tuple[tuple[str, Relation], ...] = ()
+    qualifiers: tuple[tuple[str, QualifierRelation], ...] = ()
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "type": self.type,
+            "version": self.version,
+            "locatorStem": self.locator_stem,
+            "locatorVersion": self.locator_version,
+            "fragmentPath": self.fragment_path,
+            "fragmentRefinements": {key: value for key, value in self.fragment_refinements},
+            "qualifiers": {key: value.to_json() for key, value in self.qualifiers},
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class VerdictDecidedBy:
+    """Which members of `relate`'s result decided each axis, by their `decidedBy` path —
+    `comparison.verdict.result.decidedBy`."""
+
+    identity: tuple[str, ...] = ()
+    content: tuple[str, ...] = ()
+
+    def to_json(self) -> dict[str, Any]:
+        return {"identity": list(self.identity), "content": list(self.content)}
+
+
+@dataclass(frozen=True, slots=True)
+class VerdictResult:
+    """What `verdict()` returns for a pair `relate` accepts — `comparison.verdict.result`."""
+
+    identity: VerdictIdentity
+    content: VerdictContent
+    decided_by: VerdictDecidedBy
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "identity": self.identity,
+            "content": self.content,
+            "decidedBy": self.decided_by.to_json(),
+        }