j-perm 0.1.2__tar.gz → 0.1.3.1__tar.gz

j_perm-0.1.3.1/PKG-INFO

@@ -0,0 +1,766 @@
+Metadata-Version: 2.4
+Name: j-perm
+Version: 0.1.3.1
+Summary: jsom permutation library
+Author-email: Roman <kuschanow@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kuschanow/j-perm
+Project-URL: Source, https://github.com/kuschanow/j-perm
+Project-URL: Tracker, https://github.com/kuschanow/j-perm/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: jmespath
+
+# J-Perm
+
+A small, composable JSON-transformation DSL implemented in Python.
+
+The library lets you describe transformations as **data** (a list of steps) and then apply them to an input document. It supports JSON Pointer paths, custom JMESPath expressions, interpolation with `${...}` syntax, special reference/evaluation values, and a rich set of built-in operations.
+
+---
+
+## Features
+
+* JSON Pointer read/write with support for:
+
+    * root pointers (`""`, `"/"`, `"."`)
+    * relative `..` segments
+    * list slices like `/items[1:3]`
+* Interpolation templates:
+
+    * `${/path/to/node}` — JSON Pointer lookup
+    * `${int:/path}` / `${float:/path}` / `${bool:/path}` — simple type casters
+    * `${? some.jmespath(expression) }` — JMESPath with custom functions
+* Special values:
+
+    * `$ref` — reference into the source document
+    * `$eval` — nested DSL evaluation with optional `$select`
+* Built-in operations:
+
+    * `set`, `copy`, `copyD`, `delete`, `assert`
+    * `foreach`, `if`, `distinct`
+    * `replace_root`, `exec`, `update`
+* Shorthand syntax for concise scripts (`~delete`, `~assert`, `field[]`, pointer assignments)
+* Schema helper: approximate JSON Schema generation for a given DSL script.
+
+---
+
+## Core API
+
+### `apply_actions`
+
+```python
+from j_perm import apply_actions
+
+result = apply_actions(actions, dest, source)
+```
+
+**Signature:**
+
+```python
+apply_actions(
+    actions: Any,
+    *,
+    dest: MutableMapping[str, Any] | List[Any],
+    source: Mapping[str, Any] | List[Any],
+) -> Mapping[str, Any]
+```
+
+* **`actions`** — DSL script (list or mapping).
+  Internally normalized via `normalize_actions()` and shorthand expansion.
+* **`dest`** — initial destination document to transform (typically a dict or list).
+* **`source`** — source document or context; available to pointers, interpolation, `$ref`, `$eval`, and nested operations.
+* Returns a **deep copy** of the final `dest`.
+
+---
+
+## Basic usage
+
+```python
+from j_perm import apply_actions
+
+source = {
+    "users": [
+        {"name": "Alice", "age": 17},
+        {"name": "Bob",   "age": 22}
+    ]
+}
+
+actions = [
+    # Start with empty list
+    {"op": "replace_root", "value": []},
+
+    # For each user - build a simplified object
+    {
+        "op": "foreach",
+        "in": "/users",
+        "as": "u",
+        "do": [
+            {
+                "op": "set",
+                "path": "/-",
+                "value": {
+                    "name": "${/u/name}",
+                    "is_adult": {
+                        "$eval": [
+                            {"op": "replace_root", "value": False},
+                            {
+                                "op": "if",
+                                "cond": "${?`${/u/age}` >= `18`}",
+                                "then": [{"op": "replace_root", "value": True}]
+                            }
+                        ]
+                    }
+                }
+            }
+        ]
+    }
+]
+
+result = apply_actions(actions, dest={}, source=source)
+```
+
+---
+
+# Interpolation & expression system (`${...}`)
+
+Interpolation is handled by the substitution utility used throughout operations such as `set`, `copy`, `exec`, `update`, schema building, etc.
+
+### 1. JSON Pointer interpolation
+
+* **Form:** `${/path/to/value}`
+* Meaning: resolve `/path/to/value` against the current **source context** (the original `source` plus any loop variables, etc.) and inject the value.
+
+Example:
+
+```json
+{
+  "op": "set",
+  "path": "/user/name",
+  "value": "Hello, ${/user/first_name}!"
+}
+```
+
+### 2. Casters
+
+* `${int:/age}` → cast value at `/age` to `int`
+* `${float:/height}` → cast to `float`
+* `${bool:/flag}` → cast to `bool`
+
+If the cast fails, an exception is raised.
+
+### 3. JMESPath expressions
+
+* **Form:** `${? <expression> }`
+* Evaluated against the **source context**, with access to any custom JMESPath functions wired into the engine.
+
+Example:
+
+```json
+{
+  "op": "set",
+  "path": "/expensiveNames",
+  "value": "${? items[?price > `10`].name }"
+}
+```
+
+### 4. Multiple templates in one string
+
+Any string can contain multiple `${...}` segments, which are resolved left-to-right.
+
+---
+
+# Special values: `$ref` and `$eval`
+
+Special values are resolved by `resolve_special()` before normal interpolation/substitution in operations like `set`, `update`, `exec`, `replace_root`.
+
+### `$ref`
+
+`{"$ref": "/path"}` means *“use the value at this path from the source”*.
+
+Example:
+
+```json
+{
+  "op": "set",
+  "path": "/user",
+  "value": { "$ref": "/rawUser" }
+}
+```
+
+This behaves similarly to a `copy` from `/rawUser`, but can be nested into larger structures and combined with `$eval` and interpolation.
+
+### `$eval`
+
+`{"$eval": [...]}` means *“execute this nested DSL script and use its result here”*.
+
+Example:
+
+```json
+{
+  "op": "set",
+  "path": "/flag",
+  "value": {
+    "$eval": [
+      { "op": "replace_root", "value": false },
+      {
+        "op": "if",
+        "cond": "${? some.expression }",
+        "then": [{ "op": "replace_root", "value": true }]
+      }
+    ]
+  }
+}
+```
+
+The nested script has the same `source` context as the outer script, and its final result becomes the value injected at `/flag`.
+
+---
+
+# Shorthand syntax (shortcuts)
+
+Shorthand is expanded by `normalize_actions()` into explicit operation steps.
+
+### How shorthand works internally
+
+* `actions` may be:
+
+    * a list of steps,
+    * a mapping without `"op"` — in that case it’s treated as shorthand and expanded.
+
+Expansion is done by `_expand_shorthand()`.
+
+### 1. Delete shorthand: `~delete`
+
+```json
+{ "~delete": "/path" }
+```
+
+If value is a list:
+
+```json
+{ "~delete": ["/a", "/b"] }
+```
+
+Expands into:
+
+```json
+{ "op": "delete", "path": "/a" }
+{ "op": "delete", "path": "/b" }
+```
+
+### 2. Assert shorthand: `~assert`
+
+If value is a mapping:
+
+```json
+{ "~assert": { "/x": 10, "/y": 20 } }
+```
+
+Expands into:
+
+```json
+{ "op": "assert", "path": "/x", "equals": 10 }
+{ "op": "assert", "path": "/y", "equals": 20 }
+```
+
+If value is a string or list of strings:
+
+```json
+{ "~assert": "/x" }
+# or
+{ "~assert": ["/x", "/y"] }
+```
+
+Expands into assertions that only check **existence** at those paths.
+
+### 3. Append shorthand: `field[]`
+
+A key ending with `[]` means “append to list at this path”.
+
+```json
+{ "items[]": 123 }
+```
+
+Expands into:
+
+```json
+{ "op": "set", "path": "/items/-", "value": 123 }
+```
+
+### 4. Pointer assignment shorthand
+
+If a value is a **string that starts with `/`**, it’s treated as a pointer and expanded into a `copy` operation:
+
+```json
+{ "name": "/user/fullName" }
+```
+
+Expands into:
+
+```json
+{
+  "op": "copy",
+  "path": "/name",
+  "from": "/user/fullName",
+  "ignore_missing": true
+}
+```
+
+(See `_is_pointer_string()` and `_expand_shorthand()` for details. )
+
+---
+
+# Built-in operations: signatures & parameters
+
+Below are all core operations with:
+
+* the **step shape**,
+* **required** vs **optional** parameters,
+* **default values**.
+
+All defaults are taken directly from the Python implementations.
+
+---
+
+## `set`
+
+Set or append a value at a JSON Pointer path in `dest`.
+
+### Signature
+
+```jsonc
+{
+  "op": "set",          // required
+  "path": "/pointer",   // required
+  "value": <any>,       // required
+  "create": true,       // optional, default: true
+  "extend": true        // optional, default: true
+}
+```
+
+### Parameters
+
+* **`path`** (required)
+  JSON Pointer path where the value is written.
+
+    * If the path ends with `"/-"`, the value is **appended** to a list.
+* **`value`** (required)
+  Any value, including special `$ref` / `$eval` objects and interpolated strings.
+  Resolved by `resolve_special()` and then `substitute()`.
+* **`create`** (optional, default **`true`**)
+  If `true`, missing parent containers are created.
+* **`extend`** (optional, default **`true`**)
+  If `path` is `"/-"` and `value` is a list:
+
+    * `extend=true` ⇒ list is extended with elements of `value`
+    * `extend=false` ⇒ `value` is appended as a single item (nested list)
+
+---
+
+## `copy`
+
+Copy a value from `source` (or extended source context) into `dest`. Internally uses `set`.
+
+### Signature
+
+```jsonc
+{
+  "op": "copy",                // required
+  "from": "/source/pointer",   // required
+  "path": "/target/pointer",   // required
+  "create": true,              // optional, default: true
+  "extend": true,              // optional, default: true
+  "ignore_missing": false,     // optional, default: false
+  "default": <any>             // optional
+}
+```
+
+### Parameters
+
+* **`from`** (required)
+  JSON Pointer into the **source** context (after interpolation).
+* **`path`** (required)
+  Destination path; same semantics as in `set`.
+* **`create`** (optional, default **`true`**)
+  Passed through to `set` — create missing parents.
+* **`extend`** (optional, default **`true`**)
+  Passed through to `set` — controls list extension on appends.
+* **`ignore_missing`** (optional, default **`false`**)
+  If `true` and `from` cannot be resolved, the operation is a no-op.
+* **`default`** (optional)
+  Used when `from` cannot be resolved and `ignore_missing` is **not** set.
+  If provided, `default` is copied into `path` instead of raising.
+
+---
+
+## `copyD`
+
+Copy a value from the **current `dest`** (self) into another path in `dest`. Internally uses `set`.
+
+This is useful for rearranging or duplicating data that has already been built in `dest`, without going back to the `source`.
+
+### Signature
+
+```jsonc
+{
+  "op": "copyD",               // required
+  "from": "/source/pointer",   // required
+  "path": "/target/pointer",   // required
+  "create": true,              // optional, default: true
+  "ignore_missing": false,     // optional, default: false
+  "default": <any>             // optional
+}
+```
+
+### Parameters
+
+* **`from`** (required)
+  JSON Pointer evaluated against **`dest`** (not `source`). The pointer itself is first interpolated with `src` (source context), but resolution uses `dest`.
+* **`path`** (required)
+  Destination path in `dest`, same semantics as in `set`.
+* **`create`** (optional, default **`true`**)
+  Passed to `set` — whether to create missing parent containers.
+* **`ignore_missing`** (optional, default **`false`**)
+  If `true` and the `from` pointer cannot be resolved in `dest`, the operation becomes a no-op.
+* **`default`** (optional)
+  Used when `from` cannot be resolved and `ignore_missing` is **not** set.
+  If provided, that default is deep-copied into `path` instead of raising.
+
+---
+
+## `delete`
+
+Delete a node at a JSON Pointer path in `dest`.
+
+### Signature
+
+```jsonc
+{
+  "op": "delete",          // required
+  "path": "/pointer",      // required
+  "ignore_missing": true   // optional, default: true
+}
+```
+
+### Parameters
+
+* **`path`** (required)
+  JSON Pointer to the node to delete.
+  Must not end with `"-"`.
+* **`ignore_missing`** (optional, default **`true`**)
+  If `false`, a missing path raises an error;
+  if `true`, missing path is silently ignored.
+
+---
+
+## `assert`
+
+Assert node existence and optional equality in `dest`.
+
+### Signature
+
+```jsonc
+{
+  "op": "assert",      // required
+  "path": "/pointer",  // required
+  "equals": <any>      // optional
+}
+```
+
+### Parameters
+
+* **`path`** (required)
+  JSON Pointer to check in `dest`.
+  If it does not exist, an `AssertionError` is raised.
+* **`equals`** (optional)
+  If provided, the value at `path` is compared with `equals`;
+  mismatch raises `AssertionError`.
+
+---
+
+## `foreach`
+
+Iterate over an array (or mapping) in the source context and execute nested actions.
+
+### Signature
+
+```jsonc
+{
+  "op": "foreach",        // required
+  "in": "/array/path",    // required
+  "do": [ ... ],          // required
+  "as": "item",           // optional, default: "item"
+  "default": [],          // optional, default: []
+  "skip_empty": true      // optional, default: true
+}
+```
+
+### Parameters
+
+* **`in`** (required)
+  JSON Pointer to the array in the source context (after interpolation).
+* **`do`** (required)
+  Nested DSL script (list or single op) executed for each element.
+* **`as`** (optional, default **`"item"`**)
+  Name of the variable bound to the current element in the extended source context.
+* **`default`** (optional, default **`[]`**)
+  Used when the pointer in `"in"` cannot be resolved.
+* **`skip_empty`** (optional, default **`true`**)
+  If `true` and the resolved array is empty, the loop is skipped.
+
+Additional behavior:
+
+* If the resolved object is a **dict**, it’s converted to a list of `(key, value)` pairs.
+* On exception in the body, `dest` is restored from a deep copy snapshot.
+
+---
+
+## `if`
+
+Conditionally execute nested actions.
+
+### Signature (path-based condition)
+
+```jsonc
+{
+  "op": "if",              // required
+  "path": "/pointer",      // required in this mode
+  "equals": <any>,         // optional
+  "exists": true,          // optional
+  "then": [ ... ],         // optional
+  "else": [ ... ],         // optional
+  "do": [ ... ]            // optional (fallback success branch)
+}
+```
+
+### Signature (expression-based condition)
+
+```jsonc
+{
+  "op": "if",              // required
+  "cond": "${?...}",       // required in this mode
+  "then": [ ... ],         // optional
+  "else": [ ... ],         // optional
+  "do": [ ... ]            // optional (fallback success branch)
+}
+```
+
+### Parameters
+
+At least **one** of `path` or `cond` must be supplied:
+
+* **`path`** (required in path-mode)
+
+    * If combined with `equals`, condition is `dest[path] == equals` and path must exist.
+    * If combined with `exists` (truthy), condition is “path exists”.
+    * Else, condition is `bool(dest[path])` (path must exist).
+* **`equals`** (optional, path-mode only)
+  Expected value for equality check.
+* **`exists`** (optional, path-mode only)
+  If truthy, check is presence of path only.
+* **`cond`** (required in expression-mode)
+  Arbitrary interpolated value or expression; `bool(cond)` is used.
+
+Branches:
+
+* **`then`** (optional)
+  Executed when condition is **true**.
+* **`else`** (optional)
+  Executed when condition is **false**.
+* **`do`** (optional)
+  If condition is **true** and `"then"` is missing, `"do"` is used as the success branch.
+
+If no branch is present for the chosen condition result, `dest` is returned unchanged.
+
+Error handling:
+
+* Before running branch actions, a deep copy snapshot of `dest` is taken.
+* On exception, `dest` is restored to the snapshot.
+
+---
+
+## `distinct`
+
+Remove duplicates in a list at the given path, preserving order.
+
+### Signature
+
+```jsonc
+{
+  "op": "distinct",       // required
+  "path": "/list/path",   // required
+  "key": "/key/pointer"   // optional
+}
+```
+
+### Parameters
+
+* **`path`** (required)
+  JSON Pointer to a **list** in `dest`.
+  If target is not a list, a `TypeError` is raised.
+* **`key`** (optional)
+  JSON Pointer evaluated per item to compute the *deduplication key*.
+
+    * If provided: uniqueness is based on `jptr_get(item, key_path)`.
+    * If omitted: the whole `item` is used as the key.
+
+---
+
+## `replace_root`
+
+Replace the whole `dest` root value with a new one.
+
+### Signature
+
+```jsonc
+{
+  "op": "replace_root",   // required
+  "value": <any>          // required
+}
+```
+
+### Parameters
+
+* **`value`** (required)
+  Value to become the new root.
+
+    * Special values (`$ref`, `$eval`) are resolved via `resolve_special()`.
+    * Strings/lists/dicts are then passed through interpolation `substitute()`.
+    * The final value is deep-copied.
+
+Result of `replace_root` is the new `dest`.
+
+---
+
+## `exec`
+
+Execute a nested DSL script held inline or at a pointer.
+
+Exactly one of `from` or `actions` must be provided.
+
+### Signature (script from pointer)
+
+```jsonc
+{
+  "op": "exec",           // required
+  "from": "/script/path", // required in this mode
+  "default": <any>,       // optional
+  "merge": false          // optional, default: false
+}
+```
+
+### Signature (inline script)
+
+```jsonc
+{
+  "op": "exec",           // required
+  "actions": [ ... ],     // required in this mode
+  "merge": false          // optional, default: false
+}
+```
+
+### Parameters
+
+* **`from`** (required in pointer-mode)
+  Pointer (possibly interpolated) to the actions in the source context.
+  If resolution fails:
+
+    * and `default` is present ⇒ use `default` as the script (after resolving specials and interpolation if it’s str/list/dict),
+    * else ⇒ raise `ValueError`.
+* **`actions`** (required in inline-mode)
+  Inline DSL script (list or mapping). Special values and templates are resolved.
+* **`merge`** (optional, default **`false`**)
+
+    * `merge=false` (default): nested script runs with `dest={}`, result **replaces** current `dest`.
+    * `merge=true`: nested script runs **on current dest** and the result is returned (like a sub-call to `apply_actions` on same `dest`).
+* **`default`** (optional, pointer-mode only)
+  Fallback script if `from` cannot be resolved.
+
+---
+
+## `update`
+
+Update a mapping at the given path using either inline value or source mapping.
+
+Exactly one of `from` or `value` must be provided.
+
+### Signature
+
+```jsonc
+{
+  "op": "update",             // required
+  "path": "/target/path",     // required
+  "from": "/source/path",     // required in from-mode
+  "value": { ... },           // required in value-mode
+  "default": { ... },         // optional (from-mode only)
+  "create": true,             // optional, default: true
+  "deep": false               // optional, default: false
+}
+```
+
+### Parameters
+
+* **`path`** (required)
+  JSON Pointer path to the **mapping** to update.
+* **`from`** (required in from-mode)
+  Pointer to mapping in source; deep-copied.
+  If resolution fails:
+
+    * and `default` is provided ⇒ use `default`,
+    * else ⇒ raise.
+* **`value`** (required in value-mode)
+  Inline mapping; resolved through `resolve_special` and `substitute` if needed.
+* **`default`** (optional, from-mode only)
+  Mapping used when `from` cannot be resolved.
+* **`create`** (optional, default **`true`**)
+  If `true`, missing containers at `path` are created (including the leaf if needed).
+* **`deep`** (optional, default **`false`**)
+
+    * `false`: shallow update via `dict.update()`.
+    * `true`: recursive deep-merge of nested mappings; leaves and non-mappings are overwritten via deep copy.
+
+Constraints:
+
+* The resolved update value **must be a mapping**; otherwise `TypeError`.
+* The target at `path` must be a mutable mapping; otherwise `TypeError`.
+
+---
+
+# Schema generation
+
+```python
+from j_perm import build_schema
+
+schema = build_schema(script)
+```
+
+`schema` is a JSON-Schema-like structure inferred by scanning the script:
+
+* Tracks `replace_root`, `set`, `update`, nested `$eval`, etc.
+* Infers basic JSON types from literal values.
+
+---
+
+## Extending with custom operations
+
+```python
+from j_perm import register_op
+
+@register_op("my_op")
+def my_op(step, dest, src):
+    # implement your logic
+    return dest
+```
+
+Any registered operation can be used in scripts via:
+
+```json
+{ "op": "my_op", ... }
+```
+
+---
+
+## License
+
+This package is provided as-is; feel free to adapt it to your project structure.