
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

class 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.

   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.

   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(*args, **kwds)

      Execute a block with the signal connected *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.temporarily_connected_to(receiver):
            # do stuff
            on_ready.send(123)

      New in version 0.9.


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 class blinker.base.NamedSignal(name, doc=None)

   Bases: ``blinker.base.Signal``

   A named generic notification emitter.

   name

      The name of this signal.

class 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.
