nervio 0.2.0__py3-none-any.whl

nervio/__init__.py

@@ -0,0 +1,575 @@
+"""nervio — reactividad de grano fino, sin dependencias.
+
+signal / computed / effect con tracking automático de dependencias y
+propagación *pull* glitch-free (estados clean/check/dirty, estilo Reactively):
+los `computed` se recalculan perezosamente y solo si una dependencia real cambió;
+los diamantes (A→B, A→C, B+C→D) nunca producen lecturas inconsistentes ni
+recálculos de más.
+"""
+from __future__ import annotations
+
+import operator
+import sys
+import threading
+import weakref
+from collections import deque
+from typing import Callable, Generic, List, TypeVar
+
+T = TypeVar("T")
+
+__all__ = [
+    "signal", "computed", "effect", "batch", "untrack", "root", "on_cleanup",
+    "Signal", "Computed",
+]
+__version__ = "0.2.0"
+
+_CLEAN, _CHECK, _DIRTY = 0, 1, 2
+
+# Un único lock reentrante serializa toda mutación del grafo: escrituras, tracking,
+# recomputos, flush y disposición. Corrección primero: varios hilos pueden tocar el
+# MISMO grafo sin corromper sus listas internas (observers/sources) y sin glitches
+# entre hilos. Nunca se sostiene a través de un `await` (la librería no tiene puntos
+# async), así que no introduce deadlocks propios; la regla para el usuario es no
+# bloquear dentro de un effect/computed esperando a otro hilo que también use señales.
+_lock = threading.RLock()
+
+
+class _Scope:
+    """Estado vivo de un ámbito de ejecución: observador en curso (tracking), dueño
+    actual (cleanups/disposición), cola de effects y profundidad de batch.
+
+    El ámbito se resuelve por identidad de ejecución —la tarea asyncio actual o, en
+    su defecto, el hilo— y NO por contextvars: `asyncio.create_task(...)` copia el
+    contexto del padre, y heredar su batch/observador dejaba effects diferidos para
+    siempre (el hijo nunca puede cerrar un batch ajeno) y suscripciones fantasma.
+    Cada tarea e hilo estrena ámbito limpio.
+    """
+
+    __slots__ = ("observer", "owner", "batch_depth", "flushing", "pending", "__weakref__")
+
+    def __init__(self):
+        self.observer = None      # nodo en ejecución, para auto-tracking
+        self.owner = None         # dueño actual, para cleanups/disposición
+        self.batch_depth = 0
+        self.flushing = False
+        self.pending = deque()    # effects en cola para correr tras una escritura/batch
+
+
+class _ThreadScope(threading.local):
+    def __init__(self):
+        self.scope = _Scope()
+
+
+_thread_scope = _ThreadScope()
+# tarea asyncio -> ámbito; claves débiles: al morir la tarea, su ámbito se libera solo
+_task_scopes: "weakref.WeakKeyDictionary" = weakref.WeakKeyDictionary()
+
+# Ancla de los effects vivos. Las referencias fuente->observador son DÉBILES (un
+# computed abandonado se recolecta solo), así que algo tiene que retener a los
+# effects aunque el usuario tire el handle de dispose: viven aquí hasta su
+# dispose() explícito (o el de su root). Mutado solo bajo _lock.
+_live_effects: set = set()
+
+
+def _scope() -> _Scope:
+    """Ámbito del ejecutor actual: la tarea asyncio si la hay; si no, el hilo."""
+    aio = sys.modules.get("asyncio")  # no importa asyncio si el usuario no lo usa
+    if aio is not None:
+        current = getattr(aio, "current_task", None)  # tolera stubs/imports parciales
+        task = None
+        if current is not None:
+            try:
+                task = current()
+            except RuntimeError:      # sin event loop corriendo en este hilo
+                task = None
+        if task is not None:
+            with _lock:
+                sc = _task_scopes.get(task)
+                if sc is None:
+                    sc = _task_scopes[task] = _Scope()
+                return sc
+    return _thread_scope.scope
+
+
+def _never_equal(_a, _b) -> bool:
+    return False
+
+
+class _Node:
+    """Nodo del grafo reactivo. Signal: fn=None. Computed/Effect: fn dado."""
+
+    def __init__(self, value=None, fn=None, equals=None, is_effect=False):
+        self._value = value
+        self.fn = fn
+        if equals is None:
+            self.equals = operator.eq
+        elif equals is False:
+            self.equals = _never_equal
+        else:
+            self.equals = equals
+        # computed/effect arrancan sucios (necesitan primer cómputo); signal limpio.
+        self.state = _CLEAN if fn is None else _DIRTY
+        self.sources: List["_Node"] = []          # refs FUERTES hacia abajo
+        self.observers: List["weakref.ref"] = []  # refs DÉBILES hacia arriba
+        self.is_effect = is_effect
+        self.cleanups: List[Callable[[], None]] = []
+        self.owned: List["_Node"] = []
+        self.disposed = False
+        # weakref al _Scope en cuya cola espera este effect, o None si no espera en
+        # ninguna. Si el scope dueño muere (hilo/tarea abandonados con cola no vacía),
+        # el siguiente escritor lo detecta y lo adopta: ningún effect queda mudo.
+        self._queued_in = None
+        # True mientras corre el propio _recompute: reentrar ahí es un ciclo
+        # (el nodo se lee/escribe a sí mismo, directa o indirectamente).
+        self._computing = False
+
+    # --- lectura con tracking -------------------------------------------------
+    def _get(self):
+        with _lock:
+            obs = _scope().observer
+            if obs is not None and obs is not self and self not in obs.sources:
+                obs.sources.append(self)
+                refs = self.observers
+                if len(refs) >= 64 and not len(refs) % 64:
+                    self._live_observers()  # compactación oportunista: una señal que
+                    #                          nunca cambia no acumula refs muertas
+                # ref débil hacia arriba: la fuente no retiene a su observador
+                # (weakref.ref devuelve la ref canónica cacheada del objeto)
+                refs.append(weakref.ref(obs))
+            if self.fn is not None:
+                self._update_if_necessary()
+            return self._value
+
+    def _live_observers(self):
+        """Observadores vivos (deref de las weakrefs), compactando las muertas.
+
+        source->observer es débil: un computed abandonado (sin refs del usuario
+        ni de nodos aguas abajo) se recolecta solo en vez de quedar retenido
+        para siempre por sus fuentes. Se llama con _lock tomado."""
+        refs = self.observers
+        live, live_refs = [], []
+        for r in refs:
+            o = r()
+            if o is not None:
+                live.append(o)
+                live_refs.append(r)
+        if len(live_refs) != len(refs):
+            refs[:] = live_refs
+        return live
+
+    def _peek(self):
+        if self.fn is None:
+            return self._value
+        with _lock:
+            self._update_if_necessary()
+            return self._value
+
+    # --- propagación (fase de marcado, barata; se llama con _lock tomado) ------
+    def _mark(self, state):
+        if self.state < state:
+            self.state = state
+            if self.is_effect:
+                self._enqueue()
+            # recorrido iterativo en preorden DFS (mismo orden de encolado que la
+            # versión recursiva): grafos de profundidad arbitraria sin RecursionError
+            stack = list(reversed(self._live_observers()))
+            while stack:
+                o = stack.pop()
+                if o.state < _CHECK:   # primera marca: propaga a su subgrafo
+                    o.state = _CHECK
+                    if o.is_effect:
+                        o._enqueue()
+                    stack.extend(reversed(o._live_observers()))
+                elif o.is_effect:      # ya estaba sucio: chequeo de adopción
+                    o._enqueue()
+        elif self.is_effect and self.state != _CLEAN and not self._computing:
+            # ya estaba sucio: si su cola murió, el escritor lo adopta. Nunca mientras
+            # _computing: esa marca viene de su propio run (p.ej. un computed fresco
+            # recién calculado dentro de él) y encolarla dejaría una entrada fantasma
+            # que bloquearía la adopción desde otros hilos/tareas.
+            self._enqueue()
+
+    def _enqueue(self):
+        # Idempotente: no encola si ya espera en la cola de un scope vivo. Si su
+        # cola murió con el scope (weakref muerta), lo encola el scope actual.
+        if self._queued_in is not None and self._queued_in() is not None:
+            return
+        sc = _scope()
+        sc.pending.append(self)
+        self._queued_in = weakref.ref(sc)
+
+    # --- resolución perezosa (fase de pull; se llama con _lock tomado) ---------
+    def _update_if_necessary(self):
+        if self.state == _CLEAN:
+            return
+        if self.state == _DIRTY:
+            self._recompute()
+            self.state = _CLEAN
+            return
+        # _CHECK: resuelve las fuentes primero y recomputa solo si alguna lo
+        # ensució. Descenso con pila explícita (no recursión): cadenas de miles
+        # de computeds no revientan el stack. Nota: en grafo CALIENTE las fn de
+        # usuario leen fuentes ya resueltas y no anidan; solo la primera
+        # evaluación de una cadena fría anida frames (límite: stack de Python).
+        stack = [[self, 0]]
+        on_path = {id(self)}  # guardia de ciclo: sin ella un ciclo seria bucle infinito
+        while stack:
+            frame = stack[-1]
+            node = frame[0]
+            if node.state == _DIRTY:  # una fuente lo ensució (o arrancó sucio)
+                node._recompute()
+                node.state = _CLEAN
+                on_path.discard(id(node))
+                stack.pop()
+                continue
+            if node.state == _CHECK:
+                srcs = node.sources
+                i = frame[1]
+                pushed = False
+                while i < len(srcs):
+                    src = srcs[i]
+                    i += 1
+                    if src.state != _CLEAN:
+                        if id(src) in on_path:
+                            raise RuntimeError(
+                                "nervio: ciclo reactivo detectado entre computeds")
+                        frame[1] = i
+                        stack.append([src, 0])
+                        on_path.add(id(src))
+                        pushed = True
+                        break
+                if pushed:
+                    continue
+                node.state = _CLEAN  # ninguna fuente cambió: limpio sin recomputar
+            on_path.discard(id(node))
+            stack.pop()
+
+    def _recompute(self):
+        if self._computing:
+            raise RuntimeError(
+                "nervio: ciclo reactivo: el computed/effect participa en su propio "
+                "recálculo (se lee o se fuerza a sí mismo, directa o indirectamente)")
+        self._computing = True
+        try:
+            self._run_cleanups()
+            old_sources = self.sources[:]
+            for src in self.sources:  # re-tracking limpio: deps dinámicas correctas
+                try:
+                    src.observers.remove(weakref.ref(self))
+                except ValueError:
+                    pass  # la ref pudo compactarse ya
+            self.sources.clear()
+            sc = _scope()
+            prev_obs, prev_owner = sc.observer, sc.owner
+            sc.observer = sc.owner = self
+            try:
+                new = self.fn()
+            except BaseException:
+                # fn falló a medias: conserva también las dependencias del run anterior,
+                # así toda escritura que antes lo despertaba sigue despertándolo (sin
+                # esto, una dep aún no releída al lanzar quedaría desuscrita y muda).
+                for src in old_sources:
+                    if not src.disposed and src not in self.sources:
+                        self.sources.append(src)
+                        src.observers.append(weakref.ref(self))
+                raise
+            finally:
+                sc.observer, sc.owner = prev_obs, prev_owner
+            if self.is_effect:
+                self._value = new
+            elif not self.equals(self._value, new):
+                self._value = new
+                for o in self._live_observers():
+                    o._mark(_DIRTY)
+        finally:
+            self._computing = False
+
+    # --- limpieza y disposición ----------------------------------------------
+    def _run_cleanups(self):
+        # Un cleanup (o el dispose de un hijo) que lanza no aborta a los demás, y
+        # las listas SIEMPRE se vacían: el cleanup roto no queda re-registrado, así
+        # que no envenena los runs futuros. Corren todos; el primer error se
+        # re-lanza al final (un KeyboardInterrupt/CancelledError posterior desplaza
+        # a un Exception anterior para no quedar enmascarado).
+        error = None
+        for child in self.owned:
+            try:
+                child._dispose()
+            except BaseException as exc:
+                if error is None or (isinstance(error, Exception)
+                                     and not isinstance(exc, Exception)):
+                    error = exc
+        self.owned.clear()
+        for fn in reversed(self.cleanups):
+            try:
+                fn()
+            except BaseException as exc:
+                if error is None or (isinstance(error, Exception)
+                                     and not isinstance(exc, Exception)):
+                    error = exc
+        self.cleanups.clear()
+        if error is not None:
+            raise error
+
+    def _dispose(self):
+        error = None
+        with _lock:
+            if self.disposed:
+                return
+            self.disposed = True
+            try:
+                self._run_cleanups()
+            except BaseException as exc:
+                error = exc  # el desmontaje se completa igual; se re-lanza al final:
+                #              un cleanup roto no puede dejar un nodo a medio disponer
+            for src in self.sources:
+                try:
+                    src.observers.remove(weakref.ref(self))
+                except ValueError:
+                    pass
+            self.sources.clear()
+            for r in self.observers:    # simetría: quitarse de las sources de quien
+                obs = r()
+                if obs is None:
+                    continue
+                try:                    # lo observa, o su próximo re-tracking revienta
+                    obs.sources.remove(self)
+                except ValueError:
+                    pass
+            self.observers.clear()
+            self.state = _CLEAN
+            _live_effects.discard(self)  # un effect dispuesto suelta su ancla
+            self.fn = None  # suelta la clausura: un handle de dispose retenido no
+            #                 debe fijar en memoria el subgrafo que aquella capturaba
+        if error is not None:
+            raise error
+
+
+class Signal(_Node, Generic[T]):
+    """Estado reactivo. Lee con `.value` (suscribe) o `.peek()` (no); escribe con `.value=`/`.set()`."""
+
+    def __init__(self, value: T, *, equals=None):
+        super().__init__(value=value, fn=None, equals=equals)
+
+    @property
+    def value(self) -> T:
+        return self._get()
+
+    @value.setter
+    def value(self, v: T) -> None:
+        self.set(v)
+
+    def peek(self) -> T:
+        """Lee el valor sin suscribirse. Lock-free: bajo concurrencia puede ver el
+        valor inmediatamente anterior a una escritura en curso de otro hilo."""
+        return self._value
+
+    def set(self, v: T) -> T:
+        """Asigna v; propaga solo si difiere del actual. Devuelve v."""
+        with _lock:
+            if not self.equals(self._value, v):
+                self._value = v
+                for o in self._live_observers():
+                    o._mark(_DIRTY)
+                _flush()
+        return v
+
+    def update(self, fn: Callable[[T], T]) -> T:
+        """Asigna fn(actual) de forma atómica (leer-modificar-escribir bajo el lock:
+        seguro entre hilos, sin updates perdidos). Devuelve el nuevo valor."""
+        with _lock:
+            return self.set(fn(self._value))
+
+    def __call__(self) -> T:
+        return self._get()
+
+    def __repr__(self) -> str:
+        return f"Signal({self._value!r})"
+
+
+class Computed(_Node, Generic[T]):
+    """Valor derivado, cacheado y perezoso: recalcula al leerse solo si cambió una dependencia."""
+
+    def __init__(self, fn: Callable[[], T], *, equals=None):
+        super().__init__(value=None, fn=fn, equals=equals)
+        _attach(self)
+
+    @property
+    def value(self) -> T:
+        return self._get()
+
+    def peek(self) -> T:
+        """Lee (recalculando si hace falta) sin suscribirse."""
+        return self._peek()
+
+    def __call__(self) -> T:
+        return self._get()
+
+    def __repr__(self) -> str:
+        st = ("clean", "check", "dirty")[self.state]
+        return f"Computed(state={st})"
+
+
+def _attach(node: _Node) -> None:
+    with _lock:
+        owner = _scope().owner
+        if owner is not None:
+            owner.owned.append(node)
+
+
+def _recover(node: "_Node") -> None:
+    """Tras un error de cómputo en el flush, devuelve `node` y su subgrafo de
+    fuentes a CLEAN. Así el próximo cambio vuelve a marcar y propagar con
+    normalidad (y a recalcular con valores frescos), en vez de dejar el effect
+    colgado para siempre: un nodo `dirty` fuera de la cola ya no se re-encola.
+    Iterativo: recuperarse de un error en una cadena profunda no debe lanzar
+    un RecursionError en pleno manejo de errores."""
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        if n.state == _CLEAN:
+            continue
+        n.state = _CLEAN
+        stack.extend(n.sources)
+
+
+def _flush(sc=None) -> None:
+    # Se llama con _lock tomado (desde set/update, effect() o batch.__exit__).
+    # batch.__exit__ pasa SU scope: si el __exit__ corre en otro contexto (p.ej.
+    # GeneratorExit al GC-earse una tarea abandonada), se drena la cola correcta.
+    if sc is None:
+        sc = _scope()
+    if sc.batch_depth or sc.flushing:
+        return  # dentro de batch o de otro flush: el bucle externo drena la cola
+    sc.flushing = True
+    guard = 0
+    error = None
+    try:
+        pending = sc.pending
+        while pending:
+            node = pending.popleft()
+            node._queued_in = None
+            if node.disposed or node.state == _CLEAN:
+                continue
+            try:
+                node._update_if_necessary()
+            except Exception as exc:   # un effect que falla no debe quedar colgado
+                _recover(node)          # ni abortar el resto de la cola; se recupera
+                if error is None:
+                    error = exc         # se re-lanza el primero tras drenar la cola
+            except BaseException:       # KeyboardInterrupt/CancelledError: recupera
+                _recover(node)          # el nodo y re-lanza de inmediato
+                raise
+            guard += 1
+            if guard > 1_000_000:
+                while pending:          # los descartados quedan CLEAN y fuera de cola:
+                    n = pending.popleft()
+                    n._queued_in = None
+                    _recover(n)         # la próxima escritura los revive
+                raise RuntimeError("nervio: posible ciclo reactivo (demasiados re-cálculos)")
+    finally:
+        sc.flushing = False
+    if error is not None:
+        raise error
+
+
+def signal(value: T, *, equals=None) -> Signal[T]:
+    """Crea estado reactivo. `equals=False` fuerza propagar siempre (objetos mutados in-place)."""
+    return Signal(value, equals=equals)
+
+
+def computed(fn: Callable[[], T], *, equals=None) -> Computed[T]:
+    """Crea un valor derivado perezoso y cacheado a partir de `fn`."""
+    return Computed(fn, equals=equals)
+
+
+def effect(fn: Callable[[], None]) -> Callable[[], None]:
+    """Corre `fn` ahora y cada vez que cambie una dependencia leída. Devuelve `dispose()`.
+
+    Si la primera corrida lanza, el effect NO queda registrado (se dispone y la
+    excepción se propaga): el llamador no recibió el dispose, así que un nodo a
+    medio suscribir sería un zombi imposible de liberar."""
+    node = _Node(value=None, fn=fn, is_effect=True)
+    with _lock:
+        _attach(node)
+        _live_effects.add(node)  # ancla: las fuentes ya no retienen (refs débiles)
+        try:
+            node._update_if_necessary()  # arranca DIRTY -> corre de inmediato
+        except BaseException:
+            try:
+                node._dispose()
+            except BaseException:
+                pass  # el desmontaje se completó igual (garantía de _dispose); para
+                #       el llamador importa el error original de la fn, no el del cleanup
+            raise
+        _flush()  # drena lo encolado durante la corrida inicial (p.ej. otros effects
+        #           marcados por un computed recién calculado); en batch/flush es no-op
+        #           y el drenador activo lo recogerá
+    return node._dispose
+
+
+class batch:
+    """Context manager: agrupa escrituras; los effects corren una sola vez al salir.
+
+    El batch pertenece al ejecutor EXACTO (tarea asyncio o hilo) que lo abre:
+    - Las tareas creadas dentro NO lo heredan (sus escrituras disparan effects
+      de inmediato), y el código corrido en otras tareas del mismo hilo —p.ej.
+      dentro de un `asyncio.run(...)`— tampoco lo ve.
+    - No es una transacción con aislamiento: otros hilos pueden leer los valores
+      intermedios entre las escrituras del batch. Lo único que difiere son los
+      effects que ESTE batch ensució; un effect ya ensuciado por el batch que
+      otro hilo vuelva a tocar correrá al cerrarse el batch, no antes. Mantén
+      los batch cortos y síncronos."""
+
+    def __enter__(self) -> "batch":
+        self._scope = _scope()
+        self._scope.batch_depth += 1
+        return self
+
+    def __exit__(self, *exc) -> bool:
+        sc = self._scope
+        sc.batch_depth -= 1
+        if sc.batch_depth == 0:        # el batch más externo: ahora sí vaciamos
+            with _lock:
+                _flush(sc)             # SU cola, aunque __exit__ corra en otro contexto
+        return False
+
+
+def untrack(fn: Callable[[], T]) -> T:
+    """Ejecuta `fn` sin registrar las señales que lea como dependencias. Devuelve su resultado."""
+    sc = _scope()
+    prev = sc.observer
+    sc.observer = None
+    try:
+        return fn()
+    finally:
+        sc.observer = prev
+
+
+def on_cleanup(fn: Callable[[], None]) -> Callable[[], None]:
+    """Registra `fn` para correr antes del próximo re-run del effect/root actual y al disponerlo."""
+    owner = _scope().owner
+    if owner is not None:
+        with _lock:
+            owner.cleanups.append(fn)
+    return fn
+
+
+class root:
+    """Context manager: agrupa effects/computeds creados dentro para disponerlos juntos.
+
+    Uso: `with root() as dispose: ...`  y luego `dispose()` libera todo el subgrafo.
+    """
+
+    def __enter__(self) -> Callable[[], None]:
+        self._node = _Node(value=None, fn=None)
+        _attach(self._node)
+        sc = _scope()
+        self._scope = sc
+        self._prev_owner = sc.owner
+        sc.owner = self._node
+        return self._node._dispose
+
+    def __exit__(self, *exc) -> bool:
+        self._scope.owner = self._prev_owner
+        return False

