statepatch 0.2.0__tar.gz → 0.2.2__tar.gz

{statepatch-0.2.0 → statepatch-0.2.2}/.gitignore

@@ -25,3 +25,6 @@ apps/docs/.docs
 /.deepsec/
 .vercel
 .env*
+
+MAINTAIN_EPOCH.md
+DOCS_EPOCH.md

statepatch-0.2.2/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.5
+Name: statepatch
+Version: 0.2.2
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# statepatch
+
+Immer-style ops over a plain JSON tree: `observable(initial)` wraps one value, `.value` reads it, and every mutation emits the matching `replace` / `add` / `remove` op to subscribers. Observables compose: one stored inside another mounts its op stream at that path. Part of [harness-sdk](https://github.com/assistant-ui/harness-sdk), under `statewire` and `pinned`.
+
+## Install
+
+```sh
+uv add statepatch
+```
+
+## Use
+
+```python
+from statepatch import observable
+
+state = observable({"runs": []})
+state.subscribe(print)
+
+run = observable({"runId": "r1", "queue": []})
+state["runs"].append(run)          # add op at ["runs", 0]
+run["queue"].append({"id": "q1"})  # forwarded as add at ["runs", 0, "queue", 0]
+state["runs"].pop(0)               # remove op; run is detached and reusable
+```
+
+## Docs
+
+- Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/reference/packages/page.mdx
+- Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/guides/statewire/host/page.mdx
+- Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/spec/statewire-protocol/statepatch/page.mdx

statepatch-0.2.2/README.md

@@ -0,0 +1,29 @@
+# statepatch
+
+Immer-style ops over a plain JSON tree: `observable(initial)` wraps one value, `.value` reads it, and every mutation emits the matching `replace` / `add` / `remove` op to subscribers. Observables compose: one stored inside another mounts its op stream at that path. Part of [harness-sdk](https://github.com/assistant-ui/harness-sdk), under `statewire` and `pinned`.
+
+## Install
+
+```sh
+uv add statepatch
+```
+
+## Use
+
+```python
+from statepatch import observable
+
+state = observable({"runs": []})
+state.subscribe(print)
+
+run = observable({"runId": "r1", "queue": []})
+state["runs"].append(run)          # add op at ["runs", 0]
+run["queue"].append({"id": "q1"})  # forwarded as add at ["runs", 0, "queue", 0]
+state["runs"].pop(0)               # remove op; run is detached and reusable
+```
+
+## Docs
+
+- Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/reference/packages/page.mdx
+- Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/guides/statewire/host/page.mdx
+- Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/spec/statewire-protocol/statepatch/page.mdx

{statepatch-0.2.0 → statepatch-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "statepatch"
-version = "0.2.0"
+version = "0.2.2"
 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.0 → statepatch-0.2.2}/src/statepatch/__init__.py

@@ -7,13 +7,14 @@ 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
+from ._wire import Listener, Op, Path, Segment, plain, snapshot
 
 __all__ = [
     "observable",
     "Observable",
     "Proxy",
     "plain",
+    "snapshot",
     "append",
     "Op",
     "Path",

{statepatch-0.2.0 → statepatch-0.2.2}/src/statepatch/_core.py

@@ -4,7 +4,7 @@ from ._wire import _MISSING, Listener, Op, Path, Segment, _adopt, _index, _snaps
 
 
 class Observable:
-    __slots__ = ("_state", "_listeners", "_mounts", "_parent")
+    __slots__ = ("_state", "_listeners", "_mounts", "_parent", "__weakref__")
 
     def __init__(self, initial: Any = None) -> None:
         if isinstance(initial, Observable):

{statepatch-0.2.0 → statepatch-0.2.2}/src/statepatch/_wire.py

@@ -22,8 +22,10 @@ _MISSING: Any = object()
 
 
 def _snapshot(node: Any) -> Any:
-    from ._core import Observable
+    from ._core import Observable, Proxy
 
+    if isinstance(node, Proxy):
+        _, _, node = node._target()
     if isinstance(node, Observable):
         return _snapshot(node._state)
     if isinstance(node, dict):
@@ -34,15 +36,21 @@ def _snapshot(node: Any) -> Any:
 
 
 def plain(value: Any) -> Any:
-    """Resolve a proxy or observable to a plain snapshot; pass anything else through."""
+    """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, Proxy):
-        _owner, _rel, node = value._target()
-        return _snapshot(node)
     if isinstance(value, Observable):
-        return _snapshot(value._state)
-    return value
+        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 snapshot(value: Any) -> Any:
+    """Copy a value and its mounted observables into an independent plain tree."""
+    return _snapshot(value)
 
 
 def _adopt(value: Any, base: Path) -> tuple[Any, list[tuple[Path, "Observable"]]]:

{statepatch-0.2.0 → statepatch-0.2.2}/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)

statepatch-0.2.2/tests/test_snapshot.py

@@ -0,0 +1,19 @@
+from statepatch import observable, plain, snapshot
+
+
+def test_snapshot_copies_only_the_selected_subtree_and_unwraps_mounts():
+    child = observable({"values": [1]})
+    state = observable({"selected": {"child": child}, "other": {"large": [2]}})
+    copied = snapshot(state["selected"])
+    assert copied == {"child": {"values": [1]}}
+    copied["child"]["values"].append(3)
+    assert plain(child["values"]) == [1]
+    child["values"].append(4)
+    assert copied["child"]["values"] == [1, 3]
+
+
+def test_snapshot_accepts_proxies_inside_plain_containers():
+    state = observable({"items": [{"id": "m1"}]})
+    copied = snapshot({"wrapped": [state["items"][0]]})
+    state["items"][0]["id"] = "m2"
+    assert copied == {"wrapped": [{"id": "m1"}]}

statepatch-0.2.0/PKG-INFO

@@ -1,26 +0,0 @@
-Metadata-Version: 2.5
-Name: statepatch
-Version: 0.2.0
-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
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# statepatch
-
-Immer-style ops over a plain JSON tree.
-
-`observable(initial)` wraps one value: `.value` reads it, every mutation applies to the tree and emits the matching op (`replace` / `add` / `remove`) to subscribers. Observables compose: an observable stored inside another mounts its op stream at that path.
-
-```python
-from statepatch import observable
-
-state = observable({"runs": []})
-state.subscribe(print)
-
-run = observable({"runId": "r1", "queue": []})
-state["runs"].append(run)          # add op at ["runs", 0]
-run["queue"].append({"id": "q1"})  # forwarded as add at ["runs", 0, "queue", 0]
-state["runs"].pop(0)               # remove op; run is detached and reusable
-```

statepatch-0.2.0/README.md

@@ -1,17 +0,0 @@
-# statepatch
-
-Immer-style ops over a plain JSON tree.
-
-`observable(initial)` wraps one value: `.value` reads it, every mutation applies to the tree and emits the matching op (`replace` / `add` / `remove`) to subscribers. Observables compose: an observable stored inside another mounts its op stream at that path.
-
-```python
-from statepatch import observable
-
-state = observable({"runs": []})
-state.subscribe(print)
-
-run = observable({"runId": "r1", "queue": []})
-state["runs"].append(run)          # add op at ["runs", 0]
-run["queue"].append({"id": "q1"})  # forwarded as add at ["runs", 0, "queue", 0]
-state["runs"].pop(0)               # remove op; run is detached and reusable
-```