diff --git a/src/psygnal/_signal.py b/src/psygnal/_signal.py index e81b4f3a..6e285b18 100644 --- a/src/psygnal/_signal.py +++ b/src/psygnal/_signal.py @@ -395,6 +395,7 @@ def _create_signal_instance( self.signature, instance=instance, name=name or self._name, + description=self.description, check_nargs_on_connect=self._check_nargs_on_connect, check_types_on_connect=self._check_types_on_connect, reemission=self._reemission, @@ -491,6 +492,19 @@ class Emitter: reemission : Literal["immediate", "queued", "latest-only"] | None See docstring for [`Signal`][psygnal.Signal] for details. By default, `"immediate"`. + description : str + Optional descriptive text for the signal. (not used internally). + + Attributes + ---------- + signature : Signature + Signature supported by this `SignalInstance`. + instance : Any + Object that emits this `SignalInstance`. + name : str + Name of this `SignalInstance`. + description : str + Description of this `SignalInstance`. Raises ------ @@ -509,6 +523,7 @@ def __init__( *, instance: Any = None, name: str | None = None, + description: str = "", check_nargs_on_connect: bool = True, check_types_on_connect: bool = False, reemission: ReemissionVal = DEFAULT_REEMISSION, @@ -521,6 +536,7 @@ def __init__( "instance of `inspect.Signature`" ) + self._description = description self._reemission = ReemissionMode.validate(reemission) self._name = name self._instance: Callable = self._instance_ref(instance) @@ -572,6 +588,11 @@ def name(self) -> str: """Name of this `SignalInstance`.""" return self._name or "" + @property + def description(self) -> str: + """Description of this `SignalInstance`.""" + return self._description + def __repr__(self) -> str: """Return repr.""" name = f" {self._name!r}" if self._name else "" diff --git a/tests/test_psygnal.py b/tests/test_psygnal.py index 7696d594..bae11e33 100644 --- a/tests/test_psygnal.py +++ b/tests/test_psygnal.py @@ -1195,3 +1195,13 @@ def test_emit_loop_error_message_construction(strategy: ReemissionVal) -> None: if strategy == "queued": # check that we show a useful message for confusign queued signals assert "NOTE" in str(e.value) + + +def test_description(): + description = "A signal" + + class T: + sig = Signal(description=description) + + assert T.sig.description == description + assert T().sig.description == description