j-perm 0.1.3.1__py3-none-any.whl

j_perm/__init__.py

@@ -0,0 +1,13 @@
+# Import built-in operations so that they register on import.
+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
+
+__all__ = [
+    "Handler",
+    "register_op",
+    "apply_actions",
+    "normalize_actions",
+    "build_schema",
+]

j_perm/engine.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import copy
+from typing import Any, List, Mapping, MutableMapping, Union
+
+from .registry import get_handler
+from .utils.tuples import tuples_to_lists
+
+
+def _is_pointer_string(v: Any) -> bool:
+    return isinstance(v, str) and v.startswith("/")
+
+
+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:
+                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))
+            else:
+                out.append(item)
+        return out
+
+    if isinstance(spec, Mapping):
+        return _expand_shorthand(spec)
+
+    raise TypeError("spec must be dict or list")
+
+
+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)

j_perm/jmes_ext.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import jmespath
+from jmespath import functions as _jp_funcs
+
+
+class _UserFunctions(_jp_funcs.Functions):
+    """Container for custom JMESPath functions used by the DSL."""
+
+    @_jp_funcs.signature({'types': ['number']}, {'types': ['number']})
+    def _func_subtract(self, a: float, b: float) -> float:
+        """JMESPath function that subtracts two numbers (a - b)."""
+        return a - b
+
+
+USER_FUNCTIONS = _UserFunctions()
+JP_OPTIONS = jmespath.Options(custom_functions=USER_FUNCTIONS)

j_perm/ops/__init__.py

@@ -0,0 +1,10 @@
+from ._exec import op_exec
+from ._if import op_if
+from .copy import op_copy
+from .copy_d import op_copy_d
+from .delete import op_delete
+from .distinct import op_distinct
+from .foreach import op_foreach
+from .replace_root import op_replace_root
+from .set import op_set
+from .update import op_update

j_perm/ops/_exec.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import MutableMapping, Any, Mapping
+
+from ..registry import register_op
+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")
+def op_exec(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+) -> MutableMapping[str, Any]:
+    """Execute nested actions stored either in source or inline in the op."""
+    has_from = "from" in step
+    has_actions = "actions" in step
+
+    if has_from and has_actions:
+        raise ValueError("exec operation cannot have both 'from' and 'actions' parameters")
+
+    if not has_from and not has_actions:
+        raise ValueError("exec operation requires either 'from' or 'actions' parameter")
+
+    if has_from:
+        actions_ptr = substitute(step["from"], src)
+        try:
+            actions = maybe_slice(actions_ptr, src)
+        except Exception:
+            if "default" in step:
+                actions = resolve_special(step["default"], src)
+                if isinstance(actions, (str, list, dict)):
+                    actions = substitute(actions, src)
+            else:
+                raise ValueError(f"Cannot find actions at {actions_ptr}")
+    else:
+        actions = resolve_special(step["actions"], src)
+        if isinstance(actions, (str, list, dict)):
+            actions = substitute(actions, src)
+
+    merge = bool(step.get("merge", False))
+
+    if merge:
+        result = apply_actions(actions, dest=dest, source=src)
+        return result
+    else:
+        result = apply_actions(actions, dest={}, source=src)
+        dest.clear()
+        if isinstance(dest, list):
+            dest.extend(result)  # type: ignore[arg-type]
+        else:
+            dest.update(result)  # type: ignore[arg-type]
+        return dest

j_perm/ops/_if.py

@@ -0,0 +1,54 @@
+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 ..utils.pointers import maybe_slice
+from ..utils.subst import substitute
+
+
+@register_op("if")
+def op_if(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any] | list,
+) -> MutableMapping[str, Any]:
+    """Conditionally execute nested actions based on a path or expression."""
+    if "path" in step:
+        try:
+            ptr = substitute(step["path"], src)
+            current = maybe_slice(ptr, dest)
+            missing = False
+        except Exception:
+            current = None
+            missing = True
+
+        if "equals" in step:
+            expected = 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)
+        cond_val = bool(raw_cond)
+
+    branch_key = "then" if cond_val else "else"
+    branch_key = branch_key if branch_key in step else "do" if cond_val else None
+    actions = step.get(branch_key)
+
+    if not actions:
+        return dest
+
+    actions_norm = normalize_actions(actions)
+    snapshot = copy.deepcopy(dest)
+
+    try:
+        return apply_actions(actions_norm, dest=dest, source=src)
+    except Exception:
+        dest.clear()
+        dest.update(snapshot)
+        raise

j_perm/ops/assert.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import MutableMapping, Any, Mapping
+
+from ..registry import register_op
+from ..utils.pointers import jptr_get
+from ..utils.subst import substitute
+
+
+@register_op("assert")
+def op_assert(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+) -> MutableMapping[str, Any]:
+    """Assert node existence and/or value at JSON Pointer path in dest."""
+    path = substitute(step["path"], src)
+
+    try:
+        current = jptr_get(dest, path)
+    except Exception:
+        raise AssertionError(f"{path} does not exist")
+
+    if "equals" in step and current != step["equals"]:
+        raise AssertionError(f"{path} != {step['equals']!r}")
+
+    return dest

