Runtime cleanups split out from the type hinting work (#114)

Behavioral/code changes separated from the pure typing changes so
each can be reviewed in isolation:

* watch_effect is a real function instead of a functools.partial, so
  it has an inspectable signature, a docstring and mkdocstrings
  rendering in the API reference (the hand-written docs section is
  replaced by the generated one).
* readonly/shallow_reactive/shallow_readonly are real functions
  instead of partials, for the same reason.
* ref() no longer needs the try/except TypedDict definition dance:
  the generic Ref TypedDict is typing-only (it requires Python 3.11
  at runtime), and all Python versions share one implementation. At
  runtime a Ref was always just a plain (proxied) dict.
* The traceback introspection in _run_callback uses an explicit
  None-check instead of try/except AttributeError, and explicitly
  deletes its local reference to the traceback: a traceback held in
  a local of the frame it references forms a reference cycle that
  would keep the watcher alive until the next gc collection.
* init(mode="rendercanvas") without a loop raises a clear TypeError.
* loop_factory() looks up asyncio.eager_task_factory once with
  getattr instead of hasattr + attribute access.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016fDq6fyKg6QscqyyN6CcwC

Author: claude

docs/reference/api.md

@@ -52,13 +52,7 @@ Combination of `shallow_reactive` and `readonly`.
 
 ::: observ.watcher.watch
 
-### `watch_effect`
-
-```python
-watch_effect(fn: Callable[[], Any]) -> Watcher
-```
-
-Runs `fn` immediately to collect its dependencies and re-runs it (via the scheduler) whenever they change. Equivalent to `watch(fn, deep=True)` without a callback. See [Watchers](../guide/watchers.md#watch_effect).
+::: observ.watcher.watch_effect
 
 ::: observ.watcher.computed
 

observ/init.py

@@ -18,6 +18,8 @@ def init(mode="asyncio", loop=None):
         scheduler.register_asyncio(loop)
 
     elif mode == "rendercanvas":
+        if loop is None:
+            raise TypeError("A loop object is required for the 'rendercanvas' mode")
         scheduler.register_rendercanvas(loop)
 
 
@@ -28,6 +30,7 @@ def loop_factory():
     that observ schedules for async functions and callbacks.
     """
     loop = asyncio.new_event_loop()
-    if hasattr(asyncio, "eager_task_factory"):
-        loop.set_task_factory(asyncio.eager_task_factory)
+    eager_task_factory = getattr(asyncio, "eager_task_factory", None)
+    if eager_task_factory is not None:
+        loop.set_task_factory(eager_task_factory)
     return loop

observ/proxy.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 from copy import copy, deepcopy
-from functools import partial
-from typing import Generic, Literal, TypedDict, TypeVar, cast
+from typing import TYPE_CHECKING, Generic, TypeVar, cast
 
 from .proxy_db import proxy_db
 
+if TYPE_CHECKING:
+    from typing import TypedDict
+
 T = TypeVar("T")
 
 
@@ -104,32 +106,46 @@ def proxy(target: T, readonly=False, shallow=False) -> T:
     return cast(T, target)
 
 
-try:
-    # for Python >= 3.11
+if TYPE_CHECKING:
+    # Only used for typing: at runtime a Ref is a plain (proxied) dict.
+    # Defined here (instead of unconditionally) because a generic
+    # TypedDict requires Python 3.11
     class Ref(TypedDict, Generic[T]):
         value: T
 
-    def ref(target: T) -> Ref[T]:
-        """
-        Returns a reactive dict with a single 'value' key, set to the
-        given target. Useful for making a single (plain) value reactive.
-        """
-        return proxy(Ref(value=target))
 
-except TypeError:
-    # before python 3.11 a TypedDict cannot inherit from a non-TypedDict class
-    def ref(target: T) -> dict[Literal["value"], T]:
-        """
-        Returns a reactive dict with a single 'value' key, set to the
-        given target. Useful for making a single (plain) value reactive.
-        """
-        return proxy({"value": target})
+def ref(target: T) -> Ref[T]:
+    """
+    Returns a reactive dict with a single 'value' key, set to the
+    given target. Useful for making a single (plain) value reactive.
+    """
+    return proxy(cast("Ref[T]", {"value": target}))
 
 
 reactive = proxy
-readonly = partial(proxy, readonly=True)
-shallow_reactive = partial(proxy, shallow=True)
-shallow_readonly = partial(proxy, shallow=True, readonly=True)
+
+
+def readonly(target: T) -> T:
+    """
+    Returns a readonly proxy for the given target: reads are tracked,
+    but any write raises a ReadonlyError.
+    """
+    return proxy(target, readonly=True)
+
+
+def shallow_reactive(target: T) -> T:
+    """
+    Returns a shallow proxy for the given target: only the first level
+    of the target is made reactive, nested values are returned raw.
+    """
+    return proxy(target, shallow=True)
+
+
+def shallow_readonly(target: T) -> T:
+    """
+    Combination of `shallow_reactive` and `readonly`.
+    """
+    return proxy(target, readonly=True, shallow=True)
 
 
 def to_raw(target: Proxy[T] | T) -> T:

observ/watcher.py

@@ -10,7 +10,7 @@
 import inspect
 from collections import deque
 from collections.abc import Awaitable, Container
-from functools import partial, wraps
+from functools import wraps
 from itertools import count
 from typing import Any, Callable, Generic, Optional, TypeVar, Union
 from weakref import ref
@@ -63,7 +63,17 @@ def watch(
     return watcher
 
 
-watch_effect = partial(watch, immediate=False, deep=True, callback=None)
+def watch_effect(
+    fn: Watchable[T],
+    sync: bool = False,
+    deep: bool = True,
+) -> Watcher[T]:
+    """
+    Run the given function immediately to collect its dependencies
+    and re-run it whenever they change. Equivalent to calling `watch`
+    without a callback.
+    """
+    return watch(fn, callback=None, sync=sync, deep=deep, immediate=False)
 
 
 def computed(_fn: Callable[[], T] | None = None, *, deep=True) -> Callable[[], T]:
@@ -442,17 +452,20 @@ def _run_callback(self, *args) -> None:
             # figure out if the TypeError was caused by wrong number of arguments
             # by checking the exception's traceback
             wrong_number_of_arguments = False
-            try:
+            tb = e.__traceback__
+            if tb is not None:
                 _run_callback_is_top_frame = (
-                    e.__traceback__.tb_frame.f_code == self._run_callback.__code__
+                    tb.tb_frame.f_code == self._run_callback.__code__
                 )
-                _no_lower_frames = e.__traceback__.tb_next is None
+                _no_lower_frames = tb.tb_next is None
+                # The traceback references the current frame, so delete
+                # the local reference to it to avoid a reference cycle
+                # that would keep this watcher (and everything it
+                # references) alive until the next gc collection
+                del tb
                 wrong_number_of_arguments = (
                     _run_callback_is_top_frame and _no_lower_frames
                 )
-            except AttributeError:
-                # if there's no traceback we can't figure this out
-                pass
 
             if wrong_number_of_arguments:
                 raise WrongNumberOfArgumentsError(str(e)) from e