j-perm 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

j_perm/ops/foreach.py

@@ -3,20 +3,19 @@ from __future__ import annotations
 import copy
 from typing import MutableMapping, Any, Mapping
 
-from ..registry import register_op
-from ..engine import normalize_actions, apply_actions
+from ..op_handler import OpRegistry
 from ..utils.pointers import maybe_slice
-from ..utils.subst import substitute
 
 
-@register_op("foreach")
+@OpRegistry.register("foreach")
 def op_foreach(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any] | list,
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Iterate over array in source and execute nested actions for each element."""
-    arr_ptr = substitute(step["in"], src)
+    arr_ptr = engine.substitutor.substitute(step["in"], src)
 
     default = copy.deepcopy(step.get("default", []))
     skip_empty = bool(step.get("skip_empty", True))
@@ -33,7 +32,7 @@ def op_foreach(
         arr = list(arr.items())
 
     var = step.get("as", "item")
-    body = normalize_actions(step["do"])
+    body = engine.normalize_actions(step["do"])
     snapshot = copy.deepcopy(dest)
 
     try:
@@ -44,7 +43,7 @@ def op_foreach(
                 extended = {"_": src}
 
             extended[var] = elem
-            dest = apply_actions(body, dest=dest, source=extended)
+            dest = engine.apply_actions(body, dest=dest, source=extended)
     except Exception:
         dest.clear()
         if isinstance(dest, list):

j_perm/ops/replace_root.py

@@ -2,15 +2,13 @@ from __future__ import annotations
 
 import copy
 
-from ..registry import register_op
-from ..utils.special import resolve_special
-from ..utils.subst import substitute
+from ..op_handler import OpRegistry
 
 
-@register_op("replace_root")
-def op_replace_root(step, dest, src):
+@OpRegistry.register("replace_root")
+def op_replace_root(step, dest, src, engine):
     """Replace the whole dest root value with the resolved special value."""
-    value = resolve_special(step["value"], src)
+    value = engine.special.resolve(step["value"], src, engine)
     if isinstance(value, (str, list, dict)):
-        value = substitute(value, src)
+        value = engine.substitutor.substitute(value, src)
     return copy.deepcopy(value)

j_perm/ops/set.py

@@ -2,26 +2,25 @@ from __future__ import annotations
 
 from typing import Any, Mapping, MutableMapping
 
-from ..registry import register_op
+from ..op_handler import OpRegistry
 from ..utils.pointers import jptr_ensure_parent
-from ..utils.special import resolve_special
-from ..utils.subst import substitute
 
 
-@register_op("set")
+@OpRegistry.register("set")
 def op_set(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any],
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Set or append a value at JSON Pointer path in dest."""
-    path = substitute(step["path"], src)
+    path = engine.substitutor.substitute(step["path"], src)
     create = bool(step.get("create", True))
     extend_list = bool(step.get("extend", True))
 
-    value = resolve_special(step["value"], src)
+    value = engine.special.resolve(step["value"], src, engine)
     if isinstance(value, (str, list, Mapping)):
-        value = substitute(value, src)
+        value = engine.substitutor.substitute(value, src)
 
     parent, leaf = jptr_ensure_parent(dest, path, create=create)
 

j_perm/ops/update.py

@@ -3,25 +3,24 @@ from __future__ import annotations
 import copy
 from typing import MutableMapping, Any, Mapping
 
-from ..registry import register_op
+from ..op_handler import OpRegistry
 from ..utils.pointers import maybe_slice, jptr_ensure_parent
