dirigent-common 0.28.0__tar.gz → 0.29.0__tar.gz

{dirigent_common-0.28.0 → dirigent_common-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirigent-common
-Version: 0.28.0
+Version: 0.29.0
 Summary: Value types and shared schemas every dirigent package may depend on.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE

{dirigent_common-0.28.0 → dirigent_common-0.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-common"
-version = "0.28.0"
+version = "0.29.0"
 description = "Value types and shared schemas every dirigent package may depend on."
 readme = "README.md"
 requires-python = ">=3.13"

{dirigent_common-0.28.0 → dirigent_common-0.29.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-common"
-version = "0.28.0"
+version = "0.29.0"
 description = "Value types and shared schemas every dirigent package may depend on."
 readme = "README.md"
 requires-python = ">=3.13"

dirigent_common-0.29.0/src/dirigent_common/depth.py

@@ -0,0 +1,59 @@
+"""How deep a JSON value a run stores may nest, and how a deeper one is shown.
+
+Pydantic walks a value 255 levels down and no further, and every read nests a stored value a
+few levels deeper again: in a page, a report, an alert's context or a resolved config. A value
+past :data:`MAX_STORED_DEPTH` is refused where it would be stored, and one stored before that
+bound held is shown cut at it.
+"""
+
+from typing import Final, cast
+
+from pydantic import JsonValue
+
+from dirigent_common.messages import VALUE_NOT_SHOWN
+
+#: The most levels of lists and objects a stored value may nest: a step's output, a source's
+#: input, a run's parameters. Above the 128 an endpoint body may nest, and well inside the 255
+#: pydantic walks.
+MAX_STORED_DEPTH: Final = 160
+
+
+def nests_past(value: JsonValue, limit: int = MAX_STORED_DEPTH) -> bool:
+    """Say whether a value holds a list or object more than ``limit`` levels down.
+
+    The value itself is the first level, so a value nesting exactly ``limit`` levels passes.
+    """
+    level = [value]
+    for _ in range(limit):
+        level = [
+            child
+            for held in level
+            if isinstance(held, dict | list)
+            for child in (held.values() if isinstance(held, dict) else held)
+        ]
+        if not level:
+            return False
+    return any(isinstance(held, dict | list) for held in level)
+
+
+def shown[V: JsonValue](value: V, limit: int = MAX_STORED_DEPTH) -> V:
+    """Return a value as it is, or when it nests past ``limit``, a copy cut there.
+
+    Each list or object more than ``limit`` levels down is replaced by the sentence
+    :data:`VALUE_NOT_SHOWN` says.
+    """
+    if not nests_past(value, limit):
+        return value
+    marker = VALUE_NOT_SHOWN.render(limit=limit)
+    return cast("V", _cut(value, limit, marker))
+
+
+def _cut(value: JsonValue, left: int, marker: str) -> JsonValue:
+    """Copy a value down to ``left`` levels, putting ``marker`` where a deeper list or object was."""
+    if not isinstance(value, dict | list):
+        return value
+    if left <= 0:
+        return marker
+    if isinstance(value, dict):
+        return {key: _cut(inner, left - 1, marker) for key, inner in value.items()}
+    return [_cut(inner, left - 1, marker) for inner in value]

dirigent_common-0.29.0/src/dirigent_common/formats.py

@@ -0,0 +1,223 @@
+"""The base JSON Schema format checker every validation in dirigent draws from.
+
+A JSON Schema ``format`` keyword only asserts when a validator is given a checker for it;
+without one it is an annotation the value ignores. This is the one checker the engine and
+the blocks share, so ``format: date-time``, ``uuid`` and the like actually gate -- and it is
+the seam a plugin pack later adds its own formats to, which is why it lives in the shared
+leaf rather than in any one package.
+
+It seeds from the library's standard formats (the non-GPL extra provides their validators)
+and adds dirigent's own. ``regex`` is read without being compiled, and ``uri``, ``iri`` and their
+references are matched by the ``regex`` package under the evaluation's deadline, so a check over
+text a caller chose costs time in step with it and stops with the evaluation.
+
+None of dirigent's own are standard JSON Schema formats, so a tool that does not know them
+treats them as annotations and passes anything -- the graceful degradation every non-core
+format has; on a dirigent instance they assert. Each guards on a
+string first and parses where parsing is more correct than a pattern. The draft is 2020-12.
+"""
+
+import base64
+import binascii
+import re
+import uuid
+from collections.abc import Callable, Mapping
+from importlib import import_module
+from typing import Any, Final
+
+import regex
+from jsonschema import FormatChecker
+
+from dirigent_common.durations import is_duration
+from dirigent_common.schema_values import matches_whole
+
+#: Python's own reader of ``re`` syntax, which ``re.compile`` parses with before it compiles.
+_regex_syntax: Any = import_module("re._parser")
+_regex_ops: Any = import_module("re._constants")
+
+#: RFC 3986's IPv6address, as the library's ``uri`` check spells it.
+_IPV6: Final[str] = import_module("rfc3986_validator").IPv6_RE
+
+#: A Crockford base32 ULID: 26 characters, the first at most ``7`` so the timestamp fits 48 bits.
+_ULID = re.compile(r"[0-7][0-9A-HJKMNP-TV-Z]{25}")
+
+#: Hex digests, by their fixed nibble length; a digest is hex of either case.
+_HEX = {"md5": 32, "sha1": 40, "sha256": 64, "sha512": 128}
+
+#: The longest text ``format: regex`` reads as a pattern; anything longer is not one.
+MAX_FORMAT_REGEX: Final = 8192
+
+#: RFC 3987's ``ucschar``: the characters past ASCII an IRI may hold unescaped.
+_UCSCHAR: Final = "\u00a0-\ud7ff\uf900-\ufdcf\ufdf0-\uffef" + "".join(
+    f"{chr(plane * 0x10000 + (0x1000 if plane == 14 else 0))}-{chr(plane * 0x10000 + 0xFFFD)}" for plane in range(1, 15)
+)
+
+#: RFC 3987's ``iprivate``, which only an IRI's query may hold.
+_IPRIVATE: Final = "\ue000-\uf8ff\U000f0000-\U000ffffd\U00100000-\U0010fffd"
+
+
+def _reference_patterns(wide: str, private: str) -> tuple["regex.Pattern[str]", "regex.Pattern[str]"]:
+    """Compile RFC 3986's URI and URI-reference, or with ``wide`` and ``private`` RFC 3987's IRI forms.
+
+    Every repetition is possessive: none of them holds the character that ends it, so giving
+    one back can never let the rest match, and the match costs time in step with the text.
+    """
+    unreserved = rf"a-zA-Z0-9_.~\-{wide}"
+    sub = r"!$&'()*+,;="
+    pct = r"%[0-9A-Fa-f]{2}"
+    octet = r"(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)"
+    authority = (
+        rf"(?:(?:[{unreserved}{sub}:]|{pct})*+@)?"
+        rf"(?:\[(?:{_IPV6}|v[0-9A-Fa-f]+\.[a-zA-Z0-9_.~\-{sub}:]+)\]"
+        rf"|(?:{octet}\.){{3}}{octet}"
+        rf"|(?:[{unreserved}{sub}]|{pct})*+)"
+        r"(?::[0-9]*+)?"
+    )
+    pchar = rf"(?:[{unreserved}{sub}:@]|{pct})"
+    segments = rf"(?:/{pchar}*+)*+"
+    tail = rf"(?:\?(?:{pchar}|[/?{private}])*+)?(?:\#(?:{pchar}|[/?])*+)?"
+    absolute = rf"/(?:{pchar}++{segments})?"
+    uri = rf"[a-zA-Z][a-zA-Z0-9+.\-]*+:(?://{authority}{segments}|{absolute}|{pchar}++{segments}|){tail}"
+    noscheme = rf"(?:[{unreserved}{sub}@]|{pct})++{segments}"
+    relative = rf"(?://{authority}{segments}|{absolute}|{noscheme}|){tail}"
+    return regex.compile(uri, regex.VERSION0), regex.compile(rf"(?:{uri}|{relative})", regex.VERSION0)
+
+
+_URI, _URI_REFERENCE = _reference_patterns("", "")
+_IRI, _IRI_REFERENCE = _reference_patterns(_UCSCHAR, _IPRIVATE)
+
+#: The operators of a parsed pattern whose argument holds further parsed patterns.
+_NESTING: Final = {
+    _regex_ops.SUBPATTERN,
+    _regex_ops.BRANCH,
+    _regex_ops.MAX_REPEAT,
+    _regex_ops.MIN_REPEAT,
+    _regex_ops.POSSESSIVE_REPEAT,
+    _regex_ops.ASSERT,
+    _regex_ops.ASSERT_NOT,
+    _regex_ops.ATOMIC_GROUP,
+    _regex_ops.GROUPREF_EXISTS,
+}
+
+
+def _is_pattern(value: str) -> bool:
+    """Whether ``value`` is a pattern Python's ``re`` compiles, read without compiling it.
+
+    The parse costs time in step with the text. A look-behind must have one width, which
+    ``re`` checks only when it compiles.
+    """
+    if len(value) > MAX_FORMAT_REGEX:
+        return False
+    try:
+        pending: list[Any] = [_regex_syntax.parse(value)]
+        while pending:
+            parsed = pending.pop()
+            if not isinstance(parsed, _regex_syntax.SubPattern):
+                pending.extend(item for item in parsed if isinstance(item, list | tuple | _regex_syntax.SubPattern))
+                continue
+            for operator, argument in parsed.data:
+                if operator in (_regex_ops.ASSERT, _regex_ops.ASSERT_NOT) and argument[0] < 0:
+                    low, high = argument[1].getwidth()
+                    if low != high:
+                        return False
+                if operator in _NESTING:
+                    pending.append(argument)
+    except (re.error, RecursionError, OverflowError):
+        return False
+    return True
+
+
+def _is_uuid_version(value: object, version: int) -> bool:
+    """Whether the value parses as a UUID of exactly this version."""
+    if not isinstance(value, str):
+        return False
+    try:
+        return uuid.UUID(value).version == version
+    except ValueError:
+        return False
+
+
+def _is_hex_digest(value: object, length: int) -> bool:
+    """Whether the value is a hex string of exactly this many characters."""
+    return isinstance(value, str) and re.fullmatch(rf"[0-9a-fA-F]{{{length}}}", value) is not None
+
+
+def _is_base64(value: object) -> bool:
+    """Whether the value is standard base64. The empty string is valid: it decodes to no bytes."""
+    if not isinstance(value, str):
+        return False
+    try:
+        base64.b64decode(value, validate=True)
+    except (binascii.Error, ValueError):
+        return False
+    return True
+
+
+def base_format_checker() -> FormatChecker:
+    """Build the format checker dirigent validates values against, standard formats plus its own."""
+    checker = FormatChecker()
+
+    @checker.checks("regex")
+    def _regex(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A pattern Python's ``re`` takes, at most ``MAX_FORMAT_REGEX`` characters long."""
+        return not isinstance(value, str) or _is_pattern(value)
+
+    for _name, _reference in {
+        "uri": _URI,
+        "uri-reference": _URI_REFERENCE,
+        "iri": _IRI,
+        "iri-reference": _IRI_REFERENCE,
+    }.items():
+
+        @checker.checks(_name)
+        def _is_reference(value: object, pattern: "regex.Pattern[str]" = _reference) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+            """An RFC 3986 URI or RFC 3987 IRI, matched within the evaluation's deadline."""
+            return not isinstance(value, str) or matches_whole(pattern, value)
+
+    @checker.checks("ulid")
+    def _is_ulid(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A 26-character Crockford base32 ULID. Canonically uppercase; lowercase decodes too."""
+        return isinstance(value, str) and _ULID.fullmatch(value.upper()) is not None
+
+    @checker.checks("uuid4")
+    def _is_uuid4(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A UUID that is specifically version 4 (random)."""
+        return _is_uuid_version(value, 4)
+
+    @checker.checks("uuid7")
+    def _is_uuid7(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A UUID that is specifically version 7 (time-ordered) -- what dirigent's own ids are."""
+        return _is_uuid_version(value, 7)
+
+    for _name, _length in _HEX.items():
+
+        @checker.checks(_name)
+        def _is_digest(value: object, length: int = _length) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+            """A hex digest of the fixed length this algorithm produces, either case."""
+            return _is_hex_digest(value, length)
+
+    @checker.checks("humane-duration")
+    def _humane_duration(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A duration in dirigent's spelling, such as ``30s`` or ``1h30m``; never ISO 8601."""
+        return is_duration(value)
+
+    @checker.checks("base64")
+    def _base64(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A standard base64 string; the empty string counts, decoding to no bytes."""
+        return _is_base64(value)
+
+    return checker
+
+
+def format_checker_with(contributed: Mapping[str, Callable[[object], bool]]) -> FormatChecker:
+    """Build the checker an instance validates against: the base formats plus contributed ones.
+
+    A pack contributes a predicate per format name; a value is invalid when the predicate
+    returns False or raises, which is the whole shape of a jsonschema format check. The base
+    checker is copied rather than added to, so each host's assembly is its own and the shared
+    base stays exactly the standard-plus-dirigent set every call builds.
+    """
+    checker = base_format_checker()
+    for name, predicate in contributed.items():
+        checker.checks(name, raises=(Exception,))(predicate)
+    return checker

{dirigent_common-0.28.0 → dirigent_common-0.29.0}/src/dirigent_common/messages.py

@@ -175,6 +175,8 @@ YAML_ALIAS_CYCLE = COMMON.define(
 
 YAML_NESTED_TOO_DEEP = COMMON.define("yaml_nested_too_deep", "the YAML nests too deeply to be read")
 
+VALUE_NOT_SHOWN = COMMON.define("value_not_shown", "nested deeper than {limit} levels, not shown")
+
 VALIDATION = Catalogue("validation")
 
 #: Pydantic names the condition, so the second half of a validation code is its own error

{dirigent_common-0.28.0 → dirigent_common-0.29.0}/src/dirigent_common/schema_values.py

@@ -9,6 +9,7 @@ Draft 2020-12, saying what the library says, with these differences in how:
 * ``pattern``, ``patternProperties``, and the patterns ``additionalProperties`` and
   ``unevaluatedProperties`` read match with the ``regex`` package in its ``re``-compatible mode,
   which releases the interpreter's lock while it matches and stops at the evaluation's deadline.
+  :func:`matches_whole` gives a format predicate the same match.
 * Every keyword checks the bound :func:`bounded_evaluation` sets before it runs, and raises
   :class:`EvaluationOverrun` once the deadline has passed or the caller has stopped waiting.
 
@@ -98,10 +99,29 @@ def _found(pattern: str, text: str) -> bool:
 
     The match releases the interpreter's lock while it runs.
     """
+    return _matched(_compiled(pattern), text, whole=False)
+
+
+def matches_whole(pattern: "regex.Pattern[str]", text: str) -> bool:
+    """Whether ``pattern`` matches all of ``text``, within what the evaluation has left.
+
+    The match releases the interpreter's lock while it runs, and outside
+    :func:`bounded_evaluation` it is unbounded.
+
+    Raises:
+        EvaluationOverrun: The deadline passed before or during the match, or the caller stopped waiting.
+    """
+    return _matched(pattern, text, whole=True)
+
+
+def _matched(pattern: "regex.Pattern[str]", text: str, *, whole: bool) -> bool:
+    """Search ``text`` for ``pattern``, or match all of it, stopping at the evaluation's deadline."""
     bound = _BOUND.get()
     left = _remaining(bound)
     try:
-        return _compiled(pattern).search(text, concurrent=True, timeout=left) is not None
+        if whole:
+            return pattern.fullmatch(text, concurrent=True, timeout=left) is not None
+        return pattern.search(text, concurrent=True, timeout=left) is not None
     except TimeoutError as error:
         raise EvaluationOverrun(bound.within if bound is not None else timedelta(0)) from error
 
@@ -315,4 +335,4 @@ ValueValidator: Final[Any] = extend_validator(  # pyright: ignore[reportUnknownV
     version="draft2020-12",
 )
 
-__all__ = ["EvaluationOverrun", "ValueValidator", "bounded_evaluation", "canonical_json"]
+__all__ = ["EvaluationOverrun", "ValueValidator", "bounded_evaluation", "canonical_json", "matches_whole"]

dirigent_common-0.28.0/src/dirigent_common/formats.py

@@ -1,109 +0,0 @@
-"""The base JSON Schema format checker every validation in dirigent draws from.
-
-A JSON Schema ``format`` keyword only asserts when a validator is given a checker for it;
-without one it is an annotation the value ignores. This is the one checker the engine and
-the blocks share, so ``format: date-time``, ``uuid`` and the like actually gate -- and it is
-the seam a plugin pack later adds its own formats to, which is why it lives in the shared
-leaf rather than in any one package.
-
-It seeds from the library's standard formats (the non-GPL extra provides their validators)
-and adds dirigent's own. None of the ones added here are standard JSON Schema formats, so a
-tool that does not know them treats them as annotations and passes anything -- the graceful
-degradation every non-core format has; on a dirigent instance they assert. Each guards on a
-string first and parses where parsing is more correct than a pattern. The draft is 2020-12.
-"""
-
-import base64
-import binascii
-import re
-import uuid
-from collections.abc import Callable, Mapping
-
-from jsonschema import FormatChecker
-
-from dirigent_common.durations import is_duration
-
-#: A Crockford base32 ULID: 26 characters, the first at most ``7`` so the timestamp fits 48 bits.
-_ULID = re.compile(r"[0-7][0-9A-HJKMNP-TV-Z]{25}")
-
-#: Hex digests, by their fixed nibble length; a digest is hex of either case.
-_HEX = {"md5": 32, "sha1": 40, "sha256": 64, "sha512": 128}
-
-
-def _is_uuid_version(value: object, version: int) -> bool:
-    """Whether the value parses as a UUID of exactly this version."""
-    if not isinstance(value, str):
-        return False
-    try:
-        return uuid.UUID(value).version == version
-    except ValueError:
-        return False
-
-
-def _is_hex_digest(value: object, length: int) -> bool:
-    """Whether the value is a hex string of exactly this many characters."""
-    return isinstance(value, str) and re.fullmatch(rf"[0-9a-fA-F]{{{length}}}", value) is not None
-
-
-def _is_base64(value: object) -> bool:
-    """Whether the value is standard base64. The empty string is valid: it decodes to no bytes."""
-    if not isinstance(value, str):
-        return False
-    try:
-        base64.b64decode(value, validate=True)
-    except (binascii.Error, ValueError):
-        return False
-    return True
-
-
-def base_format_checker() -> FormatChecker:
-    """Build the format checker dirigent validates values against, standard formats plus its own."""
-    checker = FormatChecker()
-
-    @checker.checks("ulid")
-    def _is_ulid(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
-        """A 26-character Crockford base32 ULID. Canonically uppercase; lowercase decodes too."""
-        return isinstance(value, str) and _ULID.fullmatch(value.upper()) is not None
-
-    @checker.checks("uuid4")
-    def _is_uuid4(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
-        """A UUID that is specifically version 4 (random)."""
-        return _is_uuid_version(value, 4)
-
-    @checker.checks("uuid7")
-    def _is_uuid7(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
-        """A UUID that is specifically version 7 (time-ordered) -- what dirigent's own ids are."""
-        return _is_uuid_version(value, 7)
-
-    for _name, _length in _HEX.items():
-
-        @checker.checks(_name)
-        def _is_digest(value: object, length: int = _length) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
-            """A hex digest of the fixed length this algorithm produces, either case."""
-            return _is_hex_digest(value, length)
-
-    @checker.checks("humane-duration")
-    def _humane_duration(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
-        """A duration in dirigent's spelling, such as ``30s`` or ``1h30m``; never ISO 8601."""
-        return is_duration(value)
-
-    @checker.checks("base64")
-    def _base64(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
-        """A standard base64 string; the empty string counts, decoding to no bytes."""
-        return _is_base64(value)
-
-    return checker
-
-
-def format_checker_with(contributed: Mapping[str, Callable[[object], bool]]) -> FormatChecker:
-    """Build the checker an instance validates against: the base formats plus contributed ones.
-
-    A pack contributes a predicate per format name; a value is invalid when the predicate
-    returns False or raises, which is the whole shape of a jsonschema format check. The base
-    checker is copied rather than added to, so each host's assembly is its own and the shared
-    base stays exactly the standard-plus-dirigent set every call builds.
-    """
-    checker = base_format_checker()
-    for name, predicate in contributed.items():
-        checker.checks(name, raises=(Exception,))(predicate)
-    return checker