API Documentation — Blinker v1.2 documentation

### Navigation

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

# API Documentation

All public API members can (and should) be imported from `blinker`:

    from blinker import ANY, signal

## Basic Signals

`base.` `ANY`
  Token for “any sender”.

`base.` `receiver_connected`

  Sent by a `Signal` after a receiver connects.

  Argument: | the Signal that was connected to
  Parameters: | receiver_arg – the connected receiver sender_arg – the sender to connect to weak_arg – true if the connection to receiver_arg is a weak reference

  Deprecated since version 1.2.

  As of 1.2, individual signals have their own private `receiver_connected` and `receiver_disconnected` signals with a slightly simplified call signature. This global signal is planned to be removed in 1.6.

class `blinker.base.` `Signal`(doc=None)

  A notification emitter.

  Parameter: | doc – optional. If provided, will be assigned to the signal’s __doc__ attribute.

  `ANY`
    An `ANY` convenience synonym, allows `Signal.ANY` without an additional import.
  `receiver_connected`

    Emitted after each `connect()`.

    The signal sender is the signal instance, and the `connect()` arguments are passed through: receiver, sender, and weak.

    New in version 1.2.

  `receiver_disconnected`

    Emitted after `disconnect()`.

    The sender is the signal instance, and the `disconnect()` arguments are passed through: receiver and sender.

    Note, this signal is emitted only when `disconnect()` is called explicitly.

    The disconnect signal can not be emitted by an automatic disconnect (due to a weakly referenced receiver or sender going out of scope), as the receiver and/or sender instances are no longer available for use at the time this signal would be emitted.

    An alternative approach is available by subscribing to `receiver_connected` and setting up a custom weakref cleanup callback on weak receivers and senders.

    New in version 1.2.

  `receivers`

    A mapping of connected receivers.

    The values of this mapping are not meaningful outside of the internal `Signal` implementation, however the boolean value of the mapping is useful as an extremely efficient check to see if any receivers are connected to the signal.

  `connect`(receiver, sender=ANY, weak=True)

    Connect receiver to signal events sent by sender.

    Parameters: | receiver – A callable. Will be invoked by `send()` with sender= as a single positional argument and any **kwargs that were provided to a call to `send()`. sender – Any object or `ANY`, defaults to `ANY`. Restricts notifications delivered to receiver to only those `send()` emissions sent by sender. If `ANY`, the receiver will always be notified. A receiver may be connected to multiple sender values on the same Signal through multiple calls to `connect()`. weak – If true, the Signal will hold a weakref to receiver and automatically disconnect when receiver goes out of scope or is garbage collected. Defaults to True.

  `connect_via`(sender, weak=False)

    Connect the decorated function as a receiver for sender.

    Parameters: | sender – Any object or `ANY`. The decorated function will only receive `send()` emissions sent by sender. If `ANY`, the receiver will always be notified. A function may be decorated multiple times with differing sender values. weak – If true, the Signal will hold a weakref to the decorated function and automatically disconnect when receiver goes out of scope or is garbage collected. Unlike `connect()`, this defaults to False.

    The decorated function will be invoked by `send()` with
      sender= as a single positional argument and any **kwargs that were provided to the call to `send()`.

    New in version 1.1.

  `connected_to`(*args, **kwds)

    Execute a block with the signal temporarily connected to receiver.

    Parameters: | receiver – a receiver callable sender – optional, a sender to filter on

    This is a context manager for use in the `with` statement. It can be useful in unit tests. receiver is connected to the signal for the duration of the `with` block, and will be disconnected automatically when exiting the block:

        with on_ready.connected_to(receiver):
           # do stuff
           on_ready.send(123)

    New in version 1.1.

  `disconnect`(receiver, sender=ANY)

    Disconnect receiver from this signal’s events.

    Parameters: | receiver – a previously `connected` callable sender – a specific sender to disconnect from, or `ANY` to disconnect from all senders. Defaults to `ANY`.

  `has_receivers_for`(sender)

    True if there is probably a receiver for sender.

    Performs an optimistic check only. Does not guarantee that all weakly referenced receivers are still alive. See `receivers_for()` for a stronger search.

  `receivers_for`(sender)
    Iterate all live receivers listening for sender.
  `send`(*sender, **kwargs)

    Emit this signal on behalf of sender, passing on **kwargs.

    Returns a list of 2-tuples, pairing receivers with their return value. The ordering of receiver notification is undefined.

    Parameters: | *sender – Any object or `None`. If omitted, synonymous with `None`. Only accepts one positional argument. **kwargs – Data to be sent to receivers.

  `temporarily_connected_to`(receiver, sender=ANY)

    An alias for `connected_to()`.

    Parameters: | receiver – a receiver callable sender – optional, a sender to filter on

    New in version 0.9.

    Changed in version 1.1: Renamed to `connected_to()`. `temporarily_connected_to` was deprecated in 1.2 and removed in a subsequent version.

## Named Signals

`blinker.base.` `signal`(name, doc=None)

  Return the `NamedSignal` name, creating it if required.

  Repeated calls to this function will return the same signal object. Signals are created in a global `Namespace`.

class `blinker.base.` `NamedSignal`(name, doc=None)

  Bases: `blinker.base.Signal`

  A named generic notification emitter.

  `name`
    The name of this signal.

class `blinker.base.` `Namespace`(*args, **kw)

  Bases: `weakref.WeakValueDictionary`

  A mapping of signal names to signals.

  `signal`(name, doc=None)

    Return the `NamedSignal` name, creating it if required.

    Repeated calls to this function will return the same signal object.

### Navigation

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