statepatch 0.1.0__py3-none-any.whl

statepatch/__init__.py

@@ -0,0 +1,524 @@
+"""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.
+"""
+
+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
+
+
+class Observable:
+    __slots__ = ("_state", "_listeners", "_mounts", "_parent")
+
+    def __init__(self, initial: Any = None) -> None:
+        if isinstance(initial, Observable):
+            raise TypeError("an observable cannot wrap another observable; nest it inside a container")
+        self._listeners: list[Listener] = []
+        self._mounts: dict[int, tuple[Observable, Path, Callable[[], None]]] = {}
+        self._parent: Observable | None = None
+        stored, mounts = _adopt(initial, ())
+        self._admit(mounts)
+        self._state = stored
+        for path, child in mounts:
+            self._attach(child, path)
+
+    @property
+    def value(self) -> Any:
+        return _snapshot(self._state)
+
+    @value.setter
+    def value(self, value: Any) -> None:
+        if isinstance(value, Observable):
+            raise TypeError("an observable cannot wrap another observable; nest it inside a container")
+        stored, mounts = _adopt(value, ())
+        self._admit(mounts, ())
+        for child, _path, unsubscribe in list(self._mounts.values()):
+            unsubscribe()
+            child._parent = None
+        self._mounts.clear()
+        self._state = stored
+        for path, child in mounts:
+            self._attach(child, path)
+        self._emit(Op("replace", (), _snapshot(stored)))
+
+    def subscribe(self, listener: Listener) -> Callable[[], None]:
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            if listener in self._listeners:
+                self._listeners.remove(listener)
+
+        return unsubscribe
+
+    def _emit(self, op: Op) -> None:
+        for listener in list(self._listeners):
+            listener(op)
+
+    def _admit(
+        self,
+        mounts: list[tuple[Path, "Observable"]],
+        detach_root: Path | None = None,
+        seen: set[int] | None = None,
+    ) -> None:
+        """Validate pending mounts before any tree mutation; ``detach_root``
+        exempts children this write is about to detach from ``self``."""
+        seen = seen if seen is not None else set()
+        for _path, child in mounts:
+            if id(child) in seen:
+                raise ValueError("observable appears more than once in one write")
+            seen.add(id(child))
+            if child._parent is not None:
+                current = self._mounts.get(id(child))
+                freed = (
+                    detach_root is not None
+                    and current is not None
+                    and current[1][: len(detach_root)] == detach_root
+                )
+                if not freed:
+                    raise ValueError("observable is already mounted; detach it first")
+            node: Observable | None = self
+            while node is not None:
+                if node is child:
+                    raise ValueError("mounting this observable would create a cycle")
+                node = node._parent
+
+    def _attach(self, child: "Observable", path: Path) -> None:
+        if child._parent is not None:
+            raise ValueError("observable is already mounted; detach it first")
+        node: Observable | None = self
+        while node is not None:
+            if node is child:
+                raise ValueError("mounting this observable would create a cycle")
+            node = node._parent
+        child._parent = self
+        unsubscribe = child.subscribe(lambda op, child=child: self._forward(child, op))
+        self._mounts[id(child)] = (child, path, unsubscribe)
+
+    def _forward(self, child: "Observable", op: Op) -> None:
+        entry = self._mounts.get(id(child))
+        if entry is None:
+            return
+        _child, path, _unsubscribe = entry
+        self._emit(Op(op.kind, path + op.path, op.value))
+
+    def _detach_under(self, path: Path) -> None:
+        for key, (child, mount_path, unsubscribe) in list(self._mounts.items()):
+            if mount_path[: len(path)] == path:
+                unsubscribe()
+                child._parent = None
+                del self._mounts[key]
+
+    def _shift(self, parent: Path, start: int, delta: int) -> None:
+        depth = len(parent)
+        for key, (child, path, unsubscribe) in list(self._mounts.items()):
+            if (
+                len(path) > depth
+                and path[:depth] == parent
+                and isinstance(path[depth], int)
+                and path[depth] >= start
+            ):
+                self._mounts[key] = (
+                    child,
+                    parent + (path[depth] + delta,) + path[depth + 1 :],
+                    unsubscribe,
+                )
+
+    def _target(self, path: Path) -> tuple["Observable", Path, Any]:
+        """Deepest observable owning ``path``, the path relative to it, and the node there."""
+        node = self._state
+        for i, segment in enumerate(path):
+            if isinstance(node, Observable):
+                return node._target(path[i:])
+            node = node[segment]
+        if isinstance(node, Observable):
+            return node._target(())
+        return self, path, node
+
+    def __getitem__(self, key: Any) -> Any:
+        return Proxy(self, ())[key]
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        Proxy(self, ())[key] = value
+
+    def __delitem__(self, key: Any) -> None:
+        proxy = Proxy(self, ())
+        del proxy[key]
+
+    def __contains__(self, item: Any) -> bool:
+        return item in Proxy(self, ())
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(Proxy(self, ()))
+
+    def __len__(self) -> int:
+        return len(Proxy(self, ()))
+
+    def __repr__(self) -> str:
+        return f"observable({self.value!r})"
+
+    def append(self, item: Any) -> None:
+        Proxy(self, ()).append(item)
+
+    def insert(self, index: int, item: Any) -> None:
+        Proxy(self, ()).insert(index, item)
+
+    def pop(self, *args: Any) -> Any:
+        return Proxy(self, ()).pop(*args)
+
+    def remove(self, item: Any) -> None:
+        Proxy(self, ()).remove(item)
+
+    def clear(self) -> None:
+        Proxy(self, ()).clear()
+
+    def extend(self, items: Any) -> None:
+        Proxy(self, ()).extend(items)
+
+    def update(self, other: Any) -> None:
+        Proxy(self, ()).update(other)
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        return Proxy(self, ()).get(key, default)
+
+    def setdefault(self, key: Any, default: Any = None) -> Any:
+        return Proxy(self, ()).setdefault(key, default)
+
+    def keys(self):
+        return Proxy(self, ()).keys()
+
+    def values(self):
+        return Proxy(self, ()).values()
+
+    def items(self):
+        return Proxy(self, ()).items()
+
+
+def observable(initial: Any = None) -> Observable:
+    """A mini statewire: ``.value`` reads it, every mutation is an op."""
+    return Observable(initial)
+
+
+class Proxy:
+    """Mutation cursor into an observable's tree; reads resolve live, writes
+    apply and record ops on the owning (deepest mounted) observable."""
+
+    __slots__ = ("_root", "_path")
+
+    def __init__(self, root: Observable, path: Path) -> None:
+        self._root = root
+        self._path = path
+
+    def _target(self) -> tuple[Observable, Path, Any]:
+        return self._root._target(self._path)
+
+    def __getitem__(self, key: Any) -> Any:
+        _owner, _rel, node = self._target()
+        key = _index(node, key)
+        value = node[key]
+        if isinstance(value, (dict, list, Observable)):
+            return Proxy(self._root, self._path + (key,))
+        return value
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        owner, rel, container = self._target()
+        key = _index(container, key)
+        if isinstance(container, dict) and not isinstance(key, str):
+            raise TypeError(f"object keys must be strings, got {type(key).__name__}")
+        if isinstance(container, list) and (
+            isinstance(key, bool) or not isinstance(key, int)
+        ):
+            raise TypeError(f"list indices must be integers, got {type(key).__name__}")
+        old = (
+            container.get(key, _MISSING)
+            if isinstance(container, dict)
+            else container[key]
+        )
+        path = rel + (key,)
+        if isinstance(old, str) and isinstance(value, str) and value.startswith(old):
+            if value == old:
+                return
+            container[key] = value
+            owner._emit(Op("add", path + (len(old),), value[len(old) :]))
+            return
+        stored, mounts = _adopt(value, path)
+        owner._admit(mounts, path)
+        owner._detach_under(path)
+        container[key] = stored
+        for mount_path, child in mounts:
+            owner._attach(child, mount_path)
+        owner._emit(Op("replace", path, _snapshot(stored)))
+
+    def append(self, item: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, list):
+            raise TypeError(f"append on non-list at path {list(self._path)!r}")
+        index = len(container)
+        path = rel + (index,)
+        stored, mounts = _adopt(item, path)
+        owner._admit(mounts)
+        container.append(stored)
+        for mount_path, child in mounts:
+            owner._attach(child, mount_path)
+        owner._emit(Op("add", path, _snapshot(stored)))
+
+    def insert(self, index: int, item: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, list):
+            raise TypeError(f"insert on non-list at path {list(self._path)!r}")
+        index = max(0, min(index + len(container) if index < 0 else index, len(container)))
+        path = rel + (index,)
+        stored, mounts = _adopt(item, path)
+        owner._admit(mounts)
+        owner._shift(rel, index, 1)
+        container.insert(index, stored)
+        for mount_path, child in mounts:
+            owner._attach(child, mount_path)
+        owner._emit(Op("add", path, _snapshot(stored)))
+
+    def _remove_at(
+        self, owner: Observable, rel: Path, container: list, index: int
+    ) -> Any:
+        value = _snapshot(container[index])
+        path = rel + (index,)
+        owner._detach_under(path)
+        del container[index]
+        owner._shift(rel, index + 1, -1)
+        owner._emit(Op("remove", path))
+        return value
+
+    def __delitem__(self, key: Any) -> None:
+        owner, rel, container = self._target()
+        key = _index(container, key)
+        if isinstance(container, list):
+            container[key]
+            self._remove_at(owner, rel, container, key)
+            return
+        if key not in container:
+            raise KeyError(key)
+        path = rel + (key,)
+        owner._detach_under(path)
+        del container[key]
+        owner._emit(Op("remove", path))
+
+    def pop(self, *args: Any) -> Any:
+        owner, rel, container = self._target()
+        if isinstance(container, list):
+            index = _index(container, args[0] if args else -1)
+            container[index]
+            return self._remove_at(owner, rel, container, index)
+        if not args:
+            raise TypeError("pop expected at least 1 argument, got 0")
+        if args[1:] and args[0] not in container:
+            return args[1]
+        key = args[0]
+        value = _snapshot(container[key])
+        path = rel + (key,)
+        owner._detach_under(path)
+        del container[key]
+        owner._emit(Op("remove", path))
+        return value
+
+    def remove(self, item: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, list):
+            raise TypeError(f"remove on non-list at path {list(self._path)!r}")
+        target = plain(item)
+        index = next(
+            (i for i, node in enumerate(container) if _snapshot(node) == target), None
+        )
+        if index is None:
+            raise ValueError(f"{target!r} not in list")
+        self._remove_at(owner, rel, container, index)
+
+    def clear(self) -> None:
+        owner, rel, container = self._target()
+        owner._detach_under(rel)
+        container.clear()
+        owner._emit(Op("replace", rel, _snapshot(container)))
+
+    def extend(self, items: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, list):
+            raise TypeError(f"extend on non-list at path {list(self._path)!r}")
+        adopted = [
+            _adopt(item, rel + (index,))
+            for index, item in enumerate(items, start=len(container))
+        ]
+        seen: set[int] = set()
+        for _stored, mounts in adopted:
+            owner._admit(mounts, seen=seen)
+        for stored, mounts in adopted:
+            container.append(stored)
+            for mount_path, child in mounts:
+                owner._attach(child, mount_path)
+        owner._emit(Op("replace", rel, _snapshot(container)))
+
+    def update(self, other: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, dict):
+            raise TypeError(f"update on non-dict at path {list(self._path)!r}")
+        adopted = []
+        for key, item in dict(plain(other) if isinstance(other, Proxy) else other).items():
+            if not isinstance(key, str):
+                raise TypeError(f"object keys must be strings, got {type(key).__name__}")
+            adopted.append((key, *_adopt(item, rel + (key,))))
+        seen: set[int] = set()
+        for key, _stored, mounts in adopted:
+            owner._admit(mounts, rel + (key,), seen)
+        for key, stored, mounts in adopted:
+            owner._detach_under(rel + (key,))
+            container[key] = stored
+            for mount_path, child in mounts:
+                owner._attach(child, mount_path)
+        owner._emit(Op("replace", rel, _snapshot(container)))
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        try:
+            return self[key]
+        except (KeyError, IndexError):
+            return default
+
+    def setdefault(self, key: Any, default: Any = None) -> Any:
+        _owner, _rel, container = self._target()
+        if not isinstance(container, dict):
+            raise TypeError(f"setdefault on non-dict at path {list(self._path)!r}")
+        if key not in container:
+            self[key] = default
+        return self[key]
+
+    def keys(self):
+        _owner, _rel, node = self._target()
+        return node.keys()
+
+    def values(self):
+        _owner, _rel, node = self._target()
+        return (self[key] for key in node.keys())
+
+    def items(self):
+        _owner, _rel, node = self._target()
+        return ((key, self[key]) for key in node.keys())
+
+    def index(self, item: Any) -> int:
+        _owner, _rel, node = self._target()
+        target = plain(item)
+        found = next(
+            (i for i, entry in enumerate(node) if _snapshot(entry) == target), None
+        )
+        if found is None:
+            raise ValueError(f"{target!r} not in list")
+        return found
+
+    def __contains__(self, item: Any) -> bool:
+        _owner, _rel, node = self._target()
+        target = plain(item)
+        if isinstance(node, list):
+            return any(_snapshot(entry) == target for entry in node)
+        return target in node
+
+    def __iter__(self) -> Iterator[Any]:
+        _owner, _rel, node = self._target()
+        if isinstance(node, list):
+            return (self[i] for i in range(len(node)))
+        return iter(list(node))
+
+    def __len__(self) -> int:
+        _owner, _rel, node = self._target()
+        return len(node)
+
+    def __eq__(self, other: Any) -> bool:
+        _owner, _rel, node = self._target()
+        return _snapshot(node) == plain(other)
+
+    def __bool__(self) -> bool:
+        _owner, _rel, node = self._target()
+        return bool(node)
+
+    def __repr__(self) -> str:
+        _owner, _rel, node = self._target()
+        return repr(_snapshot(node))

statepatch-0.1.0.dist-info/METADATA

@@ -0,0 +1,26 @@
+Metadata-Version: 2.5
+Name: statepatch
+Version: 0.1.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.1.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+statepatch/__init__.py,sha256=1-wj-_iSAHyQOtmTMhQAB5kGvN_rU35FNCNbnx-VcGY,19091
+statepatch-0.1.0.dist-info/METADATA,sha256=sKJZBQe1VsqZo3FbG0gc5CmfUJYL3JPMHB6Yoeo-vXY,991
+statepatch-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+statepatch-0.1.0.dist-info/RECORD,,

statepatch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any