nervio-0.2.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: nervio
+Version: 0.2.0
+Summary: Thread-safe, zero-dependency fine-grained reactivity for Python: signal / computed / effect with glitch-free pull propagation, resilient error recovery, and per-task/thread scoping.
+Project-URL: Homepage, https://github.com/ElEscribanoSilente/Nervio
+Project-URL: Repository, https://github.com/ElEscribanoSilente/Nervio
+Project-URL: Issues, https://github.com/ElEscribanoSilente/Nervio/issues
+Project-URL: Changelog, https://github.com/ElEscribanoSilente/Nervio/blob/main/CHANGELOG.md
+Author: ElEscribanoSilente
+License: MIT
+License-File: LICENSE
+Keywords: asyncio,computed,effect,fine-grained,reactive,reactivity,signals,state,thread-safe,zero-dependency
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# nervio
+
+[![CI](https://github.com/ElEscribanoSilente/Nervio/actions/workflows/ci.yml/badge.svg)](https://github.com/ElEscribanoSilente/Nervio/actions/workflows/ci.yml)
+
+Reactividad de grano fino para Python, **sin dependencias y segura entre hilos**. `signal` / `computed` / `effect` con tracking automático de dependencias, propagación *pull glitch-free* (estados `clean/check/dirty`, en la línea de SolidJS y [Reactively](https://github.com/milomg/reactively)), recuperación de errores auditada y ámbitos por tarea `asyncio`/hilo.
+
+- **Tracking automático**: lo que leas dentro de un `computed`/`effect` se vuelve dependencia. Sin `subscribe` manual.
+- **Perezoso y cacheado**: un `computed` solo se recalcula cuando lo lees *y* una dependencia real cambió.
+- **Glitch-free**: en diamantes (A→B, A→C, B+C→D), D se recalcula **una vez** y nunca ve estados intermedios inconsistentes.
+- **Seguro entre hilos**: un mismo grafo puede compartirse entre hilos (lock global reentrante; `update()` atómico), y el estado de scheduling va por ejecutor (tarea `asyncio` o hilo), nunca heredado.
+- **Sin fugas**: los `computed` abandonados se recolectan (refs fuente→observador débiles); los `effect` viven hasta su `dispose()`.
+- **~580 líneas, un solo módulo, tipado (PEP 561).**
+
+```bash
+pip install nervio
+```
+
+## En 30 segundos
+
+```python
+from nervio import signal, computed, effect, batch
+
+precio   = signal(100)
+cantidad = signal(2)
+total    = computed(lambda: precio.value * cantidad.value)   # perezoso
+
+effect(lambda: print(f"Total: {total.value}"))   # imprime "Total: 200" ya mismo
+
+precio.value = 150          # -> "Total: 300"
+with batch():               # varias escrituras, un solo recálculo
+    precio.value = 200
+    cantidad.value = 3      # -> "Total: 600" (una vez)
+```
+
+## API
+
+| | |
+|---|---|
+| `signal(v, *, equals=None)` | Estado reactivo. `.value` (lee y suscribe), `.value = x` / `.set(x)` / `.update(fn)` (escribe), `.peek()` (lee sin suscribir). `equals=False` propaga siempre (útil para objetos mutados in-place). |
+| `computed(fn, *, equals=None)` | Valor derivado perezoso y cacheado. `.value` / `.peek()`. Sin referencias (tuyas ni de nodos aguas abajo) **se recolecta solo**: no hace falta disponerlo. |
+| `effect(fn) -> dispose` | Corre `fn` ahora y ante cada cambio de sus dependencias. Queda **anclado internamente**: sigue corriendo aunque descartes el handle; solo `dispose()` (o el del `root` que lo contiene) lo libera. |
+| `batch()` | Context manager: agrupa escrituras; los effects corren una sola vez al salir. |
+| `untrack(fn)` | Ejecuta `fn` leyendo señales **sin** registrarlas como dependencias. |
+| `on_cleanup(fn)` | Dentro de un effect/root: registra limpieza que corre antes del próximo re-run y al disponer. |
+| `root() -> dispose` | Context manager que agrupa effects/computeds creados dentro para disponerlos juntos. |
+
+### Dependencias dinámicas, limpieza, alcance
+
+```python
+from nervio import signal, effect, on_cleanup, root
+
+modo = signal("a"); a = signal(1); b = signal(2)
+
+# Las dependencias se recalculan en cada corrida: aquí se suscribe a `a` O a `b`, nunca a ambas.
+effect(lambda: print(a.value if modo.value == "a" else b.value))
+
+# Limpieza por corrida (cerrar sockets, cancelar timers, etc.)
+def watcher():
+    conn = abrir(modo.value)
+    on_cleanup(conn.close)        # corre antes del próximo run y al disponer
+effect(watcher)
+
+# Disponer un subgrafo completo de una vez
+with root() as dispose:
+    effect(lambda: ...)
+    effect(lambda: ...)
+# ...más tarde:
+dispose()
+```
+
+## Cómo funciona
+
+Escribir una señal solo **marca** el subgrafo (fase barata: observadores directos → `dirty`, el resto → `check`). Nada se recalcula ahí. El recálculo ocurre al **leer** un `computed` o al vaciar la cola de `effect`s: un nodo en `check` pregunta a sus fuentes y solo se recalcula si alguna resultó `dirty`; si ninguna cambió, vuelve a `clean` sin trabajo. Eso da el mínimo de recálculos y consistencia sin *glitches* dentro de cada ejecutor. Todo el estado vivo —observador, dueño, cola de `effect`s y profundidad de `batch`— vive en un **ámbito por ejecutor** (la tarea `asyncio` actual o, en su defecto, el hilo), que **nunca se hereda**: una tarea creada con `create_task` dentro de un `batch` o de un `effect` estrena ámbito limpio (nada de batches heredados que nunca cierran ni suscripciones fantasma). Las mutaciones del grafo (escrituras, tracking, recomputos, flush, disposición) se serializan con un **lock global reentrante**, así varios hilos pueden compartir un mismo grafo sin corromperlo. Las referencias tienen dirección: dependiente→fuente es **fuerte** (lo que un effect vivo necesita no puede morir) y fuente→observador es **débil** con compactación perezosa (un computed abandonado se recolecta solo); los effects se anclan en un registro interno hasta su `dispose()`.
+
+## Errores
+
+Si un `effect` —o un `computed` del que depende— lanza una excepción, el error se **propaga** a quien disparó el recálculo (la escritura `.value` / `.set`, o la salida del `batch`), pero el grafo **no queda corrupto**: el `effect` se **recupera** y vuelve a ejecutarse en el siguiente cambio de una dependencia, y las dependencias registradas antes del fallo **se conservan** (ninguna escritura futura queda muda). Un `effect` que falla tampoco impide que corran los demás de la misma cola. Esto vale también para `BaseException` (`KeyboardInterrupt`, `CancelledError`): se re-lanzan de inmediato, pero el effect no muere.
+
+- Si la **primera corrida** de un `effect(fn)` lanza, el effect **no queda registrado** (se libera y la excepción se propaga): como el llamador aún no recibió su `dispose`, un nodo a medio suscribir sería imposible de liberar.
+- Un **`on_cleanup` que lanza** tampoco envenena: corren **todos** los cleanups del run (el roto no frena a los demás ni queda re-registrado), el primer error se propaga una sola vez, y el effect se recupera en el siguiente cambio. Si ocurre durante un `dispose()`, el desmontaje **se completa igual** (nada queda a medio disponer) y el error se re-lanza al final.
+- Si **varios** effects fallan en el mismo flush, se re-lanza **el primero**; los demás corren igual pero sus errores no se reportan. En multihilo, el error aflora en el **hilo escritor** que disparó el flush, aunque el effect lo haya creado otro hilo.
+- **Trade-off**: un `computed` que lanza *mientras lo evalúa un effect* se resetea a `clean`; una **lectura directa** de ese `computed` —en la ventana entre el fallo y el siguiente cambio— devuelve su último valor bueno en vez de reintentar. Tras cualquier cambio de una fuente recalcula fresco. (Un `computed` leído directo, sin `effect` de por medio, conserva el reintento en cada lectura.)
+
+## Límites (a propósito)
+
+- **Hilos: seguro, pero serializado.** Un mismo grafo puede mutarse desde varios hilos: un lock global reentrante serializa escrituras, tracking, recomputos y disposición (`update()` es leer-modificar-escribir **atómico**: sin updates perdidos). El costo: el lock se sostiene mientras corre tu código (`fn` de effects/computeds, `equals`, cleanups) — **no bloquees ahí esperando a otro hilo que también use señales** (deadlock clásico), ni hagas I/O lenta (frena el grafo entero). `peek()` de señales es lock-free (puede ver el valor inmediatamente anterior a una escritura en curso).
+- **`batch` difiere effects; no es una transacción con aislamiento.** Otros hilos pueden *leer* los valores intermedios entre las escrituras de un batch ajeno (la garantía glitch-free es por-ejecutor, no inter-hilo). Un effect ya ensuciado por un batch abierto corre cuando ese batch cierre, aunque otro hilo vuelva a escribir sus señales: mantén los batch **cortos y síncronos**. Si el ejecutor dueño muere con el batch abierto (hilo o tarea abandonados), sus effects pendientes los **adopta** la siguiente escritura — no se pierden.
+- **El batch pertenece al ejecutor exacto que lo abre.** Las tareas creadas dentro no lo heredan, y el código corrido en *otras* tareas del mismo hilo —p.ej. dentro de un `asyncio.run(...)`— tampoco lo ve. *(Async: un `await` dentro de un `batch()` difiere los effects de **esa** tarea hasta salir; las demás tareas no se ven afectadas.)* Con frameworks async sin tareas `asyncio` (trio, curio), el ámbito es el **hilo**: todas las tareas de ese hilo comparten batch y cola.
+- **Profundidad sin límite en grafo caliente**: marcado, resolución y recuperación son **iterativos** — cadenas de miles de computeds funcionan para escrituras y actualizaciones. Solo la **primera** evaluación de una cadena *fría* anida llamadas de usuario y queda limitada por el stack de Python (~200 niveles): caliéntala leyendo los computeds conforme la construyes.
+- **Ciclos: detectados y rechazados.** Un computed/effect que participa (directa o indirectamente) en su **propio recálculo** lanza `RuntimeError` con mensaje claro; los ciclos por *ping-pong* de effects que se escriben señales entre sí los corta un tope duro de re-cálculos. No diseñes ciclos: el error existe para encontrarlos, no es una semántica. *(En cadenas frías muy profundas un ciclo puede aflorar como `RecursionError` antes de alcanzar la detección.)*
+- **Memoria**: un `effect` nunca dispuesto vive (y retiene su clausura) para siempre — guarda el handle de `dispose` o créalo dentro de un `root()`. Los `computed` abandonados se recolectan solos. *(En intérpretes sin recolección por conteo de referencias —PyPy— la liberación puede diferirse hasta el siguiente ciclo de GC; las refs muertas se compactan solas en la siguiente escritura.)*
+- Para arrays de numpy u objetos con `==` no booleano, pasa `equals=` propio o `equals=False`.
+
+## Licencia
+
+MIT.

nervio-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+nervio/__init__.py,sha256=B9MZxJSU8P-HfI_VsH28lcfeY08NOvwaes0p1TuNkfg,23741
+nervio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nervio-0.2.0.dist-info/METADATA,sha256=z8-TdBZNEzJPxMH3DDFxyy03NbakA68qjjijSxC8430,11241
+nervio-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+nervio-0.2.0.dist-info/licenses/LICENSE,sha256=ICO9rlTUZFkWtxxYR_WGObXzZNp859eX3Kx5odkr9y8,1075
+nervio-0.2.0.dist-info/RECORD,,

nervio-0.2.0.dist-info/WHEEL

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

nervio-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ElEscribanoSilente
+
+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.