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

j_perm/__init__.py

@@ -1,13 +1,21 @@
 # Import built-in operations so that they register on import.
+from . import casters as _builtin_casters  # noqa: F401
+from . import constructs as _builtin_constructs  # noqa: F401
+from . import funcs as _builtin_funcs  # noqa: F401
 from . import ops as _builtin_ops  # noqa: F401
-from .engine import apply_actions, normalize_actions
-from .registry import register_op, Handler
-from .schema import build_schema
+from .engine import apply_actions, ActionEngine
+from .subst import JpFuncRegistry, CasterRegistry, TemplateSubstitutor
+from .op_handler import OpRegistry, Handlers
+from .special_resolver import SpecialRegistry, SpecialResolver
 
 __all__ = [
-    "Handler",
-    "register_op",
     "apply_actions",
-    "normalize_actions",
-    "build_schema",
+    "ActionEngine",
+    "JpFuncRegistry",
+    "CasterRegistry",
+    "TemplateSubstitutor",
+    "OpRegistry",
+    "Handlers",
+    "SpecialRegistry",
+    "SpecialResolver",
 ]

j_perm/casters/__init__.py

@@ -0,0 +1,4 @@
+from ._bool import cast_bool
+from ._float import cast_float
+from ._int import cast_int
+from ._str import cast_str

j_perm/casters/_bool.py

@@ -0,0 +1,9 @@
+from typing import Any
+
+from j_perm.subst import CasterRegistry
+
+
+@CasterRegistry.register("bool")
+def cast_bool(x: Any) -> bool:
+    # Preserve original semantics
+    return bool(int(x)) if isinstance(x, (int, str)) else bool(x)

j_perm/casters/_float.py

@@ -0,0 +1,8 @@
+from typing import Any
+
+from j_perm.subst import CasterRegistry
+
+
+@CasterRegistry.register("float")
+def cast_float(x: Any) -> float:
+    return float(x)

j_perm/casters/_int.py

@@ -0,0 +1,8 @@
+from typing import Any
+
+from j_perm.subst import CasterRegistry
+
+
+@CasterRegistry.register("int")
+def cast_int(x: Any) -> int:
+    return int(x)

j_perm/casters/_str.py

@@ -0,0 +1,8 @@
+from typing import Any
+
+from j_perm.subst import CasterRegistry
+
+
+@CasterRegistry.register("str")
+def cast_str(x: Any) -> str:
+    return str(x)

j_perm/constructs/__init__.py

@@ -0,0 +1,2 @@
+from .eval import sp_eval
+from .ref import of_ref

j_perm/constructs/eval.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Mapping, Any
+
+from j_perm.special_resolver import SpecialRegistry
+
+
+@SpecialRegistry.register("$eval")
+def sp_eval(node: Mapping[str, Any], src: Mapping[str, Any], engine: "ActionEngine") -> Any:
+    out = engine.apply_actions(node["$eval"], dest={}, source=src)
+
+    if "$select" in node:
+        sel = resolver.slice(node["$select"], out)  # type: ignore[arg-type]
+        return sel
+
+    return out

j_perm/constructs/ref.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import copy
+from typing import Mapping, Any
+
+from j_perm.special_resolver import _MISSING, SpecialRegistry
+from j_perm.utils.pointers import maybe_slice
+
+
+@SpecialRegistry.register("$ref")
+def of_ref(node: Mapping[str, Any], src: Mapping[str, Any], engine: "ActionEngine") -> Any:
+    # Expand templates inside "$ref" using configured substitutor
+    ptr = engine.substitutor.substitute(node["$ref"], src)
+
+    dflt = node.get("$default", _MISSING)
+    try:
+        return copy.deepcopy(maybe_slice(ptr, src))
+    except Exception:
+        if dflt is not _MISSING:
+            return copy.deepcopy(dflt)
+        raise

j_perm/engine.py

@@ -1,11 +1,21 @@
 from __future__ import annotations
 
 import copy
-from typing import Any, List, Mapping, MutableMapping, Union
+from dataclasses import dataclass, field
+from typing import Any, List, Mapping, TypeAlias, MutableMapping, Union
 
