statepatch 0.1.1__tar.gz → 0.2.1__tar.gz

{statepatch-0.1.1 → statepatch-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: statepatch
-Version: 0.1.1
+Version: 0.2.1
 Summary: Immer-style ops over a plain JSON tree: observables that emit every mutation as an op
 Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
 License-Expression: MIT

{statepatch-0.1.1 → statepatch-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "statepatch"
-version = "0.1.1"
+version = "0.2.1"
 description = "Immer-style ops over a plain JSON tree: observables that emit every mutation as an op"
 readme = "README.md"
 license = "MIT"

statepatch-0.2.1/src/statepatch/__init__.py

@@ -0,0 +1,22 @@
+"""Immer-style ops over a plain JSON tree.
+
+An ``Observable`` wraps one value: ``.value`` reads a plain snapshot, every
+mutation applies to the tree and emits the matching ``Op`` to subscribers.
+Observables compose: an observable stored inside another mounts its op
+stream at that path; removing it detaches it, live and reusable.
+"""
+
+from ._core import Observable, Proxy, append, observable
+from ._wire import Listener, Op, Path, Segment, plain
+
+__all__ = [
+    "observable",
+    "Observable",
+    "Proxy",
+    "plain",
+    "append",
+    "Op",
+    "Path",
+    "Segment",
+    "Listener",
+]

statepatch-0.1.1/src/statepatch/__init__.py → statepatch-0.2.1/src/statepatch/_core.py

@@ -1,96 +1,6 @@
-"""Immer-style ops over a plain JSON tree.
+from typing import Any, Callable, Iterator
 
-An ``Observable`` wraps one value: ``.value`` reads a plain snapshot, every
-mutation applies to the tree and emits the matching ``Op`` to subscribers.
-Observables compose: an observable stored inside another mounts its op
-stream at that path; removing it detaches it, live and reusable.
-"""
-
-import math
-from datetime import datetime
-from typing import Any, Callable, Iterator, NamedTuple
-
-Segment = str | int
-Path = tuple[Segment, ...]
-
-
-class Op(NamedTuple):
-    kind: str  # "replace" | "add" | "remove"
-    path: Path
-    value: Any = None
-
-
-Listener = Callable[[Op], None]
-
-_MAX_SAFE_INT = 2**53 - 1
-_MISSING: Any = object()
-
-
-def _snapshot(node: Any) -> Any:
-    if isinstance(node, Observable):
-        return _snapshot(node._state)
-    if isinstance(node, dict):
-        return {key: _snapshot(item) for key, item in node.items()}
-    if isinstance(node, list):
-        return [_snapshot(item) for item in node]
-    return node
-
-
-def plain(value: Any) -> Any:
-    """Resolve a proxy or observable to a plain snapshot; pass anything else through."""
-    if isinstance(value, Proxy):
-        _owner, _rel, node = value._target()
-        return _snapshot(node)
-    if isinstance(value, Observable):
-        return _snapshot(value._state)
-    return value
-
-
-def _adopt(value: Any, base: Path) -> tuple[Any, list[tuple[Path, "Observable"]]]:
-    """Validated deep copy keeping ``Observable`` nodes in place; returns the
-    stored tree and the mount points found inside it (paths rooted at ``base``)."""
-    mounts: list[tuple[Path, Observable]] = []
-
-    def walk(value: Any, path: Path) -> Any:
-        if isinstance(value, Observable):
-            mounts.append((path, value))
-            return value
-        if isinstance(value, Proxy):
-            value = plain(value)
-        if isinstance(value, bool) or value is None or isinstance(value, str):
-            return value
-        if isinstance(value, float):
-            if math.isnan(value) or math.isinf(value):
-                raise ValueError(f"{value!r} is not wire-encodable; floats must be finite")
-            return value
-        if isinstance(value, int):
-            if abs(value) > _MAX_SAFE_INT:
-                raise ValueError(
-                    f"integer {value} exceeds the JS safe range (|n| <= 2**53-1); send it as a string"
-                )
-            return value
-        if isinstance(value, datetime):
-            if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
-                raise ValueError("naive datetime is not wire-encodable; attach a timezone")
-            return value
-        if isinstance(value, (list, tuple)):
-            return [walk(item, path + (i,)) for i, item in enumerate(value)]
-        if isinstance(value, dict):
-            out: dict[str, Any] = {}
-            for key, item in value.items():
-                if not isinstance(key, str):
-                    raise TypeError(f"object keys must be strings, got {type(key).__name__}")
-                out[key] = walk(item, path + (key,))
-            return out
-        raise TypeError(f"{type(value).__name__} is not wire-encodable")
-
-    return walk(value, base), mounts
-
-
-def _index(container: Any, key: Any) -> Any:
-    if isinstance(container, list) and isinstance(key, int) and key < 0:
-        return key + len(container)
-    return key
+from ._wire import _MISSING, Listener, Op, Path, Segment, _adopt, _index, _snapshot, plain
 
 
 class Observable:
@@ -220,6 +130,8 @@ class Observable:
             return node._target(())
         return self, path, node
 
+    # container delegators
+
     def __getitem__(self, key: Any) -> Any:
         return Proxy(self, ())[key]
 

statepatch-0.2.1/src/statepatch/_wire.py

@@ -0,0 +1,95 @@
+import math
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Callable, NamedTuple
+
+if TYPE_CHECKING:
+    from ._core import Observable
+
+Segment = str | int
+Path = tuple[Segment, ...]
+
+
+class Op(NamedTuple):
+    kind: str  # "replace" | "add" | "remove"
+    path: Path
+    value: Any = None
+
+
+Listener = Callable[[Op], None]
+
+_MAX_SAFE_INT = 2**53 - 1
+_MISSING: Any = object()
+
+
+def _snapshot(node: Any) -> Any:
+    from ._core import Observable
+
+    if isinstance(node, Observable):
+        return _snapshot(node._state)
+    if isinstance(node, dict):
+        return {key: _snapshot(item) for key, item in node.items()}
+    if isinstance(node, list):
+        return [_snapshot(item) for item in node]
+    return node
+
+
+def plain(value: Any) -> Any:
+    """Resolve a proxy or observable to its live stored node (mutating it emits no ops); pass anything else through."""
+    from ._core import Observable, Proxy
+
+    if isinstance(value, Observable):
+        value = Proxy(value, ())
+    if not isinstance(value, Proxy):
+        return value
+    owner, rel, node = value._target()
+    mounted = any(path[: len(rel)] == rel for _child, path, _unsub in owner._mounts.values())
+    return _snapshot(node) if mounted else node
+
+
+def _adopt(value: Any, base: Path) -> tuple[Any, list[tuple[Path, "Observable"]]]:
+    """Validated deep copy keeping ``Observable`` nodes in place; returns the
+    stored tree and the mount points found inside it (paths rooted at ``base``)."""
+    from ._core import Observable, Proxy
+
+    mounts: list[tuple[Path, Observable]] = []
+
+    def walk(value: Any, path: Path) -> Any:
+        if isinstance(value, Observable):
+            mounts.append((path, value))
+            return value
+        if isinstance(value, Proxy):
+            value = plain(value)
+        if isinstance(value, bool) or value is None or isinstance(value, str):
+            return value
+        if isinstance(value, float):
+            if math.isnan(value) or math.isinf(value):
+                raise ValueError(f"{value!r} is not wire-encodable; floats must be finite")
+            return value
+        if isinstance(value, int):
+            if abs(value) > _MAX_SAFE_INT:
+                raise ValueError(
+                    f"integer {value} exceeds the JS safe range (|n| <= 2**53-1); send it as a string"
+                )
+            return value
+        if isinstance(value, datetime):
+            if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
+                raise ValueError("naive datetime is not wire-encodable; attach a timezone")
+            return value
+        if isinstance(value, (list, tuple)):
+            return [walk(item, path + (i,)) for i, item in enumerate(value)]
+        if isinstance(value, dict):
+            out: dict[str, Any] = {}
+            for key, item in value.items():
+                if not isinstance(key, str):
+                    raise TypeError(f"object keys must be strings, got {type(key).__name__}")
+                out[key] = walk(item, path + (key,))
+            return out
+        raise TypeError(f"{type(value).__name__} is not wire-encodable")
+
+    return walk(value, base), mounts
+
+
+def _index(container: Any, key: Any) -> Any:
+    if isinstance(container, list) and isinstance(key, int) and key < 0:
+        return key + len(container)
+    return key

{statepatch-0.1.1 → statepatch-0.2.1}/tests/test_observable.py

@@ -4,7 +4,7 @@ mounted observables forward their op streams at the mount path."""
 from datetime import datetime, timezone
 
 import pytest
-from statepatch import Op, append, observable
+from statepatch import Observable, Op, append, observable, plain
 
 
 def collect(obs):
@@ -180,6 +180,26 @@ def test_snapshot_ops_carry_plain_values_for_nested_mounts():
     assert ops[-1] == Op("replace", ("wrap", "inner", "n"), 7)
 
 
+def test_plain_returns_the_live_node():
+    state = observable({"runs": [{"id": "r1"}]})
+    ops = collect(state)
+    assert plain(state) is state._state
+    assert plain(state["runs"]) is state._state["runs"]
+    assert plain(state["runs"][0]["id"]) == "r1"
+    plain(state["runs"]).append({"id": "r2"})
+    assert state.value == {"runs": [{"id": "r1"}, {"id": "r2"}]}
+    assert ops == []
+
+
+def test_plain_unwraps_mounts_into_a_snapshot():
+    child = observable({"n": 0})
+    parent = observable({"wrap": {"inner": child}, "other": [1]})
+    assert plain(parent["wrap"]) == {"inner": {"n": 0}}
+    assert not isinstance(plain(parent["wrap"])["inner"], Observable)
+    assert plain(parent["wrap"]["inner"]) is child._state
+    assert plain(parent["other"]) is parent._state["other"]
+
+
 def test_container_helpers():
     state = observable({"d": {"a": 1}, "l": [1, 2, 3]})
     ops = collect(state)