feat: add signal aliases on SignalGroup (#299)

* add signal_aliases

* add test signal_aliases

* add test signal_aliases

* add coverage

* style(pre-commit.ci): auto fixes [...]

* clean

* compat py38

* cover group.signals

* more tests

* try speedup evented setattr

* use type alias

* go back to optional str

* simplify with_aliases

* revert with_aliases

* remove from public

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Talley Lambert <[email protected]>

Author: 3 people

src/psygnal/__init__.py

@@ -51,11 +51,7 @@
 from ._evented_decorator import evented
 from ._exceptions import EmitLoopError
 from ._group import EmissionInfo, SignalGroup
-from ._group_descriptor import (
-    SignalGroupDescriptor,
-    get_evented_namespace,
-    is_evented,
-)
+from ._group_descriptor import SignalGroupDescriptor, get_evented_namespace, is_evented
 from ._queue import emit_queued
 from ._signal import Signal, SignalInstance, _compiled
 from ._throttler import debounced, throttled

src/psygnal/_evented_decorator.py

@@ -1,21 +1,16 @@
 from __future__ import annotations
 
-from typing import (
-    Any,
-    Callable,
-    Literal,
-    TypeVar,
-    overload,
-)
+from typing import TYPE_CHECKING, Callable, Literal, Mapping, TypeVar, overload
 
 from psygnal._group_descriptor import SignalGroupDescriptor
 
+if TYPE_CHECKING:
+    from psygnal._group_descriptor import EqOperator, FieldAliasFunc
+
 __all__ = ["evented"]
 
 T = TypeVar("T", bound=type)
 
-EqOperator = Callable[[Any, Any], bool]
-
 
 @overload
 def evented(
@@ -25,6 +20,7 @@ def evented(
     equality_operators: dict[str, EqOperator] | None = None,
     warn_on_no_fields: bool = ...,
     cache_on_instance: bool = ...,
+    signal_aliases: Mapping[str, str | None] | FieldAliasFunc | None = ...,
 ) -> T: ...
 
 
@@ -36,6 +32,7 @@ def evented(
     equality_operators: dict[str, EqOperator] | None = None,
     warn_on_no_fields: bool = ...,
     cache_on_instance: bool = ...,
+    signal_aliases: Mapping[str, str | None] | FieldAliasFunc | None = ...,
 ) -> Callable[[T], T]: ...
 
 
@@ -46,6 +43,7 @@ def evented(
     equality_operators: dict[str, EqOperator] | None = None,
     warn_on_no_fields: bool = True,
     cache_on_instance: bool = True,
+    signal_aliases: Mapping[str, str | None] | FieldAliasFunc | None = None,
 ) -> Callable[[T], T] | T:
     """A decorator to add events to a dataclass.
 
@@ -85,6 +83,14 @@ def evented(
         access, but means that the owner instance will no longer be pickleable.  If
         `False`, the SignalGroup instance will *still* be cached, but not on the
         instance itself.
+    signal_aliases: Mapping[str, str | None] | Callable[[str], str | None] | None
+        If defined, a mapping between field name and signal name. Field names that are
+        not `signal_aliases` keys are not aliased (the signal name is the field name).
+        If the dict value is None, do not create a signal associated with this field.
+        If a callable, the signal name is the output of the function applied to the
+        field name. If the output is None, no signal is created for this field.
+        If None, defaults to an empty dict, no aliases.
+        Default to None
 
     Returns
     -------
@@ -122,6 +128,7 @@ def _decorate(cls: T) -> T:
             equality_operators=equality_operators,
             warn_on_no_fields=warn_on_no_fields,
             cache_on_instance=cache_on_instance,
+            signal_aliases=signal_aliases,
         )
         # as a decorator, this will have already been called
         descriptor.__set_name__(cls, events_namespace)

src/psygnal/_group.py

@@ -260,6 +260,7 @@ class MySignals(SignalGroup):
     _psygnal_signals: ClassVar[Mapping[str, Signal]]
     _psygnal_uniform: ClassVar[bool] = False
     _psygnal_name_conflicts: ClassVar[set[str]]
+    _psygnal_aliases: ClassVar[dict[str, str | None]]
 
     _psygnal_instances: dict[str, SignalInstance]
 
@@ -280,7 +281,11 @@ def __init__(self, instance: Any = None) -> None:
         }
         self._psygnal_relay = SignalRelay(self._psygnal_instances, instance)
 
-    def __init_subclass__(cls, strict: bool = False) -> None:
+    def __init_subclass__(
+        cls,
+        strict: bool = False,
+        signal_aliases: Mapping[str, str | None] = {},
+    ) -> None:
         """Collects all Signal instances on the class under `cls._psygnal_signals`."""
         # Collect Signals and remove from class attributes
         # Use dir(cls) instead of cls.__dict__ to get attributes from super()
@@ -328,6 +333,8 @@ def __init_subclass__(cls, strict: bool = False) -> None:
                 stacklevel=2,
             )
 
+        aliases = getattr(cls, "_psygnal_aliases", {})
+        cls._psygnal_aliases = {**aliases, **signal_aliases}
         cls._psygnal_uniform = _is_uniform(cls._psygnal_signals.values())
         if strict and not cls._psygnal_uniform:
             raise TypeError(