sci-protocol 0.2.0__py3-none-any.whl

pysci/errors.py

@@ -0,0 +1,204 @@
+"""Outcome vocabulary, structured issues, and the exception hierarchy.
+
+Every check in the library reports failures as :class:`Issue` records so that
+callers (such as the CLI) can show the file or field, the violated
+requirement, and the observed value. Fail-fast parsers raise a
+:class:`SciError` subclass carrying the issues; collecting validators return
+lists of issues.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+__all__ = [
+    "Incomplete",
+    "Invalid",
+    "Issue",
+    "IssueCollector",
+    "Outcome",
+    "SciError",
+    "Unsupported",
+    "observed_repr",
+    "raise_for",
+]
+
+
+class Outcome(StrEnum):
+    """Verification outcome (protocol §6)."""
+
+    VALID = "valid"
+    """The requested checks succeeded."""
+    INVALID = "invalid"
+    """A required format, signature, binding, or association check failed."""
+    UNSUPPORTED = "unsupported"
+    """The ``schema`` string identifies no supported schema."""
+    INCOMPLETE = "incomplete"
+    """Unavailable evidence or a local resource limit prevented the checks."""
+
+
+def observed_repr(value: object, limit: int = 120) -> str:
+    """Return a short, printable representation of an observed value."""
+    text = repr(value)
+    if len(text) > limit:
+        text = text[: limit - 3] + "..."
+    return text
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    """One failed requirement.
+
+    Attributes:
+        code: Stable machine-readable identifier, e.g. ``"text_not_assignable"``.
+        requirement: Human-readable statement of the violated requirement.
+        section: Protocol section, e.g. ``"4.2"``.
+        file: Bundle path or artifact the issue concerns, e.g. ``"sci.json"``.
+        field: JSON pointer (RFC 6901) of the offending value inside ``file``.
+        observed: Short representation of the observed value, when useful.
+        outcome: The outcome this issue implies (invalid, unsupported, incomplete).
+    """
+
+    code: str
+    requirement: str
+    section: str | None = None
+    file: str | None = None
+    field: str | None = None
+    observed: str | None = None
+    outcome: Outcome = Outcome.INVALID
+
+    def located(self, *, file: str | None = None, prefix: str | None = None) -> Issue:
+        """Return a copy attributed to ``file`` and/or with a JSON-pointer prefix."""
+        new_field = self.field
+        if prefix is not None:
+            new_field = prefix + (self.field or "")
+        return Issue(
+            code=self.code,
+            requirement=self.requirement,
+            section=self.section,
+            file=file if file is not None else self.file,
+            field=new_field,
+            observed=self.observed,
+            outcome=self.outcome,
+        )
+
+    def __str__(self) -> str:
+        where = ""
+        if self.file:
+            where = self.file
+        if self.field:
+            where += ("#" if where else "") + self.field
+        parts = [f"[{self.code}]"]
+        if where:
+            parts.append(where + ":")
+        parts.append(self.requirement)
+        if self.section:
+            parts.append(f"(§{self.section})")
+        if self.observed is not None:
+            parts.append(f"observed {self.observed}")
+        return " ".join(parts)
+
+
+def _worst(issues: Iterable[Issue]) -> Outcome:
+    outcomes = {issue.outcome for issue in issues}
+    for candidate in (Outcome.UNSUPPORTED, Outcome.INVALID, Outcome.INCOMPLETE):
+        if candidate in outcomes:
+            return candidate
+    return Outcome.VALID
+
+
+class SciError(Exception):
+    """Base class for protocol check failures. Carries one or more issues."""
+
+    default_outcome = Outcome.INVALID
+
+    def __init__(self, issues: Issue | Sequence[Issue]) -> None:
+        self.issues: tuple[Issue, ...] = (issues,) if isinstance(issues, Issue) else tuple(issues)
+        if not self.issues:
+            raise ValueError("SciError requires at least one issue")
+        super().__init__("; ".join(str(issue) for issue in self.issues))
+
+    @property
+    def outcome(self) -> Outcome:
+        return _worst(self.issues)
+
+    @property
+    def issue(self) -> Issue:
+        """The first issue."""
+        return self.issues[0]
+
+
+class Invalid(SciError):
+    """A required check failed."""
+
+
+class Unsupported(SciError):
+    """A schema string identifies no supported schema version."""
+
+    default_outcome = Outcome.UNSUPPORTED
+
+
+class Incomplete(SciError):
+    """Evidence was unavailable or a local limit prevented the check."""
+
+    default_outcome = Outcome.INCOMPLETE
+
+
+def raise_for(issues: Sequence[Issue]) -> None:
+    """Raise the exception class matching the worst issue, if any."""
+    if not issues:
+        return
+    worst = _worst(issues)
+    if worst is Outcome.UNSUPPORTED:
+        raise Unsupported(issues)
+    if worst is Outcome.INCOMPLETE:
+        raise Incomplete(issues)
+    raise Invalid(issues)
+
+
+@dataclass(slots=True)
+class IssueCollector:
+    """Accumulates issues from independent checks."""
+
+    issues: list[Issue] = field(default_factory=list)
+
+    def add(
+        self,
+        code: str,
+        requirement: str,
+        *,
+        section: str | None = None,
+        file: str | None = None,
+        field: str | None = None,
+        observed: object = None,
+        outcome: Outcome = Outcome.INVALID,
+    ) -> None:
+        self.issues.append(
+            Issue(
+                code=code,
+                requirement=requirement,
+                section=section,
+                file=file,
+                field=field,
+                observed=None if observed is None else observed_repr(observed),
+                outcome=outcome,
+            )
+        )
+
+    def extend(self, issues: Iterable[Issue]) -> None:
+        self.issues.extend(issues)
+
+    def __bool__(self) -> bool:
+        return bool(self.issues)
+
+    def __len__(self) -> int:
+        return len(self.issues)
+
+    @property
+    def outcome(self) -> Outcome:
+        return _worst(self.issues)
+
+    def raise_if_any(self) -> None:
+        raise_for(self.issues)

pysci/ids.py

@@ -0,0 +1,61 @@
+"""Publication identifiers (protocol §2, §4.4, §8.1.1)."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Final
+
+__all__ = [
+    "is_digest",
+    "parse_publication_id",
+    "publication_id",
+    "publication_id_from_manifest",
+    "sci_citation_target",
+]
+
+_DIGEST: Final = re.compile(r"[0-9a-f]{64}")
+
+
+def is_digest(value: str) -> bool:
+    """True for exactly 64 lowercase hexadecimal characters."""
+    return _DIGEST.fullmatch(value) is not None
+
+
+def parse_publication_id(value: str, *, allow_bare: bool = False) -> str:
+    """Parse ``sha256:<digest>`` or ``sci:sha256:<digest>``; return the bare digest.
+
+    With ``allow_bare`` a bare 64-character digest (the §8.1.1 ``id`` form) is
+    also accepted. Uppercase hexadecimal is rejected, never normalized.
+
+    Raises:
+        ValueError: the value is not a publication identifier.
+    """
+    for prefix in ("sci:sha256:", "sha256:"):
+        if value.startswith(prefix):
+            digest = value[len(prefix) :]
+            break
+    else:
+        if not allow_bare:
+            raise ValueError("publication IDs use sha256:<64 lowercase hex> or sci:sha256:<...>")
+        digest = value
+    if not is_digest(digest):
+        raise ValueError("publication digest must be 64 lowercase hexadecimal characters")
+    return digest
+
+
+def publication_id(digest: str) -> str:
+    """Format a bare digest as ``sha256:<digest>``."""
+    if not is_digest(digest):
+        raise ValueError("publication digest must be 64 lowercase hexadecimal characters")
+    return "sha256:" + digest
+
+
+def publication_id_from_manifest(manifest_bytes: bytes) -> str:
+    """``sha256:`` identifier of the exact manifest bytes (§2)."""
+    return "sha256:" + hashlib.sha256(manifest_bytes).hexdigest()
+
+
+def sci_citation_target(value: str) -> str:
+    """The ``sci:sha256:<digest>`` citation form of an identifier (§4.4)."""
+    return "sci:sha256:" + parse_publication_id(value, allow_bare=True)

