Signals — Blinker v1.2 documentation

### Navigation

- index
- next |
- previous |
- Blinker v1.2 documentation »

# Signals

## Decoupling With Named Signals

Named signals are created with `signal()`:

    >>> from blinker import signal
    >>> initialized = signal('initialized')
    >>> initialized is signal('initialized')
    True

Every call to `signal('name')` returns the same signal object, allowing unconnected parts of code (different modules, plugins, anything) to all use the same signal without requiring any code sharing or special imports.

## Subscribing to Signals

`Signal.connect()` registers a function to be invoked each time the signal is emitted. Connected functions are always passed the object that caused the signal to be emitted.

    >>> def subscriber(sender):
    ...     print("Got a signal sent by %r" % sender)
    ...
    >>> ready = signal('ready')
    >>> ready.connect(subscriber)
    <function subscriber at 0x...>

## Emitting Signals

Code producing events of interest can `Signal.send()` notifications to all connected receivers.

Below, a simple `Processor` class emits a `ready` signal when it’s about to process something, and `complete` when it is done. It passes `self` to the `send()` method, signifying that that particular instance was responsible for emitting the signal.

    >>> class Processor:
    ...    def __init__(self, name):
    ...        self.name = name
    ...
    ...    def go(self):
    ...        ready = signal('ready')
    ...        ready.send(self)
    ...        print("Processing.")
    ...        complete = signal('complete')
    ...        complete.send(self)
    ...
    ...    def __repr__(self):
    ...        return '<Processor %s>' % self.name
    ...
    >>> processor_a = Processor('a')
    >>> processor_a.go()
    Got a signal sent by <Processor a>
    Processing.

Notice the `complete` signal in `go()`? No receivers have connected to `complete` yet, and that’s a-ok. Calling `send()` on a signal with no receivers will result in no notifications being sent, and these no-op sends are optimized to be as inexpensive as possible.

## Subscribing to Specific Senders

The default connection to a signal invokes the receiver function when any sender emits it. The `Signal.connect()` function accepts an optional argument to restrict the subscription to one specific sending object:

    >>> def b_subscriber(sender):
    ...     print("Caught signal from processor_b.")
    ...     assert sender.name == 'b'
    ...
    >>> processor_b = Processor('b')
    >>> ready.connect(b_subscriber, sender=processor_b)
    <function b_subscriber at 0x...>

This function has been subscribed to `ready` but only when sent by `processor_b`:

    >>> processor_a.go()
    Got a signal sent by <Processor a>
    Processing.
    >>> processor_b.go()
    Got a signal sent by <Processor b>
    Caught signal from processor_b.
    Processing.

## Sending and Receiving Data Through Signals

Additional keyword arguments can be passed to `send()`. These will in turn be passed to the connected functions:

    >>> send_data = signal('send-data')
    >>> @send_data.connect
    ... def receive_data(sender, **kw):
    ...     print("Caught signal from %r, data %r" % (sender, kw))
    ...     return 'received!'
    ...
    >>> result = send_data.send('anonymous', abc=123)
    Caught signal from 'anonymous', data {'abc': 123}

The return value of `send()` collects the return values of each connected function as a list of (`receiver function`, `return value`) pairs:

    >>> result
    [(<function receive_data at 0x...>, 'received!')]

## Anonymous Signals

Signals need not be named. The `Signal` constructor creates a unique signal each time it is invoked. For example, an alternative implementation of the Processor from above might provide the processing signals as class attributes:

    >>> from blinker import Signal
    >>> class AltProcessor:
    ...    on_ready = Signal()
    ...    on_complete = Signal()
    ...
    ...    def __init__(self, name):
    ...        self.name = name
    ...
    ...    def go(self):
    ...        self.on_ready.send(self)
    ...        print("Alternate processing.")
    ...        self.on_complete.send(self)
    ...
    ...    def __repr__(self):
    ...        return '<AltProcessor %s>' % self.name
    ...

## `connect` as a Decorator

You may have noticed the return value of `connect()` in the console output in the sections above. This allows `connect` to be used as a decorator on functions:

    >>> apc = AltProcessor('c')
    >>> @apc.on_complete.connect
    ... def completed(sender):
    ...     print "AltProcessor %s completed!" % sender.name
    ...
    >>> apc.go()
    Alternate processing.
    AltProcessor c completed!

While convenient, this form unfortunately does not allow the `sender` or `weak` arguments to be customized for the connected function. For this, `connect_via()` can be used:

    >>> dice_roll = signal('dice_roll')
    >>> @dice_roll.connect_via(1)
    ... @dice_roll.connect_via(3)
    ... @dice_roll.connect_via(5)
    ... def odd_subscriber(sender):
    ...     print("Observed dice roll %r." % sender)
    ...
    >>> result = dice_roll.send(3)
    Observed dice roll 3.

## Optimizing Signal Sending

Signals are optimized to send very quickly, whether receivers are connected or not. If the data to be sent down a signal is very expensive, it can be more efficient to check to see if any receivers are connected first by testing the `receivers` property:

    >>> bool(signal('ready').receivers)
    True
    >>> bool(signal('complete').receivers)
    False
    >>> bool(AltProcessor.on_complete.receivers)
    True

Checking for a receiver listening for a particular sender is also possible:

    >>> signal('ready').has_receivers_for(processor_a)
    True

## Documenting Signals

Both named and anonymous signals can be passed a `doc` argument at construction to set the pydoc help text for the signal. This documentation will be picked up by most documentation generators (such as sphinx) and is nice for documenting any additional data parameters that will be sent down with the signal.

See the documentation of the `receiver_connected` built-in signal for an example.

## More

Disconnecting receivers from signals, introspection of connected receivers, private namespaces for named signals and more are discussed in the API Documentation.

### Navigation

- index
- next |
- previous |
- Blinker v1.2 documentation »