j_perm/ops/copy.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import copy
+from typing import MutableMapping, Any, Mapping
+
+from .set import op_set
+from ..registry import register_op
+from ..utils.pointers import maybe_slice
+from ..utils.subst import substitute
+
+
+@register_op("copy")
+def op_copy(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+) -> MutableMapping[str, Any]:
+    """Copy value from source pointer into dest path."""
+    path = substitute(step["path"], src)
+    create = bool(step.get("create", True))
+    extend_list = bool(step.get("extend", True))
+
+    ptr = substitute(step["from"], src)
+    ignore = bool(step.get("ignore_missing", False))
+
+    try:
+        value = copy.deepcopy(maybe_slice(ptr, src))
+    except Exception:
+        if "default" in step:
+            value = copy.deepcopy(step["default"])
+        elif ignore:
+            return dest
+        else:
+            raise
+
+    return op_set(
+        {"op": "set", "path": path, "value": value, "create": create, "extend": extend_list},
+        dest,
+        src,
+    )

j_perm/ops/copy_d.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import copy
+from typing import MutableMapping, Any, Mapping
+
+from .set import op_set
+from ..registry import register_op
+from ..utils.pointers import maybe_slice
+from ..utils.subst import substitute
+
+
+@register_op("copyD")
+def op_copy_d(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+) -> MutableMapping[str, Any]:
+    """Copy value from dest (self) into another dest path."""
+    path = substitute(step["path"], src)
+    create = bool(step.get("create", True))
+
+    ptr = substitute(step["from"], dest)
+    ignore = bool(step.get("ignore_missing", False))
+
+    try:
+        value = copy.deepcopy(maybe_slice(ptr, dest))
+    except Exception:
+        if "default" in step:
+            value = copy.deepcopy(step["default"])
+        elif ignore:
+            return dest
+        else:
+            raise
+
+    return op_set({"op": "set", "path": path, "value": value, "create": create}, dest, src)

j_perm/ops/delete.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import MutableMapping, Any, Mapping
+
+from ..registry import register_op
+from ..utils.pointers import jptr_ensure_parent
+from ..utils.subst import substitute
+
+
+@register_op("delete")
+def op_delete(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+) -> MutableMapping[str, Any]:
+    """Delete node at the given JSON Pointer path in dest."""
+    path = substitute(step["path"], src)
+    ignore = bool(step.get("ignore_missing", True))
+
+    try:
+        parent, leaf = jptr_ensure_parent(dest, path, create=False)
+
+        if leaf == "-":
+            raise ValueError("'-' not allowed in delete")
+
+        if isinstance(parent, list):
+            del parent[int(leaf)]
+        else:
+            del parent[leaf]
+
+    except (KeyError, IndexError):
+        if not ignore:
+            raise
+
+    return dest

j_perm/ops/distinct.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import MutableMapping, Any, Mapping
+
+from ..registry import register_op
+from ..utils.pointers import jptr_get
+from ..utils.subst import substitute
+
+
+@register_op("distinct")
+def op_distinct(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+) -> MutableMapping[str, Any]:
+    """Remove duplicates from a list at the given path, preserving order."""
+    path = 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)
+
+    seen = set()
+    unique = []
+    for item in lst:
+        if key is not None:
+            filter_item = jptr_get(item, key_path)
+        else:
+            filter_item = item
+
+        if filter_item not in seen:
+            seen.add(filter_item)
+            unique.append(item)
+
+    lst[:] = unique
+    return dest

j_perm/ops/foreach.py

@@ -0,0 +1,56 @@
+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 ..utils.pointers import maybe_slice
+from ..utils.subst import substitute
+
+
+@register_op("foreach")
+def op_foreach(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any] | list,
+) -> MutableMapping[str, Any]:
+    """Iterate over array in source and execute nested actions for each element."""
+    arr_ptr = substitute(step["in"], src)
+
+    default = copy.deepcopy(step.get("default", []))
+    skip_empty = bool(step.get("skip_empty", True))
+
+    try:
+        arr = maybe_slice(arr_ptr, src)
+    except Exception:
+        arr = default
+
+    if not arr and skip_empty:
+        return dest
+
+    if isinstance(arr, dict):
+        arr = list(arr.items())
+
+    var = step.get("as", "item")
+    body = normalize_actions(step["do"])
+    snapshot = copy.deepcopy(dest)
+
+    try:
+        for elem in arr:
+            if isinstance(src, Mapping):
+                extended = dict(src)
+            else:
+                extended = {"_": src}
+
+            extended[var] = elem
+            dest = apply_actions(body, dest=dest, source=extended)
+    except Exception:
+        dest.clear()
+        if isinstance(dest, list):
+            dest = snapshot
+        else:
+            dest.update(snapshot)
+        raise
+
+    return dest