-from .registry import get_handler
-from .utils.tuples import tuples_to_lists
+from .op_handler import Handlers
+from .special_resolver import SpecialResolver
+from .subst import TemplateSubstitutor
 
+JsonLikeMapping: TypeAlias = MutableMapping[str, Any]
+JsonLikeSource: TypeAlias = Union[Mapping[str, Any], List[Any]]
+JsonLikeDest: TypeAlias = Union[MutableMapping[str, Any], List[Any]]
+
+
+# =============================================================================
+# Small utilities
+# =============================================================================
 
 def _is_pointer_string(v: Any) -> bool:
     return isinstance(v, str) and v.startswith("/")
@@ -15,72 +25,138 @@ def _to_list(x: Any) -> List[Any]:
     return x if isinstance(x, list) else [x]
 
 
-def _expand_shorthand(obj: Mapping[str, Any]) -> List[dict]:
-    """Expand shorthand mapping form into explicit op steps."""
-    steps: List[dict] = []
-
-    for key, val in obj.items():
-        if key == "~delete":
-            for p in _to_list(val):
-                steps.append({"op": "delete", "path": p})
-            continue
-
-        if key == "~assert":
-            if isinstance(val, Mapping):
-                for p, eq in val.items():
-                    steps.append({"op": "assert", "path": p, "equals": eq})
-            else:
+def tuples_to_lists(obj: Any) -> Any:
+    """Recursively convert all tuples into lists so JMESPath indexers work reliably."""
+    if isinstance(obj, tuple):
+        return [tuples_to_lists(x) for x in obj]
+
+    if isinstance(obj, list):
+        return [tuples_to_lists(x) for x in obj]
+
+    if isinstance(obj, Mapping):
+        return {k: tuples_to_lists(v) for k, v in obj.items()}
+
+    return obj
+
+
+@dataclass(slots=True)
+class ActionEngine:
+    """
+    Executes a DSL script against dest with a given source context.
+
+    Configuration:
+      - handlers: a Handlers object (has get_handler)
+      - special: a SpecialResolver (resolves $ref/$eval/... inside the actions spec, if you want)
+      - substitutor: a TemplateSubstitutor (optional: expand ${...} in action specs)
+      - resolve_special_in_actions: enable resolving special constructs inside the actions spec
+      - substitute_templates_in_actions: enable template expansion inside the actions spec
+
+    Notes on order:
+      1) Optionally substitute templates in 'actions' using 'source' as context
+      2) Optionally resolve special constructs in 'actions' using 'source' as context
+      3) Normalize to flat step list
+      4) Execute handlers
+    """
+
+    handlers: Handlers = field(default_factory=Handlers)
+    special: SpecialResolver = field(default_factory=SpecialResolver)
+    substitutor: TemplateSubstitutor = field(default_factory=TemplateSubstitutor)
+
+    resolve_special_in_actions: bool = True
+    substitute_templates_in_actions: bool = True
+
+    def apply_actions(
+            self,
+            actions: Any,
+            *,
+            dest: JsonLikeDest,
+            source: JsonLikeSource,
+    ) -> Any:
+        """External API: apply a DSL script."""
+        # Work on copies to keep the function referentially safe.
+        result = copy.deepcopy(dest)
+
+        # Normalize actions into a flat list of step dicts.
+        steps = self.normalize_actions(actions)
+
+        # Convert tuples in source to lists.
+        source_norm = tuples_to_lists(source)
+
+        try:
+            for step in steps:
+                op = step.get("op")
+                if not op:
+                    raise ValueError(f"Invalid step without 'op': {step!r}")
+
+                handler = self.handlers.get_handler(op)
+                result = handler(step, result, source_norm, self)
+        except ValueError:
+            raise
+        except Exception:
+            raise
+
+        return copy.deepcopy(result)
+
+    # -------------------------------------------------------------------------
+    # Normalization (ported from your original code)
+    # -------------------------------------------------------------------------
+
+    def normalize_actions(self, spec: Any) -> List[dict]:
+        """Normalize DSL script into a flat list of step dicts."""
+        if isinstance(spec, list):
+            out: List[dict] = []
+            for item in spec:
+                if isinstance(item, Mapping) and "op" not in item:
+                    out.extend(self._expand_shorthand(item))
+                else:
+                    out.append(item)
+            return out
+
+        if isinstance(spec, Mapping):
+            return self._expand_shorthand(spec)
+
+        raise TypeError("spec must be dict or list")
+
+    @staticmethod
+    def _expand_shorthand(obj: Mapping[str, Any]) -> List[dict]:
+        """Expand shorthand mapping form into explicit op steps."""
+        steps: List[dict] = []
+
+        for key, val in obj.items():
+            if key == "~delete":
                 for p in _to_list(val):