pysci/jsonstrict.py

@@ -0,0 +1,225 @@
+"""Strict JSON decoding under protocol §7.
+
+Rules enforced on top of RFC 8259:
+
+* UTF-8 without a byte-order mark (ill-formed UTF-8 is rejected, never replaced);
+* no duplicate object keys after escape decoding, at any depth;
+* no unpaired UTF-16 surrogate escapes;
+* no ``NaN``/``Infinity`` or other non-RFC 8259 tokens.
+
+Numbers keep their original spelling so that schema checks can insist on, for
+example, digits-only byte counts (``-0``, ``1.0`` and ``1e3`` are rejected
+where an integer is required).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Final, TypeAlias
+
+from .errors import Incomplete, Invalid, Issue, Outcome
+
+__all__ = [
+    "MAX_SAFE_INTEGER",
+    "JsonFloat",
+    "JsonInt",
+    "JsonObject",
+    "JsonValue",
+    "is_json_integer",
+    "json_pointer",
+    "json_type_name",
+    "parse_json",
+    "parse_json_object",
+]
+
+MAX_SAFE_INTEGER: Final = 9_007_199_254_740_991
+"""2^53 - 1, the largest byte count permitted by §3."""
+
+_BOM: Final = b"\xef\xbb\xbf"
+
+
+class JsonInt(int):
+    """An integer literal; ``lexeme`` is its exact source spelling."""
+
+    lexeme: str
+
+    def __new__(cls, lexeme: str) -> JsonInt:
+        obj = super().__new__(cls, lexeme)
+        obj.lexeme = lexeme
+        return obj
+
+
+class JsonFloat(float):
+    """A number literal with a fraction or exponent; ``lexeme`` is its spelling."""
+
+    lexeme: str
+
+    def __new__(cls, lexeme: str) -> JsonFloat:
+        obj = super().__new__(cls, lexeme)
+        obj.lexeme = lexeme
+        return obj
+
+
+JsonValue: TypeAlias = (
+    "bool | JsonInt | JsonFloat | str | list[JsonValue] | dict[str, JsonValue] | None"
+)
+JsonObject: TypeAlias = "dict[str, JsonValue]"
+
+
+class _DuplicateKeyError(Exception):
+    def __init__(self, key: str) -> None:
+        self.key = key
+
+
+class _ConstantError(Exception):
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+
+def _pairs_hook(pairs: list[tuple[str, JsonValue]]) -> dict[str, JsonValue]:
+    result: dict[str, JsonValue] = {}
+    for key, value in pairs:
+        if key in result:
+            raise _DuplicateKeyError(key)
+        result[key] = value
+    return result
+
+
+def _reject_constant(token: str) -> JsonValue:
+    raise _ConstantError(token)
+
+
+def _has_surrogate(text: str) -> bool:
+    # Code points U+D800..U+DFFF only arise from unpaired escapes because the
+    # UTF-8 decoder rejects encoded surrogates.
+    return any("\ud800" <= ch <= "\udfff" for ch in text)
+
+
+def _find_surrogate(value: JsonValue, pointer: str) -> str | None:
+    stack: list[tuple[JsonValue, str]] = [(value, pointer)]
+    while stack:
+        item, where = stack.pop()
+        if isinstance(item, str):
+            if _has_surrogate(item):
+                return where
+        elif isinstance(item, dict):
+            for key, child in item.items():
+                child_where = where + "/" + _escape_pointer(key)
+                if _has_surrogate(key):
+                    return child_where
+                stack.append((child, child_where))
+        elif isinstance(item, list):
+            for index, child in enumerate(item):
+                stack.append((child, f"{where}/{index}"))
+    return None
+
+
+def _escape_pointer(token: str) -> str:
+    return token.replace("~", "~0").replace("/", "~1")
+
+
+def json_pointer(*tokens: str | int) -> str:
+    """Build an RFC 6901 JSON pointer from path tokens."""
+    return "".join("/" + _escape_pointer(str(token)) for token in tokens)
+
+
+def parse_json(data: bytes, *, file: str | None = None, section: str = "7") -> JsonValue:
+    """Decode ``data`` under the §7 rules.
+
+    Raises:
+        Invalid: the bytes are not strict JSON.
+        Incomplete: nesting exceeded the interpreter's recursion limit (a local
+            resource limit, not proof of invalidity).
+    """
+
+    def fail(code: str, requirement: str, observed: str | None = None) -> Invalid:
+        return Invalid(Issue(code, requirement, section=section, file=file, observed=observed))
+
+    if data.startswith(_BOM):
+        raise fail("json_bom", "JSON must be UTF-8 without a byte-order mark")
+    try:
+        text = data.decode("utf-8", errors="strict")
+    except UnicodeDecodeError as exc:
+        raise fail(
+            "json_utf8", "JSON must be well-formed UTF-8", f"byte offset {exc.start}"
+        ) from exc
+    try:
+        value: JsonValue = json.loads(
+            text,
+            object_pairs_hook=_pairs_hook,
+            parse_int=JsonInt,
+            parse_float=JsonFloat,
+            parse_constant=_reject_constant,
+        )
+    except _DuplicateKeyError as exc:
+        raise fail(
+            "json_duplicate_key",
+            "object keys must be unique after escape decoding",
+            repr(exc.key),
+        ) from None
+    except _ConstantError as exc:
+        raise fail("json_syntax", "RFC 8259 does not permit this token", exc.token) from None
+    except json.JSONDecodeError as exc:
+        raise fail(
+            "json_syntax", "document must be RFC 8259 JSON", f"{exc.msg} at char {exc.pos}"
+        ) from None
+    except RecursionError:
+        raise Incomplete(
+            Issue(
+                "json_depth_limit",
+                "JSON nesting exceeds the local parser limit",
+                section="6",
+                file=file,
+                outcome=Outcome.INCOMPLETE,
+            )
+        ) from None
+    where = _find_surrogate(value, "")
+    if where is not None:
+        raise Invalid(
+            Issue(
+                "json_unpaired_surrogate",
+                "unpaired UTF-16 surrogate escapes are prohibited",
+                section=section,
+                file=file,
+                field=where or None,
+            )
+        )
+    return value
+
+
+def parse_json_object(data: bytes, *, file: str | None = None) -> JsonObject:
+    """Decode strict JSON and require a top-level object."""
+    value = parse_json(data, file=file)
+    if not isinstance(value, dict):
+        raise Invalid(
+            Issue(
+                "json_not_object",
+                "document must be a JSON object",
+                section="7",
+                file=file,
+                observed=json_type_name(value),
+            )
+        )
+    return value
+
+
+def is_json_integer(value: JsonValue) -> bool:
+    """True for an integer literal (not a boolean, fraction, or exponent)."""
+    return type(value) is JsonInt
+
+
+def json_type_name(value: object) -> str:
+    """Return the JSON type name of a decoded value."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, JsonInt | JsonFloat | int | float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__