-from ..utils.special import resolve_special
-from ..utils.subst import substitute
 
 
-@register_op("update")
+@OpRegistry.register("update")
 def op_update(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any],
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Update a mapping at the given path using a mapping from source or inline value."""
-    path = substitute(step["path"], src)
+    path = engine.substitutor.substitute(step["path"], src)
     create = bool(step.get("create", True))
     deep = bool(step.get("deep", False))
 
     if "from" in step:
-        ptr = substitute(step["from"], src)
+        ptr = engine.substitutor.substitute(step["from"], src)
         try:
             update_value = copy.deepcopy(maybe_slice(ptr, src))
         except Exception:
@@ -30,9 +29,9 @@ def op_update(
             else:
                 raise
     elif "value" in step:
-        update_value = resolve_special(step["value"], src)
+        update_value = engine.special.resolve(step["value"], src, engine)
         if isinstance(update_value, (str, list, Mapping)):
-            update_value = substitute(update_value, src)
+            update_value = engine.substitutor.substitute(update_value, src)
     else:
         raise ValueError("update operation requires either 'from' or 'value' parameter")
 

j_perm/schema/__init__.py

@@ -1,109 +1,109 @@
-from __future__ import annotations
-
-import re
-from typing import Any, Dict, List, Mapping
-
-from ..engine import normalize_actions
-
-_JSON_TYPE = {
-    str: "string",
-    int: "integer",
-    float: "number",
-    bool: "boolean",
-    list: "array",
-    dict: "object",
-    type(None): "null",
-}
-
-
-def _split_pointer(p: str) -> List[str]:
-    return [t.replace("~1", "/").replace("~0", "~") for t in p.lstrip("/").split("/")]
-
-
-def _merge(dst: dict, patch: dict) -> None:
-    for key, val in patch.items():
-        if isinstance(dst.get(key), dict) and isinstance(val, dict):
-            _merge(dst[key], val)
-        else:
-            dst[key] = val
-
-
-def build_schema(spec: Any) -> dict:
-    """Build a JSON Schema approximation from a DSL script.
-
-    The algorithm scans all steps that write to paths, infers basic JSON types from
-    literal values and respects replace_root / foreach / $eval nesting.
-    """
-    root: Dict[str, Any] = {
-        "type": "object",
-        "properties": {},
-        "required": [],
-    }
-
-    steps = normalize_actions(spec)
-
-    def _wild(pointer: str) -> str:
-        """Replace any ${...} template segments in pointer with '*' to avoid collisions."""
-        return re.sub(r"\$\{[^}]+}", "*", pointer)
-
-    def _ensure(pointer: str, is_append: bool) -> Dict[str, Any]:
-        """Ensure that the schema tree contains the path described by pointer."""
-        cur = root
-        for tok in _split_pointer(pointer):
-            cur.setdefault("required", [])
-            if tok not in cur["required"]:
-                cur["required"].append(tok)
-
-            cur = cur.setdefault("properties", {}).setdefault(
-                tok,
-                {"type": "object", "properties": {}},
-            )
-
-        if is_append:
-            cur["type"] = "array"
-
-        return cur
-
-    def _scan_value(val: Any) -> None:
-        if isinstance(val, Mapping):
-            if "$eval" in val:
-                nested = normalize_actions(val["$eval"])
-                _scan(nested)
-
-            for v in val.values():
-                _scan_value(v)
-
-        elif isinstance(val, (list, tuple)):
-            for item in val:
-                _scan_value(item)
-
-    def _scan(items: List[dict]) -> None:
-        for step in items:
-            op = step.get("op")
-
-            if op == "replace_root":
-                val = step.get("value")
-                if not (isinstance(val, Mapping) and "$ref" in val):
-                    root["type"] = _JSON_TYPE.get(type(val), "object")
-                _scan_value(val)
-                continue
-
-            if "do" in step and isinstance(step["do"], list):
-                _scan(step["do"])
-
-            if "path" in step:
-                path_raw = step["path"]
-                path = _wild(path_raw)
-
-                is_append = path.endswith("/-")
-                leaf = _ensure(path[:-2] if is_append else path, is_append)
-
-                if "value" in step and not isinstance(step["value"], Mapping):
-                    leaf["type"] = _JSON_TYPE.get(type(step["value"]), "object")
-
-                _scan_value(step.get("value"))
-            else:
-                _scan_value(step.get("value"))
-
-    _scan(steps)
-    return root
+# from __future__ import annotations
+#
+# import re
+# from typing import Any, Dict, List, Mapping
+#
+# from ..engine import normalize_actions
+#
+# _JSON_TYPE = {
+#     str: "string",
+#     int: "integer",
+#     float: "number",
+#     bool: "boolean",
+#     list: "array",
+#     dict: "object",
+#     type(None): "null",
+# }
+#
+#
+# def _split_pointer(p: str) -> List[str]:
+#     return [t.replace("~1", "/").replace("~0", "~") for t in p.lstrip("/").split("/")]
+#
+#
+# def _merge(dst: dict, patch: dict) -> None:
+#     for key, val in patch.items():
+#         if isinstance(dst.get(key), dict) and isinstance(val, dict):
+#             _merge(dst[key], val)
+#         else:
+#             dst[key] = val
+#
+#
+# def build_schema(spec: Any) -> dict:
+#     """Build a JSON Schema approximation from a DSL script.
+#
+#     The algorithm scans all steps that write to paths, infers basic JSON types from
+#     literal values and respects replace_root / foreach / $eval nesting.
+#     """
+#     root: Dict[str, Any] = {
+#         "type": "object",
+#         "properties": {},
+#         "required": [],
+#     }
+#
+#     steps = normalize_actions(spec)
+#
+#     def _wild(pointer: str) -> str:
+#         """Replace any ${...} template segments in pointer with '*' to avoid collisions."""
+#         return re.sub(r"\$\{[^}]+}", "*", pointer)
+#
+#     def _ensure(pointer: str, is_append: bool) -> Dict[str, Any]:
+#         """Ensure that the schema tree contains the path described by pointer."""
+#         cur = root
+#         for tok in _split_pointer(pointer):
+#             cur.setdefault("required", [])
+#             if tok not in cur["required"]:
+#                 cur["required"].append(tok)
+#
+#             cur = cur.setdefault("properties", {}).setdefault(
+#                 tok,
+#                 {"type": "object", "properties": {}},
+#             )
+#
+#         if is_append:
+#             cur["type"] = "array"
+#
+#         return cur
+#
+#     def _scan_value(val: Any) -> None:
+#         if isinstance(val, Mapping):
+#             if "$eval" in val:
+#                 nested = normalize_actions(val["$eval"])
+#                 _scan(nested)
+#
+#             for v in val.values():
+#                 _scan_value(v)
+#
+#         elif isinstance(val, (list, tuple)):
+#             for item in val:
+#                 _scan_value(item)
+#
+#     def _scan(items: List[dict]) -> None:
+#         for step in items:
+#             op = step.get("op")
+#
+#             if op == "replace_root":
+#                 val = step.get("value")
+#                 if not (isinstance(val, Mapping) and "$ref" in val):
+#                     root["type"] = _JSON_TYPE.get(type(val), "object")
+#                 _scan_value(val)
+#                 continue
+#
+#             if "do" in step and isinstance(step["do"], list):
+#                 _scan(step["do"])
+#
+#             if "path" in step:
+#                 path_raw = step["path"]
+#                 path = _wild(path_raw)
+#
+#                 is_append = path.endswith("/-")
+#                 leaf = _ensure(path[:-2] if is_append else path, is_append)
+#
+#                 if "value" in step and not isinstance(step["value"], Mapping):
+#                     leaf["type"] = _JSON_TYPE.get(type(step["value"]), "object")
+#
+#                 _scan_value(step.get("value"))
+#             else:
+#                 _scan_value(step.get("value"))
+#
+#     _scan(steps)
+#     return root