j_perm/ops/replace_root.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import copy
+
+from ..registry import register_op
+from ..utils.special import resolve_special
+from ..utils.subst import substitute
+
+
+@register_op("replace_root")
+def op_replace_root(step, dest, src):
+    """Replace the whole dest root value with the resolved special value."""
+    value = resolve_special(step["value"], src)
+    if isinstance(value, (str, list, dict)):
+        value = substitute(value, src)
+    return copy.deepcopy(value)

j_perm/ops/set.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, MutableMapping
+
+from ..registry import register_op
+from ..utils.pointers import jptr_ensure_parent
+from ..utils.special import resolve_special
+from ..utils.subst import substitute
+
+
+@register_op("set")
+def op_set(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+) -> MutableMapping[str, Any]:
+    """Set or append a value at JSON Pointer path in dest."""
+    path = substitute(step["path"], src)
+    create = bool(step.get("create", True))
+    extend_list = bool(step.get("extend", True))
+
+    value = resolve_special(step["value"], src)
+    if isinstance(value, (str, list, Mapping)):
+        value = substitute(value, src)
+
+    parent, leaf = jptr_ensure_parent(dest, path, create=create)
+
+    if leaf == "-":
+        if not isinstance(parent, list):
+            if create:
+                grand, last = jptr_ensure_parent(dest, path.rsplit("/", 1)[0], create=True)
+                if not isinstance(grand[last], list):
+                    if grand[last] == {}:
+                        grand[last] = []
+                    else:
+                        grand[last] = [grand[last]]
+                parent = grand[last]
+            else:
+                raise TypeError(f"{path} is not a list (append)")
+
+        if isinstance(value, list) and extend_list:
+            parent.extend(value)
+        else:
+            parent.append(value)
+    else:
+        if isinstance(parent, list):
+            idx = int(leaf)
+            if idx >= len(parent):
+                if create:
+                    while idx >= len(parent):
+                        parent.append(None)
+                else:
+                    raise IndexError(f"{path}: index {idx} out of range")
+            parent[idx] = value
+        else:
+            parent[leaf] = value
+
+    return dest

j_perm/ops/update.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import copy
+from typing import MutableMapping, Any, Mapping
+
+from ..registry import register_op
+from ..utils.pointers import maybe_slice, jptr_ensure_parent
+from ..utils.special import resolve_special
+from ..utils.subst import substitute
+
+
+@register_op("update")
+def op_update(
+        step: dict,
+        dest: MutableMapping[str, Any],
+        src: Mapping[str, Any],
+) -> MutableMapping[str, Any]:
+    """Update a mapping at the given path using a mapping from source or inline value."""
+    path = 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)
+        try:
+            update_value = copy.deepcopy(maybe_slice(ptr, src))
+        except Exception:
+            if "default" in step:
+                update_value = copy.deepcopy(step["default"])
+            else:
+                raise
+    elif "value" in step:
+        update_value = resolve_special(step["value"], src)
+        if isinstance(update_value, (str, list, Mapping)):
+            update_value = substitute(update_value, src)
+    else:
+        raise ValueError("update operation requires either 'from' or 'value' parameter")
+
+    if not isinstance(update_value, Mapping):
+        raise TypeError(f"update value must be a dict, got {type(update_value).__name__}")
+
+    parent, leaf = jptr_ensure_parent(dest, path, create=create)
+
+    if leaf:
+        if isinstance(parent, list):
+            idx = int(leaf)
+            target = parent[idx]
+        else:
+            if leaf not in parent:
+                if create:
+                    parent[leaf] = {}
+                else:
+                    raise KeyError(f"{path} does not exist")
+            target = parent[leaf]
+    else:
+        target = dest
+
+    if not isinstance(target, MutableMapping):
+        raise TypeError(f"{path} is not a dict, cannot update")
+
+    if deep:
+        def deep_update(dst: MutableMapping, src_val: Mapping) -> None:
+            for key, value in src_val.items():
+                if key in dst and isinstance(dst[key], MutableMapping) and isinstance(value, Mapping):
+                    deep_update(dst[key], value)  # type: ignore[index]
+                else:
+                    dst[key] = copy.deepcopy(value)
+
+        deep_update(target, update_value)
+    else:
+        target.update(update_value)
+
+    return dest

j_perm/registry.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, MutableMapping, Mapping, TypeAlias
+
+Handler: TypeAlias = Callable[
+    [dict, MutableMapping[str, Any], Mapping[str, Any]],
+    MutableMapping[str, Any],
+]
+
+_OP_HANDLERS: Dict[str, Handler] = {}
+
+
+def register_op(name: str) -> Callable[[Handler], Handler]:
+    """Decorator that registers a DSL operation handler under a given name."""
+
+    def decorator(func: Handler) -> Handler:
+        if name in _OP_HANDLERS:
+            raise ValueError(f"Handler for op '{name}' is already registered")
+        _OP_HANDLERS[name] = func
+        return func
+
+    return decorator
+
+
+def get_handler(name: str) -> Handler:
+    """Return a registered handler or raise ValueError if it does not exist."""
+    try:
+        return _OP_HANDLERS[name]
+    except KeyError:
+        raise ValueError(f"Unknown op '{name}'") from None