j-perm 0.2.0.1__py3-none-any.whl → 0.2.1.1__py3-none-any.whl

j_perm/__init__.py

@@ -3,19 +3,23 @@ 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 . import shorthands as _builtin_shorthands  # noqa: F401
 from .engine import apply_actions, ActionEngine
-from .subst import JpFuncRegistry, CasterRegistry, TemplateSubstitutor
+from .normalizer import Normalizer, ShorthandRegistry
 from .op_handler import OpRegistry, Handlers
 from .special_resolver import SpecialRegistry, SpecialResolver
+from .subst import JpFuncRegistry, CasterRegistry, TemplateSubstitutor
 
 __all__ = [
     "apply_actions",
     "ActionEngine",
-    "JpFuncRegistry",
-    "CasterRegistry",
-    "TemplateSubstitutor",
+    "Normalizer",
+    "ShorthandRegistry",
     "OpRegistry",
     "Handlers",
     "SpecialRegistry",
     "SpecialResolver",
+    "JpFuncRegistry",
+    "CasterRegistry",
+    "TemplateSubstitutor",
 ]

j_perm/constructs/eval.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Mapping, Any
 
-from j_perm.special_resolver import SpecialRegistry
+from ..special_resolver import SpecialRegistry
 
 
 @SpecialRegistry.register("$eval")

j_perm/constructs/ref.py

@@ -3,8 +3,8 @@ 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
+from ..special_resolver import _MISSING, SpecialRegistry
+from ..utils.pointers import maybe_slice
 
 
 @SpecialRegistry.register("$ref")

j_perm/engine.py

@@ -4,6 +4,7 @@ import copy
 from dataclasses import dataclass, field
 from typing import Any, List, Mapping, TypeAlias, MutableMapping, Union
 
+from .normalizer import Normalizer
 from .op_handler import Handlers
 from .special_resolver import SpecialResolver
 from .subst import TemplateSubstitutor
@@ -17,14 +18,6 @@ JsonLikeDest: TypeAlias = Union[MutableMapping[str, Any], List[Any]]
 # Small utilities
 # =============================================================================
 
-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 tuples_to_lists(obj: Any) -> Any:
     """Recursively convert all tuples into lists so JMESPath indexers work reliably."""
     if isinstance(obj, tuple):
@@ -48,22 +41,13 @@ class ActionEngine:
       - 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
