Overview#

Psygnal (pronounced "signal") is a pure python implementation of the observer pattern with the API of Qt-style Signals with (optional) signature and type checking, and support for threading.

Quickstart#

The observer pattern is a software design pattern in which an object maintains a list of its dependents ("observers"), and notifies them of any state changes – usually by calling a callback function provided by the observer.

Here is a simple example of using psygnal:

from psygnal import Signal

class MyObject:
    # define one or signals as class attributes
    value_changed = Signal(str)

# create an instance
my_obj = MyObject()

# You (or others) can connect callbacks to your signals
@my_obj.value_changed.connect
def on_change(new_value: str):
    print(f"The value changed to {new_value}!")

# The object may now emit signals when appropriate,
# (for example in a setter method)
my_obj.value_changed.emit('hi')  # prints "The value changed to hi!"

Please see the Basic Usage guide for an overview on how to use psygnal, or the API Reference for details on a specific class or method.

Features#

In addition to the Signal object, psygnal contains:

• a method to convert standard dataclasses (or attrs, pydantic, or msgspec objects) into evented dataclasses that emit signals when fields change.
• a number of "evented" versions of mutable python containers
• an "evented" pydantic model that emits signals whenever a model field changes
• throttling/debouncing decorators
• an experimental "evented object proxy"
• a few other utilities for dealing with events.

Installation#

from pip:

pip install psygnal

from conda:

conda install -c conda-forge psygnal

Performance and Compiled Code#

Performance is a high priority, as signals are often emitted frequently, benchmarks are routinely measured and tested during ci.

Code is compiled using mypyc.

python -c "import psygnal.utils; psygnal.utils.decompile()"

python -c "import psygnal.utils; psygnal.utils.recompile()"