feat: allow SignalInstances for evented dataclass fields to emit on field mutation (in addition to field change) (#379)

* working example

* update test

* fix test

* hacky fix

* fix tests

* update comments

* add doc

* coverage

* pragma

* skip cov

Author: tlambert03

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ exclude: .asv
 
 repos:
   - repo: https://github.com/crate-ci/typos
-    rev: v1
+    rev: v1.35.3
     hooks:
       - id: typos
         args: [--force-exclude] # omitting --write-changes

src/psygnal/_evented_model.py

@@ -722,7 +722,7 @@ def _setattr_with_dependents_impl(self, name: str, value: Any) -> None:
         elif name in self.__field_dependents__:
             deps_with_callbacks = self.__field_dependents__[name]
         else:
-            return self._super_setattr_(name, value)
+            return self._super_setattr_(name, value)  # pragma: no cover
 
         self._primary_changes.add(name)
         if name not in self._changes_queue:

src/psygnal/_group.py

@@ -319,19 +319,40 @@ def disconnect(self, slot: Callable | None = None, missing_ok: bool = True) -> N
     def _slot_index(self, slot: Callable) -> int:
         """Get index of `slot` in `self._slots`. Return -1 if not connected.
 
-        Override to handle _relay_partial objects directly without wrapping
-        them in WeakFunction, which would create different objects.
+        In interpreted mode, `_relay_partial` callbacks are stored as
+        weak references to the callable object itself, so comparing the
+        dereferenced callback to the provided `_relay_partial` works. In compiled
+        mode (mypyc), `weak_callback` may normalize a `_relay_partial` to a strong
+        reference to its `__call__` method (a MethodWrapperType), to avoid segfaults on
+        garbage collection. In that case the default WeakCallback equality logic is the
+        correct and more robust path.
+
+        Therefore, try the base implementation first (which compares normalized
+        WeakCallback objects). If that fails and we're dealing with a
+        `_relay_partial`, fall back to comparing the dereferenced callable to the
+        provided slot for backward compatibility.
         """
-        if not isinstance(slot, _relay_partial):
-            # For non-_relay_partial objects, use the default behavior
-            return super()._slot_index(slot)
-
-        with self._lock:
-            # For _relay_partial objects, compare directly against callbacks
-            for i, s in enumerate(self._slots):
-                if s.dereference() == slot:
-                    return i
-            return -1  # pragma: no cover
+        # First, try the standard equality path used by SignalInstance
+        idx = super()._slot_index(slot)
+        if idx != -1:
+            return idx
+
+        # Fallback: handle direct comparison for `_relay_partial` instances
+        if isinstance(slot, _relay_partial):
+            with self._lock:
+                for i, s in enumerate(self._slots):
+                    deref = s.dereference()
+                    # Case 1: stored deref is the _relay_partial itself (interpreted)
+                    if deref == slot:
+                        return i
+                    # Case 2: compiled path where we stored __call__ bound method
+                    # (these will never hit on codecov, but they are covered in tests)
+                    owner = getattr(deref, "__self__", None)  # pragma: no cover
+                    if (
+                        isinstance(owner, _relay_partial) and owner == slot
+                    ):  # pragma: no cover
+                        return i
+        return -1  # pragma: no cover
 
 
 # NOTE
@@ -612,6 +633,7 @@ def connect(
         max_args: int | None = None,
         on_ref_error: RefErrorChoice = "warn",
         priority: int = 0,
+        emit_on_evented_child_events: bool = False,
     ) -> Callable[[F], F] | F:
         if slot is None:
             return self._psygnal_relay.connect(
@@ -622,6 +644,7 @@ def connect(
                 max_args=max_args,
                 on_ref_error=on_ref_error,
                 priority=priority,
+                emit_on_evented_child_events=emit_on_evented_child_events,
             )
         else:
             return self._psygnal_relay.connect(
@@ -633,6 +656,7 @@ def connect(
                 max_args=max_args,
                 on_ref_error=on_ref_error,
                 priority=priority,
+                emit_on_evented_child_events=emit_on_evented_child_events,
             )
 
     def connect_direct(

src/psygnal/_group_descriptor.py

@@ -39,7 +39,7 @@
 
 T = TypeVar("T", bound=type)
 S = TypeVar("S")
-
+F = TypeVar("F", bound=Callable)
 
 _EQ_OPERATORS: dict[type, dict[str, EqOperator]] = {}
 _EQ_OPERATOR_NAME = "__eq_operators__"
@@ -133,6 +133,60 @@ def _pick_equality_operator(type_: type | None) -> EqOperator:
 
 
 class _DataclassFieldSignalInstance(SignalInstance):
+    """The type of SignalInstance when emitting dataclass field changes."""
+
+    def _connect_child_event_listener(self, slot: Callable[..., Any]) -> None:
+        # ------------ Emit this signal when the field changes ------------
+        #
+        # _DataclassFieldSignalInstance is a SignalInstance that is used for fields
+        # on evented dataclasses. For example `team.events.leader` is a
+        # _DataclassFieldSignalInstance that emits when the leader field changes.
+        # (e.g. `team.leader = new_leader`)
+        #
+        # However, by default, it does NOT emit when the leader itself changes.
+        # (e.g. `team.leader.age = 60`)
+        # ... because team.leader may not be an evented object, and we can't
+        # assume that we can track changes on it.
+        #
+        # However, if `team.leader` IS itself an evented object, we can connect
+        # to its events, and emit this signal when it changes.  That's what we do here.
+
+        # First, ensure that this SignalInstance is indeed a SignalInstance on
+        # a SignalGroup (presumably a SignalGroupDescriptor)
+        if not isinstance((group := self.instance), SignalGroup):
+            return
+
+        # then get the root object of the group (e.g. "team")
+        root_object = group.instance
+
+        # get the field name (e.g. "leader") representing this SignalInstance
+        field_name = self.name
+
+        # then get the value of the field (e.g. "team.leader")
+        try:
+            member = getattr(root_object, field_name)
+        except Exception:
+            return
+
+        # If that member is itself evented (e.g. "team.leader" is an evented obj)
+        # then grab the SignalGroup on it  (e.g. "team.leader.events")
+        if group := _find_signal_group(member):
+            # next, watch for ANY changes on the member
+            # and call the slot with the new value of the entire field,
+            #
+            # e.g. team.leader.events.connect(lambda: callback(team.leader))
+            def _on_any_change(info: EmissionInfo) -> None:
+                new_val = getattr(root_object, field_name)
+                # TODO somehow get old value? ...
+                # note that old_value is available only in evented_setattr
+                # but the `_handle_child_event_connections` could potentially be a
+                # place to call slot(new_val, old_val)... if we can somehow
+                # get the slot to it.
+                old_val: Any = None
+                slot(new_val, old_val)
+
+            group.connect(_on_any_change, check_nargs=False, on_ref_error="ignore")
+
     def connect_setattr(
         self,
         obj: ref | object,

src/psygnal/_signal.py

@@ -615,6 +615,7 @@ def connect(
         max_args: int | None = None,
         on_ref_error: RefErrorChoice = ...,
         priority: int = ...,
+        emit_on_evented_child_events: bool = ...,
     ) -> Callable[[F], F]: ...
 
     @overload
@@ -629,6 +630,7 @@ def connect(
         max_args: int | None = None,
         on_ref_error: RefErrorChoice = ...,
         priority: int = ...,
+        emit_on_evented_child_events: bool = ...,
     ) -> F: ...
 
     def connect(
@@ -642,6 +644,7 @@ def connect(
         max_args: int | None = None,
         on_ref_error: RefErrorChoice = "warn",
         priority: int = 0,
+        emit_on_evented_child_events: bool = False,
     ) -> Callable[[F], F] | F:
         """Connect a callback (`slot`) to this signal.
 
@@ -710,6 +713,16 @@ def my_function(): ...
             callbacks are called when multiple are connected to the same signal.
             Higher priority callbacks are called first. Negative values are allowed.
             The default is 0.
+        emit_on_evented_child_events : bool
+            If `True`, and if this is a SignalInstance associated with a specific field
+            on an evented dataclass, and if that field itself is an evented dataclass,
+            then the slot will be called both when the field is set directly, *and* when
+            a child member of that field is set.
+            For example, if `Team` is an evented-dataclass with a field `leader: Person`
+            which is itself an evented-dataclass, then
+            `team.events.leader.connect(callback, emit_on_evented_child_events=True)`
+            will invoke callback even when `team.leader.age` is mutated (in addition to
+            when `team.leader` is set directly).
 
         Raises
         ------
@@ -764,10 +777,22 @@ def _wrapper(
                 if thread is not None:
                     cb = QueuedCallback(cb, thread=thread)
                 self._append_slot(cb)
+
+            if emit_on_evented_child_events:
+                self._connect_child_event_listener(slot)
             return slot
 
         return _wrapper if slot is None else _wrapper(slot)
 
+    def _connect_child_event_listener(self, slot: Callable) -> None:
+        """Connect a child event listener to the slot.
+
+        This is called when a slot is connected to this signal.  It allows subclasses
+        to connect additional event listeners to the slot.
+        """
+        # implementing this as a method allows us to override/extend it in subclasses
+        pass  # pragma: no cover
+
     def _append_slot(self, slot: WeakCallback) -> None:
         """Append a slot to the list of slots.
 
@@ -1138,7 +1163,7 @@ def __contains__(self, slot: Callable) -> bool:
         # this change is needed for some reason after mypy v1.14.0
         if callable(slot):
             return self._slot_index(slot) >= 0
-        return False
+        return False  # pragma: no cover
 
     def __len__(self) -> int:
         """Return number of connected slots."""

src/psygnal/_weak_callback.py

@@ -228,6 +228,15 @@ def _on_delete(weak_cb):
         )
 
     if callable(cb):
+        # this is a bit of hack to workaround a segfault observed in testing
+        # on python <=3.11 when compiled by mypyc,
+        # during _weak_callback___WeakFunction_traverse
+        # it specifically happens with MethodWrapperType objects, that I think are made
+        # by mypyc itself.  So we just don't attempt to weakref them here anymore.
+        _call = getattr(cb, "__call__", None)  # noqa
+        if isinstance(_call, MethodWrapperType):
+            return StrongFunction(_call, max_args, args, kwargs, priority=priority)
+
         return WeakFunction(
             cb, max_args, args, kwargs, finalize, on_ref_error, priority=priority
         )

tests/test_evented_decorator.py

@@ -472,7 +472,7 @@ class Parent:
     )
 
 
-def test_team_example():
+def test_team_example() -> None:
     @evented
     @dataclass
     class Person:
@@ -505,3 +505,24 @@ class Team:
         testing.assert_not_emitted(team.events.leader),
     ):
         team.leader.name = "Alice"
+
+
+def test_signal_instance_emits_on_subevents() -> None:
+    @evented
+    @dataclass
+    class Person:
+        name: str = ""
+        age: int = 0
+
+    @evented
+    @dataclass
+    class Team:
+        name: str = ""
+        leader: Person = field(default_factory=Person)
+
+    team = Team(name="A-Team", leader=Person(name="Hannibal", age=59))
+
+    mock = Mock()
+    team.events.leader.connect(mock, emit_on_evented_child_events=True)
+    team.leader.age = 60
+    mock.assert_called_once_with(Person(name="Hannibal", age=60), None)