deterministic-scenario-engine 1.0.0__py3-none-any.whl

scenario_engine/validation.py

@@ -0,0 +1,95 @@
+"""Pure deterministic resource validators and pre-execution constraints."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from decimal import Decimal
+from typing import Any, Mapping
+
+from .errors import ScenarioEngineError
+from .expressions import EvaluationEnvironment, Expression
+from .ids import LogicalID
+from .resources import ResolvedResources, ResourceResolutionError
+from .values import MISSING, canonical_bytes
+
+
+class ResourceValidationError(ScenarioEngineError, ValueError):
+    pass
+
+
+class ConstraintError(ScenarioEngineError, ValueError):
+    pass
+
+
+class ConstraintDefinitionError(ConstraintError):
+    pass
+
+
+class ConstraintViolation(ConstraintError):
+    pass
+
+
+def semantic_equal(left: Any, right: Any) -> bool:
+    return canonical_bytes(left) == canonical_bytes(right)
+
+
+def _semantic_type(value: Any) -> str:
+    if value is MISSING: return "missing"
+    if value is None: return "null"
+    if type(value) is bool: return "boolean"
+    if type(value) is int: return "integer"
+    if isinstance(value, Decimal): return "decimal"
+    if isinstance(value, str): return "string"
+    if isinstance(value, datetime): return "datetime"
+    if isinstance(value, timedelta): return "duration"
+    if isinstance(value, LogicalID): return "logical_id"
+    if isinstance(value, (list, tuple)): return "list"
+    if isinstance(value, Mapping): return "map"
+    return "unsupported"
+
+
+def validate_resources(resources: ResolvedResources, declarations: tuple[Mapping[str, Any], ...]) -> None:
+    for declaration in declarations:
+        validator_id = declaration["id"]
+        path = declaration["resource"]
+        kind = declaration["kind"]
+        try:
+            value = resources.lookup(path)
+        except ResourceResolutionError as error:
+            raise ResourceValidationError(
+                f"validator {validator_id} ({kind}) resource {path}: {error}"
+            ) from None
+        reason: str | None = None
+        if kind == "required":
+            if value is MISSING: reason = "value is MISSING"
+        elif kind == "type":
+            actual = _semantic_type(value)
+            if actual != declaration["type"]: reason = f"expected {declaration['type']}, got {actual}"
+        elif kind == "range":
+            if type(value) not in (int, Decimal): reason = "value is not integer or decimal"
+            else:
+                if "min" in declaration and Decimal(value) < Decimal(declaration["min"]): reason = "below inclusive minimum"
+                if "max" in declaration and Decimal(value) > Decimal(declaration["max"]): reason = "above inclusive maximum"
+        elif kind == "length":
+            if not isinstance(value, (str, list, tuple, Mapping)): reason = "value has no supported length"
+            else:
+                if "min" in declaration and len(value) < declaration["min"]: reason = "below inclusive minimum length"
+                if "max" in declaration and len(value) > declaration["max"]: reason = "above inclusive maximum length"
+        elif kind == "one_of":
+            if not any(semantic_equal(value, candidate) for candidate in declaration["values"]):
+                reason = "value is not one of allowed semantic values"
+        if reason:
+            raise ResourceValidationError(
+                f"validator {validator_id} ({kind}) resource {path}: {reason}"
+            )
+
+
+def evaluate_constraints(constraints: tuple[tuple[str, Expression, str | None], ...]) -> None:
+    environment = EvaluationEnvironment({}, {}, {})
+    for constraint_id, expression, message in constraints:
+        result = expression.evaluate(environment)
+        if type(result) is not bool:
+            raise ConstraintDefinitionError(f"constraint {constraint_id}: check must return boolean")
+        if not result:
+            suffix = f": {message}" if message else ""
+            raise ConstraintViolation(f"constraint {constraint_id} violated{suffix}")

scenario_engine/values.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+import hashlib
+import json
+from typing import Any, Mapping
+
+from .ids import LogicalID
+
+
+class _Missing:
+    __slots__ = ()
+
+    def __copy__(self) -> _Missing:
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> _Missing:
+        memo[id(self)] = self
+        return self
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+
+MISSING = _Missing()
+
+
+def normalize(value: Any) -> Any:
+    if value is MISSING:
+        return {"$type": "missing"}
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, Decimal):
+        return {"$type": "decimal", "value": str(value)}
+    if isinstance(value, str):
+        return value
+    if isinstance(value, LogicalID):
+        return {"$type": "logical-id", "value": value.value}
+    if isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("datetime values must be timezone-aware")
+        utc = value.astimezone(timezone.utc)
+        return {"$type": "datetime", "value": utc.isoformat(timespec="microseconds")}
+    if isinstance(value, timedelta):
+        total_micros = ((value.days * 86400 + value.seconds) * 1_000_000 + value.microseconds)
+        return {"$type": "duration-microseconds", "value": total_micros}
+    if isinstance(value, (list, tuple)):
+        return [normalize(item) for item in value]
+    if isinstance(value, Mapping):
+        if not all(isinstance(key, str) for key in value):
+            raise TypeError("semantic mappings require string keys")
+        return {key: normalize(value[key]) for key in sorted(value)}
+    raise TypeError(f"unsupported semantic value: {type(value).__name__}")
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return json.dumps(normalize(value), sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+
+
+def fingerprint(value: Any) -> str:
+    return hashlib.sha256(canonical_bytes(value)).hexdigest()