-                    steps.append({"op": "assert", "path": p})
-            continue
-
-        append = key.endswith("[]")
-        dst = f"{key[:-2]}/-" if append else key
-
-        if _is_pointer_string(val):
-            steps.append({"op": "copy", "from": val, "path": dst, "ignore_missing": True})
-        else:
-            steps.append({"op": "set", "path": dst, "value": val})
-
-    return steps
-
-
-def normalize_actions(spec: Any) -> List[dict]:
-    """Normalize DSL script into a flat list of step dicts."""
-    if isinstance(spec, list):
-        out: List[dict] = []
-        for item in spec:
-            if isinstance(item, Mapping) and "op" not in item:
-                out.extend(_expand_shorthand(item))
+                    steps.append({"op": "delete", "path": p})
+                continue
+
+            if key == "~assert":
+                if isinstance(val, Mapping):
+                    for p, eq in val.items():
+                        steps.append({"op": "assert", "path": p, "equals": eq})
+                else:
+                    for p in _to_list(val):
+                        steps.append({"op": "assert", "path": p})
+                continue
+
+            append = isinstance(key, str) and key.endswith("[]")
+            dst = f"{key[:-2]}/-" if append else key
+
+            if _is_pointer_string(val):
+                steps.append({"op": "copy", "from": val, "path": dst, "ignore_missing": True})
             else:
-                out.append(item)
-        return out
+                steps.append({"op": "set", "path": dst, "value": val})
+
+        return steps
 
-    if isinstance(spec, Mapping):
-        return _expand_shorthand(spec)
 
-    raise TypeError("spec must be dict or list")
+# Create a default engine instance for convenience
+default_engine = ActionEngine()
 
 
 def apply_actions(
         actions: Any,
         *,
-        dest: Union[MutableMapping[str, Any], List[Any]],
-        source: Union[Mapping[str, Any], List[Any]],
-) -> Mapping[str, Any]:
-    """Execute a DSL script against dest with a given source context."""
-    steps = normalize_actions(actions)
-    result = copy.deepcopy(dest)
-
-    source = tuples_to_lists(source)
-
-    try:
-        for step in steps:
-            handler = get_handler(step["op"])
-            result = handler(step, result, source)  # type: ignore[arg-type]
-    except ValueError:
-        raise
-    except Exception:
-        raise
-
-    return copy.deepcopy(result)
+        dest: JsonLikeDest,
+        source: JsonLikeSource,
+) -> Any:
+    """Convenience function: apply a DSL script using the default engine."""
+    return default_engine.apply_actions(actions, dest=dest, source=source)

j_perm/funcs/__init__.py

@@ -0,0 +1 @@
+from .subtract import subtract

j_perm/funcs/subtract.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from jmespath import functions as _jp_funcs
+
+from j_perm.subst import JpFuncRegistry
+
+
+@JpFuncRegistry.register("subtract")
+@_jp_funcs.signature({"types": ["number"]}, {"types": ["number"]})
+def subtract(self, a: float, b: float) -> float:
+    return a - b