+      - normalizer: a Normalizer (for shorthand expansion)
     """
 
     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
+    normalizer: Normalizer = field(default_factory=Normalizer)
 
     def apply_actions(
             self,
@@ -107,46 +91,16 @@ class ActionEngine:
             out: List[dict] = []
             for item in spec:
                 if isinstance(item, Mapping) and "op" not in item:
-                    out.extend(self._expand_shorthand(item))
+                    out.extend(self.normalizer.expand_shorthand(item))
                 else:
                     out.append(item)
             return out
 
         if isinstance(spec, Mapping):
-            return self._expand_shorthand(spec)
+            return self.normalizer.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": "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:
-                steps.append({"op": "set", "path": dst, "value": val})
-
-        return steps
-
 
 # Create a default engine instance for convenience
 default_engine = ActionEngine()

j_perm/funcs/subtract.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from jmespath import functions as _jp_funcs
 
-from j_perm.subst import JpFuncRegistry
+from ..subst import JpFuncRegistry
 
 
 @JpFuncRegistry.register("subtract")

j_perm/normalizer.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Optional, List
+
+ExpandResult = Optional[List[dict]]
+Rule = Callable[[str, Any], ExpandResult]
+
+
+class ShorthandRegistry:
+    _rules: dict[str, Rule] = {}
+    _default_priority: dict[str, int] = {}  # name -> order (10, 5, 0, -5, -10...)
+
+    @classmethod
+    def register(cls, name: str, *, priority: int = 0):
+        def deco(fn: Rule) -> Rule:
+            if name in cls._rules:
+                raise ValueError(f"shorthand rule already registered: {name!r}")
+            cls._rules[name] = fn
+            cls._default_priority[name] = priority
+            return fn
+        return deco
+
+    @classmethod
+    def ordered(
+            cls,
+            rules: Mapping[str, Rule] | None = None,
+            *,
+            priority: Mapping[str, int] | None = None,
+    ) -> list[Rule]:
+        rules = dict(cls._rules if rules is None else rules)
+
+        _priority = dict(cls._default_priority)
+        if priority:
+            _priority.update(priority)
+
+        names = sorted(
+            rules.keys(),
+            key=lambda n: (_priority.get(n, 0), n),
+            reverse=True,
+        )
+        return [rules[n] for n in names]
+
+    @classmethod
+    def get(cls, name: str) -> Rule:
+        try:
+            return cls._rules[name]
+        except KeyError:
+            raise ValueError(f"Unknown rule {name!r}") from None
+
+    @classmethod
+    def all(cls) -> dict[str, Rule]:
+        return dict(cls._rules)
+
+
+@dataclass(slots=True)
+class Normalizer:
+    rules: list[str] | Mapping[str, Rule] | None = None
+    priority: Mapping[str, int] | None = None
+
+    _rules: list[Rule] = field(init=False)
+
+    def __post_init__(self) -> None:
+        if self.rules is None:
+            rules = ShorthandRegistry.all()
+        elif isinstance(self.rules, Mapping):
+            rules = dict(self.rules)
+        else:
+            all_rules = ShorthandRegistry.all()
+            rules = {}
+            for n in self.rules:
+                if n not in all_rules:
+                    raise ValueError(f"Unknown rule {n!r}")
+                rules[n] = all_rules[n]
+
+        self._rules = ShorthandRegistry.ordered(rules, priority=self.priority)
+
+    def expand_shorthand(self, obj: Mapping[str, Any]) -> List[dict]:
+        steps: List[dict] = []
+        for k, v in obj.items():
+            for rule in self._rules:
+                out = rule(k, v)
+                if out is not None:
+                    steps.extend(out)
+                    break
+            else:
+                raise ValueError(f"Unhandled shorthand key: {k!r}")
+        return steps

j_perm/ops/__init__.py

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

j_perm/ops/_assert.py

@@ -17,11 +17,11 @@ def op_assert(
     path = engine.substitutor.substitute(step["path"], src)
 
     try:
-        current = jptr_get(dest, path)
+        current = jptr_get(src, path)
     except Exception:
-        raise AssertionError(f"{path} does not exist")
+        raise AssertionError(f"'{path}' does not exist in source")
 
     if "equals" in step and current != step["equals"]:
-        raise AssertionError(f"{path} != {step['equals']!r}")
+        raise AssertionError(f"'{path}' != '{step['equals']!r}'")
 
     return dest

j_perm/ops/_assert_d.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import MutableMapping, Any, Mapping
+
+from ..op_handler import OpRegistry
+from ..utils.pointers import jptr_get
+
+
+@OpRegistry.register("assertD")
+def op_assert_d(
+        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 = engine.substitutor.substitute(step["path"], dest)
+
+    try:
+        current = jptr_get(dest, path)
+    except Exception:
+        raise AssertionError(f"'{path}' does not exist in destination")
+
+    if "equals" in step and current != step["equals"]:
+        raise AssertionError(f"'{path}' != '{step['equals']!r}'")
+
+    return dest

j_perm/ops/_exec.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 from typing import MutableMapping, Any, Mapping
 
 from ..op_handler import OpRegistry
-from ..engine import apply_actions
 from ..utils.pointers import maybe_slice
 
 
@@ -43,10 +42,10 @@ def op_exec(
     merge = bool(step.get("merge", False))
 
     if merge:
-        result = apply_actions(actions, dest=dest, source=src)
+        result = engine.apply_actions(actions, dest=dest, source=src)
         return result
     else:
-        result = apply_actions(actions, dest={}, source=src)
+        result = engine.apply_actions(actions, dest={}, source=src)
         dest.clear()
         if isinstance(dest, list):
             dest.extend(result)  # type: ignore[arg-type]

j_perm/shorthands/__init__.py

@@ -0,0 +1,3 @@
+from ._assert import rule_assert
+from .assign_or_append import rule_assign_or_append
+from .delete import rule_delete

j_perm/shorthands/_assert.py

@@ -0,0 +1,17 @@
+from collections.abc import Mapping
+from typing import Any
+
+from ..normalizer import ShorthandRegistry, ExpandResult
+
+
+@ShorthandRegistry.register("assert")
+def rule_assert(key: str, val: Any) -> ExpandResult:
+    if key != "~assert" and key != "~assertD":
+        return None
+    if key == "~assertD":
+        op = "assertD"
+    else:
+        op = "assert"
+    if isinstance(val, Mapping):
+        return [{"op": op, "path": p, "equals": eq} for p, eq in val.items()]
+    return [{"op": op, "path": p} for p in (val if isinstance(val, list) else [val])]

j_perm/shorthands/assign_or_append.py

@@ -0,0 +1,17 @@
+from typing import Any
+
+from ..normalizer import ExpandResult, ShorthandRegistry
+
+
+@ShorthandRegistry.register("assign_or_append", priority=-1)
+def rule_assign_or_append(key: str, val: Any) -> ExpandResult:
+    # Fallback rule: handles:
+    # - append shorthand: field[] -> "/field/-"
+    # - pointer assignment -> copy
+    # - literal assignment -> set
+    append = key.endswith("[]")
+    dst = f"{key[:-2]}/-" if append else key
+
+    if isinstance(val, str) and val.startswith("/"):
+        return [{"op": "copy", "from": val, "path": dst, "ignore_missing": True}]
+    return [{"op": "set", "path": dst, "value": val}]

j_perm/shorthands/delete.py

@@ -0,0 +1,10 @@
+from typing import Any
+
+from ..normalizer import ShorthandRegistry, ExpandResult
+
+
+@ShorthandRegistry.register("delete")
+def rule_delete(key: str, val: Any) -> ExpandResult:
+    if key != "~delete":
+        return None
+    return [{"op": "delete", "path": p} for p in (val if isinstance(val, list) else [val])]

{j_perm-0.2.0.1.dist-info → j_perm-0.2.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: j-perm
-Version: 0.2.0.1
+Version: 0.2.1.1
 Summary: json permutation library
 Author-email: Roman <kuschanow@gmail.com>
 License: MIT
@@ -84,11 +84,13 @@ Typical setup:
 substitutor = TemplateSubstitutor()
 special = SpecialResolver()
 handlers = Handlers()
+normalizer = Normalizer()
 
 engine = ActionEngine(
   handlers=handlers,
   special=special,
   substitutor=substitutor,
+  normalizer=normalizer,
 )
 ```
 
@@ -676,59 +678,103 @@ Update a mapping at `path` using either source mapping (`from`) or inline mappin
 
 ---
 
-## Shorthand expansion (built-in)
+## Shorthand normalization
 
-Normalization expands shorthand syntax into explicit operation steps:
+In addition to explicit DSL steps, J-Perm supports a *shorthand syntax* for more concise scripts.
+Shorthand forms are expanded into regular operation steps **before execution**.
 
-### `~delete`
+Shorthand expansion is implemented as a pluggable normalization layer, similar to operations and special constructs.
+
+### How it works
+
+During normalization, each mapping entry is processed by a chain of registered *shorthand rules*:
+
+1. Each rule decides whether it can handle a given `(key, value)` pair.
+2. If a rule matches, it expands the entry into one or more explicit operation steps.
+3. The first matching rule wins.
+4. If no rule matches, normalization fails with an error.
+
+The resulting list of steps is then executed by the engine as a normal DSL script.
+
+---
+
+### Built-in shorthand rules
+
+The following shorthand forms are enabled by default.
+
+#### Delete shorthand (`~delete`)
 
 ```json
 { "~delete": ["/a", "/b"] }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "delete", "path": "/a" }
 { "op": "delete", "path": "/b" }
 ```
 
-### `~assert`
+---
+
+#### Assert shorthand (`~assert`)
+
+Mapping form:
 
 ```json
-{ "~assert": { "/x": 10 } }
+{ "~assert": { "/x": 10, "/y": 20 } }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "assert", "path": "/x", "equals": 10 }
+{ "op": "assert", "path": "/y", "equals": 20 }
 ```
 
-### `field[]` append
+List / string form:
+
+```json
+{ "~assert": ["/x", "/y"] }
+```
+
+Expands into existence-only assertions.
+
+---
+
+#### Append shorthand (`field[]`)
+
+A key ending with `[]` means *append to a list* at that path:
 
 ```json
 { "items[]": 123 }
 ```
 
-→
+Expands into:
 
 ```json
 { "op": "set", "path": "/items/-", "value": 123 }
 ```
 
-### pointer assignment
+---
+
+#### Pointer assignment shorthand
 
-If a value is a string that starts with `/`, it becomes a `copy`:
+If a value is a string that starts with `/`, it is treated as a source pointer:
 
 ```json
 { "name": "/user/fullName" }
 ```
 
-→
+Expands into:
 
 ```json
-{ "op": "copy", "from": "/user/fullName", "path": "/name", "ignore_missing": true }
+{
+  "op": "copy",
+  "from": "/user/fullName",
+  "path": "/name",
+  "ignore_missing": true
+}
 ```
 
 ---
@@ -798,6 +844,21 @@ ${json:/raw_payload}
 
 ---
 
+### Custom shorthand rules
+
+```python
+from j_perm import ShorthandRegistry, ExpandResult
+
+@ShorthandRegistry.register("name", priority=10)
+def my_shorthand_rule(key: str, value: Any) -> ExpandResult | None:
+    if key.startswith("my_prefix_"):
+        # expand into steps
+        steps = [ ... ]
+        return steps
+```
+
+---
+
 ## Plugin loading
 
 Registries collect definitions **at import time**.

{j_perm-0.2.0.1.dist-info → j_perm-0.2.1.1.dist-info}/RECORD

@@ -1,5 +1,6 @@
-j_perm/__init__.py,sha256=RUpTLecqmkXgyy91s8DHNMEStW4almMYGHTJMmLR5NY,714
-j_perm/engine.py,sha256=xKSokxnkuVUyGZcsC1F88xzBw3vLpPPPUD1iHYKuKsI,5562
+j_perm/__init__.py,sha256=81aLdcmlUg51R6xR-VXVDDUeM87ezy3ZuiLpblHZ_wk,873
+j_perm/engine.py,sha256=iaUxB7EWcqvWsP4Z8z49a6-atX9br1tTC-WlZVrVo-A,3923
+j_perm/normalizer.py,sha256=50pff5j3sTrCu2Fp_SW6m99qwt88CladpYlWpQ3c-ac,2671
 j_perm/op_handler.py,sha256=h28thz_18DwZTb9IZtTd6kfsZj7hN4UsmU4uf3aMYpo,1649
 j_perm/special_resolver.py,sha256=khRVWXrE3Vch1gbxsfFwj9JQ37pZ-_ojMeh-G2Vv7bs,4032
 j_perm/subst.py,sha256=oW21Gs2nTEQLcOC_xMKzeuZFtfNvnB2QZAIWl7U4TSg,9802
@@ -9,13 +10,14 @@ j_perm/casters/_float.py,sha256=C4r-h6zbkjmQnoEdE2RDMhSkW9oGrvxbQngJZ2T7_tU,153
 j_perm/casters/_int.py,sha256=f1BKqsULiG6Puov1qcGS_inSnv0hZtQ0deQEMP0v0i4,145
 j_perm/casters/_str.py,sha256=v1_BD1_hPbOtvO5CKYAlNEGbMhpR56eKCnV2a2Q4kGU,145
 j_perm/constructs/__init__.py,sha256=TTUPSMyvj8HSfPikrFqXaFsechc9aOIbjtVjy4TOolE,50
-j_perm/constructs/eval.py,sha256=ZckFMcerRWnu-51WAEdm35kuO7t_EzqvtiCAgVWDsjQ,457
-j_perm/constructs/ref.py,sha256=eUrRCanKAEWZ98jOAHNhjs5UhXNAm17NWd4Cbus_cyY,654
+j_perm/constructs/eval.py,sha256=UzjZK27UAzsl3s26Y3RWBPhuKX1Az0fK6xk-cgpS8pQ,452
+j_perm/constructs/ref.py,sha256=GtR2hpENev9k1lsx3mHGM8956vBfrPUgHm3IydYr-_I,644
 j_perm/funcs/__init__.py,sha256=8yIafxhCH5B7jXrsautQEtl4Qt8RcUK7IWNniORj9ow,31
-j_perm/funcs/subtract.py,sha256=0UW3McKL7VDPVj0UwfvZlrSXGs1uQ6yIdLz5rPqa7bY,293
-j_perm/ops/__init__.py,sha256=G4j6MGnEVnHSeJIBwrpV9oMk7s_djlEaOmLRW_4IEEo,329
-j_perm/ops/_assert.py,sha256=l07DjqsMbvoTDzLbVVcMciblYw8O4D6gBwPt3yFKPhs,758
-j_perm/ops/_exec.py,sha256=-esjfF2te1NvkclrJJ9lGU7YdwY_15vuxMihG08HhQM,1934
+j_perm/funcs/subtract.py,sha256=8W49TsrnIU4EVjS8tWQY2GXlX2nAaQ1O9O1JlrVYdIw,288
+j_perm/ops/__init__.py,sha256=j_U4Aq0iwEvZOF0jqMmlQA0NisJsHNJWzqkfyMWuHFA,364
+j_perm/ops/_assert.py,sha256=O7MFxW3FDCglPMx-tBwi67k2Wd-Mds996AQdeGLbM6Q,773
+j_perm/ops/_assert_d.py,sha256=xEjqBryCbzBpkzYhwRZht7-uyXv7XaCkEcRt6sjwE7k,783
+j_perm/ops/_exec.py,sha256=HaFy__49QXnxYNbh1IdIu8ZQoWlQsrms5HgyRN5lV6o,1913
 j_perm/ops/_if.py,sha256=DNYp0j3-3YYMIR_CcDM3Ai0CpW2Qt4SYtKxk-9onu8c,1590
 j_perm/ops/copy.py,sha256=fV2rE92JyTRqo91GjXwWucklDR1T1ZcFHHbxG1F8S9g,1110
 j_perm/ops/copy_d.py,sha256=2SGHoq4vaD79diJos_oO3pvZvC_XrQorxhXAgZ5l09E,1017
@@ -26,9 +28,13 @@ j_perm/ops/replace_root.py,sha256=FFyc-95n3kTzcOXrnjwDdvwOnKNitXKb_1F25MMnXd8,44
 j_perm/ops/set.py,sha256=-kFFgHxeq65K5vLzDe6PhUoLT-ksoZYUVL1Jxf8bRA0,1882
 j_perm/ops/update.py,sha256=gvJTh3vS4zD-lpaqN23w5OO3hTtkSdu8RPy0V8r8Rwg,2471
 j_perm/schema/__init__.py,sha256=mhEbGdi1MgLeEm1IL8-tkTtbIdrdlvQi22sBr7vCUqg,3392
+j_perm/shorthands/__init__.py,sha256=zvsu15iExYtUrct6Ob4IRs6Ao46PoZaCKVIUhMBY4Dk,117
+j_perm/shorthands/_assert.py,sha256=iRvuUGlN5Bj9G5Bo-aXUa4MQujgmrR3N-PhDeee6xcY,555
+j_perm/shorthands/assign_or_append.py,sha256=TsSzaQXb5qoKtY6tvx_skHob-695Zii5roUfXltznAQ,621
+j_perm/shorthands/delete.py,sha256=PZeTRcP6-Q3SdbdyruWWXtMJ9mTnz1CBCHiOpHNI06Q,311
 j_perm/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 j_perm/utils/pointers.py,sha256=X1HSCag4t-qq5zTvBMRAlBKXwpHVNNZYJrdJRtyEr4g,2788
-j_perm-0.2.0.1.dist-info/METADATA,sha256=5ptvJzqqqub2rmZpl33SR6Pv-IALMA9AFwlfnCEcNWw,16143
-j_perm-0.2.0.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-j_perm-0.2.0.1.dist-info/top_level.txt,sha256=yveBxREqVn9DliNwmen1QWoxR0uta7bU5giS1CCffRI,7
-j_perm-0.2.0.1.dist-info/RECORD,,
+j_perm-0.2.1.1.dist-info/METADATA,sha256=zwwrX08mxWxT5sMGLkh4PaLBVs7FMspDzwhcqj8sfpg,17660
+j_perm-0.2.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+j_perm-0.2.1.1.dist-info/top_level.txt,sha256=yveBxREqVn9DliNwmen1QWoxR0uta7bU5giS1CCffRI,7
+j_perm-0.2.1.1.dist-info/RECORD,,