robject 0.1.0__py3-none-any.whl

robject/__init__.py

@@ -0,0 +1,37 @@
+"""robject: reactive objects for Python.
+
+Declare plain classes whose attributes are observable, derive cached
+``computed`` properties that track their own dependencies, react to changes
+with ``effect`` and ``subscribe``, and group writes with ``batch``.
+
+>>> from robject import RObject, computed
+>>> class Cart(RObject):
+...     price: float = 0.0
+...     qty: int = 1
+...     @computed
+...     def total(self) -> float:
+...         return self.price * self.qty
+>>> cart = Cart(price=2.5, qty=4)
+>>> cart.total
+10.0
+"""
+
+from ._core import Effect, batch, effect, untracked
+from ._object import Change, RObject, computed, field, fields, snapshot, subscribe
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RObject",
+    "field",
+    "computed",
+    "effect",
+    "Effect",
+    "batch",
+    "untracked",
+    "subscribe",
+    "Change",
+    "fields",
+    "snapshot",
+    "__version__",
+]

robject/_core.py

@@ -0,0 +1,358 @@
+"""Reactive core: signals, computed nodes, effects, batching and the scheduler.
+
+This module knows nothing about :class:`robject.RObject`; it provides the
+dependency-tracking graph that ``RObject`` fields and computed properties are
+built on.
+
+Model
+-----
+* A :class:`Signal` holds one value. Reading it while an observer is running
+  records a dependency; writing a different value invalidates its observers.
+* A :class:`ComputedNode` is both an observer and a source. It is lazy: it is
+  only recomputed when read after one of its dependencies changed. Errors raised
+  by its function are cached exactly like values.
+* An :class:`Effect` is an observer that re-runs its function whenever any
+  dependency changes.
+* Notifications and effect re-runs are queued and delivered by :func:`flush`,
+  which happens immediately after a write, or when the outermost
+  :func:`batch` exits.
+
+The graph is process-global and not thread-safe: use it from one thread.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any, Callable, Dict, Iterator, List, Optional, Set
+
+__all__ = [
+    "Signal",
+    "ComputedNode",
+    "Effect",
+    "batch",
+    "untracked",
+    "effect",
+]
+
+#: Upper bound on flush rounds before we assume effects are feeding each other.
+MAX_FLUSH_ROUNDS = 100
+
+_MISSING: Any = object()
+
+
+def values_equal(old: Any, new: Any) -> bool:
+    """Return True if a write of *new* over *old* is not a change."""
+    if old is new:
+        return True
+    try:
+        return bool(old == new)
+    except Exception:  # pragma: no cover - exotic __eq__ implementations
+        return False
+
+
+class _Observer:
+    """Something that reads sources and must be told when they change."""
+
+    __slots__ = ("sources", "__weakref__")
+
+    def __init__(self) -> None:
+        self.sources: Set["_Source"] = set()
+
+    def mark_dirty(self) -> None:  # pragma: no cover - abstract
+        raise NotImplementedError
+
+    def _unlink(self) -> None:
+        for src in self.sources:
+            src.observers.discard(self)
+        self.sources.clear()
+
+
+class _Source:
+    """Something whose reads can be tracked."""
+
+    __slots__ = ()
+
+    observers: Set[_Observer]
+
+    def _track(self) -> None:
+        current = _state.current
+        if current is not None:
+            current.sources.add(self)
+            self.observers.add(current)
+
+
+class _State:
+    """Process-global scheduler state."""
+
+    def __init__(self) -> None:
+        self.current: Optional[_Observer] = None
+        self.batch_depth = 0
+        self.flushing = False
+        # Ordered "sets" (dicts keep insertion order) of pending work.
+        self.pending_hooks: Dict[int, Callable[[], None]] = {}
+        self.pending_effects: Dict[int, "Effect"] = {}
+
+    def has_work(self) -> bool:
+        return bool(self.pending_hooks or self.pending_effects)
+
+
+_state = _State()
+
+
+class Signal(_Source):
+    """A single observable value.
+
+    ``on_change`` (if given) is called synchronously on every effective write
+    with ``(old, new)``; it is how :class:`robject.RObject` records pending
+    attribute notifications.
+    """
+
+    __slots__ = ("value", "observers", "on_change")
+
+    def __init__(
+        self,
+        value: Any,
+        on_change: Optional[Callable[[Any, Any], None]] = None,
+    ) -> None:
+        self.value = value
+        self.observers: Set[_Observer] = set()
+        self.on_change = on_change
+
+    def get(self) -> Any:
+        """Return the value, recording a dependency for the running observer."""
+        self._track()
+        return self.value
+
+    def set(self, new: Any) -> None:
+        """Store *new*; if it differs from the current value, propagate."""
+        old = self.value
+        if values_equal(old, new):
+            return
+        self.value = new
+        if self.on_change is not None:
+            self.on_change(old, new)
+        for obs in list(self.observers):
+            obs.mark_dirty()
+        flush()
+
+
+class _Failure:
+    """A cached exception raised by a computed function."""
+
+    __slots__ = ("error",)
+
+    def __init__(self, error: BaseException) -> None:
+        self.error = error
+
+
+class ComputedNode(_Observer, _Source):
+    """A lazily evaluated, cached derivation of other sources.
+
+    ``on_invalidate`` (if given) is called when the node becomes dirty; it is
+    how :class:`robject.RObject` schedules re-checks of watched computed
+    properties.
+    """
+
+    __slots__ = ("fn", "observers", "dirty", "computing", "result", "on_invalidate")
+
+    def __init__(
+        self,
+        fn: Callable[[], Any],
+        on_invalidate: Optional[Callable[[], None]] = None,
+    ) -> None:
+        _Observer.__init__(self)
+        self.fn = fn
+        self.observers: Set[_Observer] = set()
+        self.dirty = True
+        self.computing = False
+        self.result: Any = _MISSING
+        self.on_invalidate = on_invalidate
+
+    def get(self) -> Any:
+        """Return the (possibly recomputed) value, recording a dependency."""
+        self._track()
+        return self.peek()
+
+    def peek(self) -> Any:
+        """Return the value without recording a dependency."""
+        if self.dirty:
+            self._recompute()
+        if isinstance(self.result, _Failure):
+            raise self.result.error
+        return self.result
+
+    def _recompute(self) -> None:
+        if self.computing:
+            raise RuntimeError("cycle detected while evaluating a computed property")
+        self._unlink()
+        self.computing = True
+        prev, _state.current = _state.current, self
+        try:
+            self.result = self.fn()
+        except Exception as exc:
+            self.result = _Failure(exc)
+        finally:
+            _state.current = prev
+            self.computing = False
+            self.dirty = False
+
+    def mark_dirty(self) -> None:
+        if self.dirty:
+            return
+        self.dirty = True
+        for obs in list(self.observers):
+            obs.mark_dirty()
+        if self.on_invalidate is not None:
+            self.on_invalidate()
+
+
+class Effect(_Observer):
+    """A side effect that re-runs whenever anything it read changes.
+
+    Create one with :func:`effect`. Call :meth:`dispose` to stop it.
+    """
+
+    __slots__ = ("fn", "disposed", "runs")
+
+    def __init__(self, fn: Callable[[], Any]) -> None:
+        super().__init__()
+        self.fn = fn
+        self.disposed = False
+        #: How many times the effect function has run.
+        self.runs = 0
+
+    def run(self) -> None:
+        """Run the effect function now, re-recording its dependencies."""
+        if self.disposed:
+            return
+        self._unlink()
+        prev, _state.current = _state.current, self
+        try:
+            self.runs += 1
+            self.fn()
+        finally:
+            _state.current = prev
+
+    def mark_dirty(self) -> None:
+        if not self.disposed:
+            _state.pending_effects.setdefault(id(self), self)
+
+    def dispose(self) -> None:
+        """Stop the effect: drop its dependencies and never run it again."""
+        self.disposed = True
+        self._unlink()
+        _state.pending_effects.pop(id(self), None)
+
+    def __enter__(self) -> "Effect":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.dispose()
+
+    def __repr__(self) -> str:
+        status = "disposed" if self.disposed else f"{len(self.sources)} deps"
+        return f"<Effect {getattr(self.fn, '__qualname__', self.fn)!s} ({status})>"
+
+
+def schedule_hook(key: int, hook: Callable[[], None]) -> None:
+    """Queue *hook* to run during the next flush (deduplicated by *key*)."""
+    _state.pending_hooks.setdefault(key, hook)
+
+
+def flush() -> None:
+    """Deliver pending notifications and re-run dirty effects.
+
+    Does nothing while inside :func:`batch` or while a flush is already in
+    progress (work queued by callbacks is picked up by the running flush).
+    Every queued callback runs even if an earlier one raised; the first
+    exception is re-raised once the queue has drained.
+    """
+    if _state.flushing or _state.batch_depth:
+        return
+    _state.flushing = True
+    # Callbacks must never be tracked as dependencies of whatever observer
+    # happened to trigger this flush.
+    prev, _state.current = _state.current, None
+    errors: List[BaseException] = []
+    try:
+        rounds = 0
+        while _state.has_work():
+            rounds += 1
+            if rounds > MAX_FLUSH_ROUNDS:
+                _state.pending_hooks.clear()
+                _state.pending_effects.clear()
+                raise RuntimeError(
+                    f"reactive updates did not settle after {MAX_FLUSH_ROUNDS} "
+                    "rounds; an effect or subscriber probably writes to "
+                    "something it depends on"
+                )
+            hooks = list(_state.pending_hooks.values())
+            effects = list(_state.pending_effects.values())
+            _state.pending_hooks.clear()
+            _state.pending_effects.clear()
+            for hook in hooks:
+                try:
+                    hook()
+                except Exception as exc:
+                    errors.append(exc)
+            for eff in effects:
+                try:
+                    eff.run()
+                except Exception as exc:
+                    errors.append(exc)
+    finally:
+        _state.current = prev
+        _state.flushing = False
+    if errors:
+        raise errors[0]
+
+
+@contextlib.contextmanager
+def batch() -> Iterator[None]:
+    """Group writes so subscribers and effects run once, at the end.
+
+    Nested batches are allowed; delivery happens when the outermost one exits
+    (also when it exits with an exception, so no change is silently lost).
+    Usable as a context manager or as a decorator::
+
+        with batch():
+            cart.price = 3
+            cart.qty = 2
+    """
+    _state.batch_depth += 1
+    try:
+        yield
+    finally:
+        _state.batch_depth -= 1
+        if _state.batch_depth == 0:
+            flush()
+
+
+@contextlib.contextmanager
+def untracked() -> Iterator[None]:
+    """Read reactive values without recording them as dependencies."""
+    prev, _state.current = _state.current, None
+    try:
+        yield
+    finally:
+        _state.current = prev
+
+
+def effect(fn: Callable[[], Any]) -> Effect:
+    """Run *fn* now and again whenever any reactive value it read changes.
+
+    Returns the :class:`Effect`; call ``.dispose()`` (or use it as a context
+    manager) to stop it. If the first run raises, the effect is disposed and
+    the exception propagates. Usable as a decorator::
+
+        @effect
+        def log():
+            print(cart.total)
+    """
+    eff = Effect(fn)
+    try:
+        eff.run()
+    except BaseException:
+        eff.dispose()  # the caller never receives it, so it must not linger
+        raise
+    return eff

robject/_object.py

@@ -0,0 +1,428 @@
+"""The :class:`RObject` base class and its module-level helpers."""
+
+from __future__ import annotations
+
+import inspect
+import typing
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Dict,
+    Generic,
+    List,
+    NamedTuple,
+    Optional,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    overload,
+)
+
+from ._core import _MISSING, ComputedNode, Signal, schedule_hook, values_equal
+
+__all__ = ["RObject", "field", "computed", "Change", "subscribe", "fields", "snapshot"]
+
+T = TypeVar("T")
+
+_MUTABLE_DEFAULTS = (list, dict, set, bytearray)
+
+
+class Change(NamedTuple):
+    """One delivered change: attribute *name* of *obj* went from *old* to *new*.
+
+    For a computed property whose previous evaluation raised, *old* is ``None``.
+    """
+
+    obj: "RObject"
+    name: str
+    old: Any
+    new: Any
+
+
+# --------------------------------------------------------------------------
+# Field declarations
+# --------------------------------------------------------------------------
+
+
+class _FieldSpec:
+    """Declaration-time configuration of one reactive field."""
+
+    __slots__ = ("name", "default", "default_factory")
+
+    def __init__(
+        self,
+        default: Any = _MISSING,
+        default_factory: Optional[Callable[[], Any]] = None,
+    ) -> None:
+        if default is not _MISSING and default_factory is not None:
+            raise ValueError("cannot specify both default and default_factory")
+        self.name = ""
+        self.default = default
+        self.default_factory = default_factory
+
+    @property
+    def required(self) -> bool:
+        return self.default is _MISSING and self.default_factory is None
+
+    def make_default(self) -> Any:
+        if self.default_factory is not None:
+            return self.default_factory()
+        return self.default
+
+    def __repr__(self) -> str:
+        return f"field(name={self.name!r})"
+
+
+def field(
+    *,
+    default: Any = _MISSING,
+    default_factory: Optional[Callable[[], Any]] = None,
+) -> Any:
+    """Declare a reactive field with an explicit default or default factory.
+
+    Plain ``name: type = value`` annotations already create fields; use this
+    for mutable defaults::
+
+        class Todo(RObject):
+            tags: list = field(default_factory=list)
+    """
+    return _FieldSpec(default, default_factory)
+
+
+class _FieldDescriptor:
+    """Class-level descriptor that routes attribute access to a Signal."""
+
+    def __init__(self, spec: _FieldSpec) -> None:
+        self.spec = spec
+        self.name = spec.name
+
+    def __get__(self, obj: Optional["RObject"], objtype: Any = None) -> Any:
+        if obj is None:
+            if self.spec.default is not _MISSING:
+                return self.spec.default
+            raise AttributeError(self.name)
+        return _rstate(obj).signals[self.name].get()
+
+    def __set__(self, obj: "RObject", value: Any) -> None:
+        _rstate(obj).signals[self.name].set(value)
+
+
+class computed(Generic[T]):
+    """Decorator for a cached, dependency-tracked, read-only property.
+
+    The function runs lazily on first access and again only after a reactive
+    value it read has changed. Exceptions are cached and re-raised on access
+    until a dependency changes::
+
+        class Cart(RObject):
+            price: float = 0.0
+            qty: int = 1
+
+            @computed
+            def total(self) -> float:
+                return self.price * self.qty
+    """
+
+    def __init__(self, fn: Callable[[Any], T]) -> None:
+        self.fn = fn
+        self.name: str = fn.__name__
+        self.__doc__ = fn.__doc__
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.name = name
+
+    @overload
+    def __get__(self, obj: None, objtype: Any = None) -> "computed[T]": ...
+
+    @overload
+    def __get__(self, obj: "RObject", objtype: Any = None) -> T: ...
+
+    def __get__(self, obj: Optional["RObject"], objtype: Any = None) -> Any:
+        if obj is None:
+            return self
+        return _rstate(obj).node(self.name).get()
+
+    def __set__(self, obj: "RObject", value: Any) -> None:
+        raise AttributeError(f"computed property {self.name!r} is read-only")
+
+
+# --------------------------------------------------------------------------
+# Per-instance state
+# --------------------------------------------------------------------------
+
+
+class _Subscription:
+    __slots__ = ("callback", "names", "active")
+
+    def __init__(self, callback: Callable[[Change], Any], names: Optional[frozenset]) -> None:
+        self.callback = callback
+        self.names = names
+        self.active = True
+
+    def wants(self, name: str) -> bool:
+        return self.names is None or name in self.names
+
+
+class _RState:
+    """Reactive bookkeeping attached to one RObject instance."""
+
+    __slots__ = (
+        "obj",
+        "signals",
+        "nodes",
+        "subs",
+        "pending_fields",
+        "pending_computed",
+        "baselines",
+    )
+
+    def __init__(self, obj: "RObject") -> None:
+        self.obj = obj
+        self.signals: Dict[str, Signal] = {}
+        self.nodes: Dict[str, ComputedNode] = {}
+        self.subs: List[_Subscription] = []
+        self.pending_fields: Dict[str, Any] = {}  # name -> value before first change
+        self.pending_computed: Dict[str, None] = {}  # set of names
+        self.baselines: Dict[str, Any] = {}  # computed name -> last delivered value
+
+    # -- construction -----------------------------------------------------
+
+    def add_signal(self, name: str, value: Any) -> None:
+        self.signals[name] = Signal(value, on_change=lambda old, new: self._field_changed(name, old))
+
+    def node(self, name: str) -> ComputedNode:
+        node = self.nodes.get(name)
+        if node is None:
+            prop: computed[Any] = type(self.obj).__robject_computed__[name]
+            obj = self.obj
+            node = ComputedNode(lambda: prop.fn(obj), on_invalidate=lambda: self._computed_invalidated(name))
+            self.nodes[name] = node
+        return node
+
+    # -- change recording ---------------------------------------------------
+
+    def watched(self, name: str) -> bool:
+        return any(sub.wants(name) for sub in self.subs)
+
+    def _field_changed(self, name: str, old: Any) -> None:
+        if not self.watched(name):
+            return
+        self.pending_fields.setdefault(name, old)
+        schedule_hook(id(self), self.deliver)
+
+    def _computed_invalidated(self, name: str) -> None:
+        if not self.watched(name):
+            return
+        self.pending_computed[name] = None
+        schedule_hook(id(self), self.deliver)
+
+    # -- delivery -----------------------------------------------------------
+
+    def deliver(self) -> None:
+        """Turn pending records into Change events and call subscribers."""
+        pending_fields, self.pending_fields = self.pending_fields, {}
+        pending_computed, self.pending_computed = self.pending_computed, {}
+        errors: List[BaseException] = []
+        changes: List[Change] = []
+
+        for name, old in pending_fields.items():
+            new = self.signals[name].value
+            if not values_equal(old, new):  # coalesced writes may cancel out
+                changes.append(Change(self.obj, name, old, new))
+
+        # Declaration order, not invalidation order, so delivery is predictable.
+        for name in type(self.obj).__robject_computed__:
+            if name not in pending_computed or not self.watched(name):
+                continue
+            old = self.baselines.get(name, _MISSING)
+            try:
+                new = self.nodes[name].peek()
+            except Exception as exc:
+                errors.append(exc)
+                continue
+            self.baselines[name] = new
+            if old is _MISSING or not values_equal(old, new):
+                changes.append(Change(self.obj, name, None if old is _MISSING else old, new))
+
+        for change in changes:
+            for sub in list(self.subs):
+                if sub.active and sub.wants(change.name):
+                    try:
+                        sub.callback(change)
+                    except Exception as exc:
+                        errors.append(exc)
+        if errors:
+            raise errors[0]
+
+    def subscribe(self, callback: Callable[[Change], Any], names: Optional[frozenset]) -> Callable[[], None]:
+        sub = _Subscription(callback, names)
+        newly_watched = [
+            name
+            for name in type(self.obj).__robject_computed__
+            if sub.wants(name) and not self.watched(name)
+        ]
+        self.subs.append(sub)
+        for name in newly_watched:
+            try:
+                self.baselines[name] = self.node(name).peek()
+            except Exception:
+                self.baselines.pop(name, None)
+
+        def unsubscribe() -> None:
+            if sub.active:
+                sub.active = False
+                self.subs.remove(sub)
+
+        return unsubscribe
+
+
+def _rstate(obj: "RObject") -> _RState:
+    try:
+        return obj.__dict__["_robject_state"]
+    except KeyError:
+        raise RuntimeError(
+            f"{type(obj).__name__} instance is not initialised; "
+            "did a custom __init__ forget to call super().__init__()?"
+        ) from None
+
+
+# --------------------------------------------------------------------------
+# RObject
+# --------------------------------------------------------------------------
+
+
+def _is_classvar(annotation: Any) -> bool:
+    if annotation is ClassVar or typing.get_origin(annotation) is ClassVar:
+        return True
+    return isinstance(annotation, str) and annotation.startswith(("ClassVar", "typing.ClassVar"))
+
+
+def _own_annotations(cls: type) -> Dict[str, Any]:
+    try:
+        return dict(inspect.get_annotations(cls))
+    except Exception:  # unresolved forward references on newer Pythons
+        return dict(cls.__dict__.get("__annotations__", {}))
+
+
+class RObject:
+    """Base class for objects with reactive (observable) attributes.
+
+    Every annotated class attribute becomes a reactive field; methods decorated
+    with :class:`computed` become cached derived properties. Construct
+    instances with keyword arguments::
+
+        class Point(RObject):
+            x: float = 0.0
+            y: float = 0.0
+
+        p = Point(x=1.0)
+
+    Subclasses that define ``__init__`` must call ``super().__init__(**kwargs)``.
+    """
+
+    __robject_fields__: ClassVar[Dict[str, _FieldSpec]] = {}
+    __robject_computed__: ClassVar[Dict[str, computed[Any]]] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        specs: Dict[str, _FieldSpec] = {}
+        props: Dict[str, computed[Any]] = {}
+        for base in reversed(cls.__mro__[1:]):
+            specs.update(getattr(base, "__robject_fields__", {}))
+            props.update(getattr(base, "__robject_computed__", {}))
+
+        annotations = _own_annotations(cls)
+        own = cls.__dict__
+        for name, value in own.items():
+            if isinstance(value, computed):
+                props[name] = value
+                specs.pop(name, None)
+            elif name in specs and name not in annotations:
+                # Redefining an inherited field's default: `x = 5`.
+                annotations[name] = None
+        for name, annotation in annotations.items():
+            if _is_classvar(annotation) or isinstance(own.get(name), computed):
+                continue
+            value = own.get(name, _MISSING)
+            if isinstance(value, _FieldSpec):
+                spec = value
+            elif value is _MISSING and name in specs:
+                continue  # re-annotated without a new default: keep inherited
+            else:
+                if isinstance(value, _MUTABLE_DEFAULTS):
+                    raise ValueError(
+                        f"mutable default {type(value).__name__} for field {name!r} "
+                        "is not allowed: use field(default_factory=...)"
+                    )
+                spec = _FieldSpec(value)
+            spec.name = name
+            specs[name] = spec
+            props.pop(name, None)
+            setattr(cls, name, _FieldDescriptor(spec))
+
+        cls.__robject_fields__ = specs
+        cls.__robject_computed__ = props
+
+    def __init__(self, **kwargs: Any) -> None:
+        state = _RState(self)
+        self.__dict__["_robject_state"] = state
+        specs = type(self).__robject_fields__
+        unknown = sorted(set(kwargs) - set(specs))
+        if unknown:
+            raise TypeError(f"{type(self).__name__}() got unexpected field(s): {', '.join(unknown)}")
+        missing = [n for n, s in specs.items() if s.required and n not in kwargs]
+        if missing:
+            raise TypeError(f"{type(self).__name__}() missing required field(s): {', '.join(missing)}")
+        for name, spec in specs.items():
+            state.add_signal(name, kwargs[name] if name in kwargs else spec.make_default())
+
+    def __repr__(self) -> str:
+        state = self.__dict__.get("_robject_state")
+        if state is None:
+            return f"<uninitialised {type(self).__name__}>"
+        parts = ", ".join(f"{n}={s.value!r}" for n, s in state.signals.items())
+        return f"{type(self).__name__}({parts})"
+
+
+# --------------------------------------------------------------------------
+# Module-level helpers (kept off the class so they never clash with fields)
+# --------------------------------------------------------------------------
+
+
+def subscribe(obj: RObject, callback: Callable[[Change], Any], *names: str) -> Callable[[], None]:
+    """Call ``callback(change)`` whenever an attribute of *obj* changes.
+
+    With no *names*, every field and computed property is watched; otherwise
+    only the named ones. Watched computed properties are re-evaluated eagerly
+    after their dependencies change and notify only if their value differs.
+    Inside :func:`batch`, repeated writes to one attribute are coalesced into a
+    single change (and dropped if the final value equals the original).
+
+    Returns a function that cancels the subscription.
+    """
+    cls = type(obj)
+    known = set(cls.__robject_fields__) | set(cls.__robject_computed__)
+    bad = [n for n in names if n not in known]
+    if bad:
+        raise ValueError(f"{cls.__name__} has no reactive attribute(s): {', '.join(bad)}")
+    return _rstate(obj).subscribe(callback, frozenset(names) if names else None)
+
+
+def fields(obj_or_cls: Union[RObject, Type[RObject]]) -> Tuple[str, ...]:
+    """Return the names of the reactive fields, in declaration order."""
+    cls = obj_or_cls if isinstance(obj_or_cls, type) else type(obj_or_cls)
+    return tuple(cls.__robject_fields__)
+
+
+def snapshot(obj: RObject, *, include_computed: bool = False) -> Dict[str, Any]:
+    """Return a plain ``dict`` of the field values (and optionally computed ones).
+
+    Reads go through the normal attribute path, so calling this inside an
+    effect makes the effect depend on every included attribute.
+    """
+    names = list(type(obj).__robject_fields__)
+    if include_computed:
+        names += list(type(obj).__robject_computed__)
+    return {name: getattr(obj, name) for name in names}

robject-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: robject
+Version: 0.1.0
+Summary: Reactive objects for Python: observable fields, auto-tracked computed properties, effects, subscriptions and batching.
+Author: nehz
+License-Expression: MIT
+Project-URL: Homepage, https://example.com/robject
+Keywords: reactive,observable,signals,computed,state,observer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# robject
+
+**Reactive objects for Python.** Declare a class the way you would a dataclass,
+and its attributes become observable. Derived values recompute only when what
+they read actually changed, side effects re-run automatically, and a burst of
+writes can be grouped into a single notification.
+
+It's the signals / computed / effect model from modern UI frameworks, packaged
+as plain Python classes. Pure standard library, no dependencies.
+
+```python
+from robject import RObject, computed, effect, batch
+
+class Cart(RObject):
+    price: float = 0.0
+    qty: int = 1
+
+    @computed
+    def total(self) -> float:
+        return self.price * self.qty
+
+cart = Cart(price=2.5)
+effect(lambda: print("total is", cart.total))   # prints: total is 2.5
+
+with batch():
+    cart.price = 3.0
+    cart.qty = 4
+# prints once: total is 12.0
+```
+
+## Features
+
+- **Reactive fields** from ordinary class annotations, with defaults,
+  required fields, `field(default_factory=...)` and inheritance.
+- **`@computed` properties**: lazy, cached and read-only. Dependencies are tracked
+  automatically, including dynamic ones (branches) and ones on other objects.
+  Exceptions are cached too, and cycles are detected.
+- **Effects** re-run whenever anything they read changes. They are glitch-free:
+  an effect never sees a half-updated state.
+- **Subscriptions** deliver `Change(obj, name, old, new)` events for fields and
+  computed properties. A computed property notifies only when its value really
+  changes.
+- **Batching** coalesces writes. Subscribers get one event per attribute (none
+  if the value ends up back where it started), and effects run once.
+- **Safety rails**: an error in one callback doesn't stop the others (the first
+  one is re-raised afterwards), and runaway feedback loops raise instead of hanging.
+- Typed (`py.typed`), standard library only, Python 3.10+.
+
+## Install
+
+From a checkout (the package is not published to PyPI):
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install .
+```
+
+## Quickstart
+
+```python
+from robject import RObject, Change, batch, computed, effect, field, subscribe
+
+class Todo(RObject):
+    title: str                                 # required
+    done: bool = False
+    tags: list = field(default_factory=list)   # mutable defaults need a factory
+
+class TodoList(RObject):
+    items: tuple = ()
+
+    @computed
+    def remaining(self) -> int:
+        return sum(not t.done for t in self.items)
+
+todos = TodoList(items=(Todo(title="write docs"), Todo(title="ship")))
+
+# Subscribe to specific attributes (or all of them, by passing no names).
+unsubscribe = subscribe(todos, lambda ch: print(f"{ch.name}: {ch.old} -> {ch.new}"), "remaining")
+
+todos.items[0].done = True          # prints: remaining: 2 -> 1
+
+# Effects track whatever they read, across objects.
+watcher = effect(lambda: print("left:", todos.remaining))   # prints: left: 1
+
+with batch():                       # delivery waits until the block ends
+    todos.items[1].done = True      # remaining: 1 -> 0 ...
+    todos.items = todos.items + (Todo(title="celebrate"),)   # ... -> 1
+# The effect re-runs once and prints: left: 1
+# `remaining` ended where it started, so the subscriber prints nothing.
+
+watcher.dispose()
+unsubscribe()
+```
+
+Fields are tracked by assignment. Mutating a list in place (`todo.tags.append(...)`)
+is invisible, so assign a new value instead (`todo.tags = [*todo.tags, "x"]`), or use
+immutable containers such as tuples.
+
+## API overview
+
+Everything below is importable from `robject`.
+
+| Name | Description |
+| --- | --- |
+| `RObject` | Base class. Annotated class attributes become reactive fields (except `ClassVar`). Instances are constructed with keyword arguments only. Unknown names and missing required fields raise `TypeError`. A subclass that defines `__init__` must call `super().__init__(**kwargs)`. `repr()` shows the field values. |
+| `field(*, default=..., default_factory=None)` | Explicit field declaration. You need it for mutable defaults: a bare `list`/`dict`/`set`/`bytearray` default raises `ValueError`. |
+| `computed` | Decorator for a lazy, cached, read-only property whose dependencies are tracked. Assigning to it raises `AttributeError`. Exceptions are cached until a dependency changes, and self-reference raises `RuntimeError("cycle detected ...")`. |
+| `effect(fn) -> Effect` | Runs `fn()` now and again after any reactive value it read changes. If the first run raises, the effect is disposed and the exception propagates. Also works as a decorator. |
+| `Effect` | Returned by `effect`. Has `.dispose()`, `.run()`, a `.runs` counter and `.disposed`. It is also a context manager that disposes on exit. |
+| `subscribe(obj, callback, *names) -> unsubscribe` | Calls `callback(Change)` when the named fields or computed properties of `obj` change. With no names it watches all of them. Unknown names raise `ValueError`. Watched computed properties are re-evaluated eagerly. The returned function cancels the subscription and is idempotent. |
+| `Change` | `NamedTuple(obj, name, old, new)`. For a computed property whose previous evaluation raised, `old` is `None`. |
+| `batch()` | Context manager (and decorator) that defers delivery until the outermost batch exits, including on exception. Reads inside a batch already see the new values. |
+| `untracked()` | Context manager. Reads inside it don't become dependencies. |
+| `fields(obj_or_cls) -> tuple[str, ...]` | Field names in declaration order, with base classes first. |
+| `snapshot(obj, *, include_computed=False) -> dict` | Plain `dict` of the current values. Reading it inside an effect makes the effect depend on every included attribute. |
+| `__version__` | `"0.1.0"` |
+
+### Semantics worth knowing
+
+- A write that is `==` to the current value is a no-op.
+- Outside a batch, delivery is synchronous: by the time an assignment returns,
+  subscribers and effects have run.
+- Subscribers and effects may write to reactive values. Their work is processed
+  in further rounds of the same flush. If 100 rounds pass without settling, the
+  flush raises `RuntimeError("reactive updates did not settle ...")`.
+- An effect's own reads are tracked; reads made by callbacks it triggers are not.
+- The reactive graph is process-global and **not thread-safe**. Use it from one
+  thread, such as a UI or event-loop thread.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+The tests use only `unittest`, so `python3 -m pytest` works too if you have pytest.
+
+## License
+
+MIT

robject-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+robject/__init__.py,sha256=x05mKUDF38fT6EkYWzNMIROYSAkPlBuzLIksM7_Pz1s,878
+robject/_core.py,sha256=75EXFSLPhhVQ_YZMfKpyGkkFuZf98Uy83hmpN9eMDQ0,10805
+robject/_object.py,sha256=fNe1CA71J45t2OTp85_K_yRkjXWsIihbyg7Utm0Xs1Y,15111
+robject/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+robject-0.1.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+robject-0.1.0.dist-info/METADATA,sha256=XhZCL2wHsAVHIU3LRwTiUWC8yqDgudsYfP3-amrDCdY,7482
+robject-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+robject-0.1.0.dist-info/top_level.txt,sha256=xO157N6oXUedXt7mIGC7c6yG-zibrMIcUG49pG2tVbI,8
+robject-0.1.0.dist-info/RECORD,,

robject-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

robject-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

robject-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+robject