j_perm/op_handler.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass, field
+from typing import Mapping, Any, Callable
+
+OpHandler = Callable[[dict, Any, Any, "ActionEngine"], Any]
+
+
+class OpRegistry:
+    _ops: dict[str, OpHandler] = {}
+
+    @classmethod
+    def register(cls, name: str) -> Callable[[OpHandler], OpHandler]:
+        def deco(fn: OpHandler) -> OpHandler:
+            if name in cls._ops:
+                raise ValueError(f"op already registered: {name!r}")
+            cls._ops[name] = fn
+            return fn
+
+        return deco
+
+    @classmethod
+    def get(cls, name: str) -> OpHandler:
+        try:
+            return cls._ops[name]
+        except KeyError:
+            raise ValueError(f"Unknown op {name!r}") from None
+
+    @classmethod
+    def all(cls) -> dict[str, OpHandler]:
+        return dict(cls._ops)
+
+
+@dataclass(slots=True)
+class Handlers:
+    """
+    If ops is None -> use all registered.
+    If ops is list[str] -> use only those names.
+    If ops is Mapping[str, handler] -> use that explicit mapping (no registry).
+    """
+    ops: list[str] | Mapping[str, OpHandler] | None = None
+    on_conflict: str = "error"  # "error" | "override"
+    _ops: dict[str, OpHandler] = field(init=False, repr=False)
+
+    def get_handler(self, name: str) -> OpHandler:
+        return self._ops[name]
+
+    def __post_init__(self) -> None:
+        if self.ops is None:
+            ops_map = OpRegistry.all()
+        elif isinstance(self.ops, Mapping):
+            ops_map = dict(self.ops)
+        else:
+            all_ops = OpRegistry.all()
+            ops_map = {}
+            for n in self.ops:
+                ops_map[n] = all_ops[n]
+
+        self._ops = ops_map

j_perm/ops/__init__.py

@@ -1,3 +1,4 @@
+from ._assert import op_assert
 from ._exec import op_exec
 from ._if import op_if
 from .copy import op_copy

j_perm/ops/{assert.py → _assert.py}

@@ -2,19 +2,19 @@ from __future__ import annotations
 
 from typing import MutableMapping, Any, Mapping
 
-from ..registry import register_op
+from ..op_handler import OpRegistry
 from ..utils.pointers import jptr_get
-from ..utils.subst import substitute
 
 
-@register_op("assert")
+@OpRegistry.register("assert")
 def op_assert(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any],
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Assert node existence and/or value at JSON Pointer path in dest."""
-    path = substitute(step["path"], src)
+    path = engine.substitutor.substitute(step["path"], src)
 
     try:
         current = jptr_get(dest, path)

j_perm/ops/_exec.py

@@ -2,18 +2,17 @@ from __future__ import annotations
 
 from typing import MutableMapping, Any, Mapping
 
-from ..registry import register_op
+from ..op_handler import OpRegistry
 from ..engine import apply_actions
 from ..utils.pointers import maybe_slice
-from ..utils.special import resolve_special
-from ..utils.subst import substitute
 
 
-@register_op("exec")
+@OpRegistry.register("exec")
 def op_exec(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any],
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Execute nested actions stored either in source or inline in the op."""
     has_from = "from" in step
@@ -26,20 +25,20 @@ def op_exec(
         raise ValueError("exec operation requires either 'from' or 'actions' parameter")
 
     if has_from:
-        actions_ptr = substitute(step["from"], src)
+        actions_ptr = engine.substitutor.substitute(step["from"], src)
         try:
             actions = maybe_slice(actions_ptr, src)
         except Exception:
             if "default" in step:
-                actions = resolve_special(step["default"], src)
+                actions = engine.special.resolve(step["default"], src, engine)
                 if isinstance(actions, (str, list, dict)):
-                    actions = substitute(actions, src)
+                    actions = engine.substitutor.substitute(actions, src)
             else:
                 raise ValueError(f"Cannot find actions at {actions_ptr}")
     else:
-        actions = resolve_special(step["actions"], src)
+        actions = engine.special.resolve(step["actions"], src, engine)
         if isinstance(actions, (str, list, dict)):
-            actions = substitute(actions, src)
+            actions = engine.substitutor.substitute(actions, src)
 
     merge = bool(step.get("merge", False))
 

j_perm/ops/_if.py

@@ -3,22 +3,21 @@ 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("if")
+@OpRegistry.register("if")
 def op_if(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any] | list,
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Conditionally execute nested actions based on a path or expression."""
     if "path" in step:
         try:
-            ptr = substitute(step["path"], src)
+            ptr = engine.substitutor.substitute(step["path"], src)
             current = maybe_slice(ptr, dest)
             missing = False
         except Exception:
@@ -26,14 +25,14 @@ def op_if(
             missing = True
 
         if "equals" in step:
-            expected = substitute(step["equals"], src)
+            expected = engine.substitutor.substitute(step["equals"], src)
             cond_val = current == expected and not missing
         elif step.get("exists"):
             cond_val = not missing
         else:
             cond_val = bool(current) and not missing
     else:
-        raw_cond = substitute(step.get("cond"), src)
+        raw_cond = engine.substitutor.substitute(step.get("cond"), src)
         cond_val = bool(raw_cond)
 
     branch_key = "then" if cond_val else "else"
@@ -43,11 +42,11 @@ def op_if(
     if not actions:
         return dest
 
-    actions_norm = normalize_actions(actions)
+    actions_norm = engine.normalize_actions(actions)
     snapshot = copy.deepcopy(dest)
 
     try:
-        return apply_actions(actions_norm, dest=dest, source=src)
+        return engine.apply_actions(actions_norm, dest=dest, source=src)
     except Exception:
         dest.clear()
         dest.update(snapshot)

j_perm/ops/copy.py

@@ -4,23 +4,23 @@ import copy
 from typing import MutableMapping, Any, Mapping
 
 from .set import op_set
-from ..registry import register_op
+from ..op_handler import OpRegistry
 from ..utils.pointers import maybe_slice
-from ..utils.subst import substitute
 
 
-@register_op("copy")
+@OpRegistry.register("copy")
 def op_copy(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any],
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Copy value from source pointer into dest path."""
-    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))
 