j_perm/special_resolver.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, MutableMapping
+
+# =============================================================================
+# Types
+# =============================================================================
+
+SpecialHandler = Callable[[Mapping[str, Any], Mapping[str, Any], "ActionEngine"], Any]
+
+
+# =============================================================================
+# Special registry (register constructs one-by-one)
+# =============================================================================
+
+class SpecialRegistry:
+    """
+    Registry of special constructs keyed by the marker key in a dict,
+    e.g. {"$ref": ...}, {"$eval": ...}.
+
+    Registration is per construct KEY (no "set" wrappers).
+
+    IMPORTANT:
+      If you rely on 'None => all registered', you must ensure modules that call
+      SpecialRegistry.register(...) are imported somewhere at startup.
+    """
+
+    _handlers: MutableMapping[str, SpecialHandler] = {}
+
+    @classmethod
+    def register(cls, key: str) -> Callable[[SpecialHandler], SpecialHandler]:
+        """
+        Decorator to register a special handler under a dict key (e.g. "$ref").
+
+        By default we raise on duplicates to avoid accidental overrides.
+        If you want overrides, change the duplicate check logic.
+        """
+
+        def decorator(fn: SpecialHandler) -> SpecialHandler:
+            if key in cls._handlers:
+                raise ValueError(f"special key already registered: {key!r}")
+            cls._handlers[key] = fn
+            return fn
+
+        return decorator
+
+    @classmethod
+    def get(cls, key: str) -> SpecialHandler:
+        """Return a registered handler or raise KeyError."""
+        return cls._handlers[key]
+
+    @classmethod
+    def all(cls) -> dict[str, SpecialHandler]:
+        """Return a copy of all registered handlers."""
+        return dict(cls._handlers)
+
+
+# =============================================================================
+# SpecialResolver (configurable)
+# =============================================================================
+
+_MISSING = object()
+
+
+@dataclass(slots=True)
+class SpecialResolver:
+    """
+    Walk a value tree and resolve registered special constructs.
+
+    Configuration:
+      - substitutor: used for template expansion inside constructs (e.g. "$ref" value)
+      - specials:
+          * None -> use all registered keys/handlers from SpecialRegistry
+          * list[str] -> use only these keys from registry
+          * Mapping[str, SpecialHandler] -> explicit mapping, bypass registry
+    """
+
+    specials: list[str] | Mapping[str, SpecialHandler] | None = None
+
+    _specials: dict[str, SpecialHandler] = field(init=False)
+
+    def __post_init__(self) -> None:
+        # Build the active special-handler map.
+        if self.specials is None:
+            self._specials = SpecialRegistry.all()
+        elif isinstance(self.specials, Mapping):
+            self._specials = dict(self.specials)
+        else:
+            all_sp = SpecialRegistry.all()
+            self._specials = {k: all_sp[k] for k in self.specials}
+
+    def resolve(self, val: Any, src: Mapping[str, Any], engine: "ActionEngine") -> Any:
+        """
+        Resolve special constructs inside an arbitrary value tree.
+
+        Semantics:
+          - If a dict contains a registered special key, that handler "takes over"
+            and the whole dict is replaced with the handler result.
+          - Otherwise we recurse into dict/list/tuple.
+        """
+        if isinstance(val, dict):
+            for key, fn in self._specials.items():
+                if key in val:
+                    return fn(val, src, engine)
+
+            return {k: self.resolve(v, src, engine) for k, v in val.items()}
+
+        if isinstance(val, list):
+            return [self.resolve(x, src, engine) for x in val]
+
+        if isinstance(val, tuple):
+            return tuple(self.resolve(x, src, engine) for x in val)
+
+        return val