-    ptr = substitute(step["from"], src)
+    ptr = engine.substitutor.substitute(step["from"], src)
     ignore = bool(step.get("ignore_missing", False))
 
     try:

j_perm/ops/copy_d.py

@@ -4,22 +4,22 @@ import copy
 from typing import MutableMapping, Any, Mapping
 
 from .set import op_set
-from ..registry import register_op
+from ..op_handler import OpRegistry
 from ..utils.pointers import maybe_slice
-from ..utils.subst import substitute
 
 
-@register_op("copyD")
+@OpRegistry.register("copyD")
 def op_copy_d(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any],
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Copy value from dest (self) into another dest path."""
-    path = substitute(step["path"], src)
+    path = engine.substitutor.substitute(step["path"], src)
     create = bool(step.get("create", True))
 
-    ptr = substitute(step["from"], dest)
+    ptr = engine.substitutor.substitute(step["from"], dest)
     ignore = bool(step.get("ignore_missing", False))
 
     try:

j_perm/ops/delete.py

@@ -2,19 +2,19 @@ from __future__ import annotations
 
 from typing import MutableMapping, Any, Mapping
 
-from ..registry import register_op
+from ..op_handler import OpRegistry
 from ..utils.pointers import jptr_ensure_parent
-from ..utils.subst import substitute
 
 
-@register_op("delete")
+@OpRegistry.register("delete")
 def op_delete(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any],
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Delete node at the given JSON Pointer path in dest."""
-    path = substitute(step["path"], src)
+    path = engine.substitutor.substitute(step["path"], src)
     ignore = bool(step.get("ignore_missing", True))
 
     try:

j_perm/ops/distinct.py

@@ -2,26 +2,26 @@ from __future__ import annotations
 
 from typing import MutableMapping, Any, Mapping
 
-from ..registry import register_op
+from ..op_handler import OpRegistry
 from ..utils.pointers import jptr_get
-from ..utils.subst import substitute
 
 
-@register_op("distinct")
+@OpRegistry.register("distinct")
 def op_distinct(
         step: dict,
         dest: MutableMapping[str, Any],
         src: Mapping[str, Any],
+        engine: "ActionEngine",
 ) -> MutableMapping[str, Any]:
     """Remove duplicates from a list at the given path, preserving order."""
-    path = substitute(step["path"], src)
+    path = engine.substitutor.substitute(step["path"], src)
     lst = jptr_get(dest, path)
 
     if not isinstance(lst, list):
         raise TypeError(f"{path} is not a list (distinct)")
 
     key = step.get("key", None)
-    key_path = substitute(key, src)
+    key_path = engine.substitutor.substitute(key, src)
 
     seen = set()
     unique = []