<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Blinker Documentation — Blinker</title>
<link rel="stylesheet" href="_static/flasky.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Blinker" href="#" />
</head>
<body>
<div class=indexwrapper>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="blinker-documentation">
<h1>Blinker Documentation<a class="headerlink" href="#blinker-documentation" title="Permalink to this headline">¶</a></h1>
<p>Blinker provides fast & simple object-to-object and broadcast
signaling for Python objects.</p>
<p>The core of Blinker is quite small but provides powerful features:</p>
<blockquote>
<div><ul class="simple">
<li>a global registry of named signals</li>
<li>anonymous signals</li>
<li>custom name registries</li>
<li>permanently or temporarily connected receivers</li>
<li>automatically disconnected receivers via weak referencing</li>
<li>sending arbitrary data payloads</li>
<li>collecting return values from signal receivers</li>
<li>thread safety</li>
</ul>
</div></blockquote>
<p>Blinker was written by Jason Kirtand and is provided under the MIT
License. The library supports Python 2.4 or later; Python 3.0 or later;
or Jython 2.5 or later; or PyPy 1.6 or later.</p>
<div class="section" id="decoupling-with-named-signals">
<h2>Decoupling With Named Signals<a class="headerlink" href="#decoupling-with-named-signals" title="Permalink to this headline">¶</a></h2>
<p>Named signals are created with <tt class="xref py py-func docutils literal"><span class="pre">signal()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">blinker</span> <span class="kn">import</span> <span class="n">signal</span>
<span class="gp">>>> </span><span class="n">initialized</span> <span class="o">=</span> <span class="n">signal</span><span class="p">(</span><span class="s">'initialized'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">initialized</span> <span class="ow">is</span> <span class="n">signal</span><span class="p">(</span><span class="s">'initialized'</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Every call to <tt class="docutils literal"><span class="pre">signal('name')</span></tt> 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.</p>
</div>
<div class="section" id="subscribing-to-signals">
<h2>Subscribing to Signals<a class="headerlink" href="#subscribing-to-signals" title="Permalink to this headline">¶</a></h2>
<p><tt class="xref py py-meth docutils literal"><span class="pre">Signal.connect()</span></tt> 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.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">subscriber</span><span class="p">(</span><span class="n">sender</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"Got a signal sent by </span><span class="si">%r</span><span class="s">"</span> <span class="o">%</span> <span class="n">sender</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="n">ready</span> <span class="o">=</span> <span class="n">signal</span><span class="p">(</span><span class="s">'ready'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">ready</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">subscriber</span><span class="p">)</span>
<span class="go"><function subscriber at 0x...></span>
</pre></div>
</div>
</div>
<div class="section" id="emitting-signals">
<h2>Emitting Signals<a class="headerlink" href="#emitting-signals" title="Permalink to this headline">¶</a></h2>
<p>Code producing events of interest can <tt class="xref py py-meth docutils literal"><span class="pre">Signal.send()</span></tt>
notifications to all connected receivers.</p>
<p>Below, a simple <tt class="docutils literal"><span class="pre">Processor</span></tt> class emits a <tt class="docutils literal"><span class="pre">ready</span></tt> signal when it’s
about to process something, and <tt class="docutils literal"><span class="pre">complete</span></tt> when it is done. It
passes <tt class="docutils literal"><span class="pre">self</span></tt> to the <tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt> method, signifying that
that particular instance was responsible for emitting the signal.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Processor</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">go</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">ready</span> <span class="o">=</span> <span class="n">signal</span><span class="p">(</span><span class="s">'ready'</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">ready</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"Processing."</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">complete</span> <span class="o">=</span> <span class="n">signal</span><span class="p">(</span><span class="s">'complete'</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">complete</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s">'<Processor </span><span class="si">%s</span><span class="s">>'</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="n">processor_a</span> <span class="o">=</span> <span class="n">Processor</span><span class="p">(</span><span class="s">'a'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">processor_a</span><span class="o">.</span><span class="n">go</span><span class="p">()</span>
<span class="go">Got a signal sent by <Processor a></span>
<span class="go">Processing.</span>
</pre></div>
</div>
<p>Notice the <tt class="docutils literal"><span class="pre">complete</span></tt> signal in <tt class="docutils literal"><span class="pre">go()</span></tt>? No receivers have
connected to <tt class="docutils literal"><span class="pre">complete</span></tt> yet, and that’s a-ok. Calling
<tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt> 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.</p>
</div>
<div class="section" id="subscribing-to-specific-senders">
<h2>Subscribing to Specific Senders<a class="headerlink" href="#subscribing-to-specific-senders" title="Permalink to this headline">¶</a></h2>
<p>The default connection to a signal invokes the receiver function when
any sender emits it. The <tt class="xref py py-meth docutils literal"><span class="pre">Signal.connect()</span></tt> function accepts an
optional argument to restrict the subscription to one specific sending
object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">b_subscriber</span><span class="p">(</span><span class="n">sender</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"Caught signal from processor_b."</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">assert</span> <span class="n">sender</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'b'</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="n">processor_b</span> <span class="o">=</span> <span class="n">Processor</span><span class="p">(</span><span class="s">'b'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">ready</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">b_subscriber</span><span class="p">,</span> <span class="n">sender</span><span class="o">=</span><span class="n">processor_b</span><span class="p">)</span>
<span class="go"><function b_subscriber at 0x...></span>
</pre></div>
</div>
<p>This function has been subscribed to <tt class="docutils literal"><span class="pre">ready</span></tt> but only when sent by
<tt class="docutils literal"><span class="pre">processor_b</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">processor_a</span><span class="o">.</span><span class="n">go</span><span class="p">()</span>
<span class="go">Got a signal sent by <Processor a></span>
<span class="go">Processing.</span>
<span class="gp">>>> </span><span class="n">processor_b</span><span class="o">.</span><span class="n">go</span><span class="p">()</span>
<span class="go">Got a signal sent by <Processor b></span>
<span class="go">Caught signal from processor_b.</span>
<span class="go">Processing.</span>
</pre></div>
</div>
</div>
<div class="section" id="sending-and-receiving-data-through-signals">
<h2>Sending and Receiving Data Through Signals<a class="headerlink" href="#sending-and-receiving-data-through-signals" title="Permalink to this headline">¶</a></h2>
<p>Additional keyword arguments can be passed to <tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt>.
These will in turn be passed to the connected functions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">send_data</span> <span class="o">=</span> <span class="n">signal</span><span class="p">(</span><span class="s">'send-data'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nd">@send_data.connect</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">receive_data</span><span class="p">(</span><span class="n">sender</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"Caught signal from </span><span class="si">%r</span><span class="s">, data </span><span class="si">%r</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">sender</span><span class="p">,</span> <span class="n">kw</span><span class="p">))</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s">'received!'</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">send_data</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s">'anonymous'</span><span class="p">,</span> <span class="n">abc</span><span class="o">=</span><span class="mi">123</span><span class="p">)</span>
<span class="go">Caught signal from 'anonymous', data {'abc': 123}</span>
</pre></div>
</div>
<p>The return value of <tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt> collects the return values of
each connected function as a list of (<tt class="docutils literal"><span class="pre">receiver</span> <span class="pre">function</span></tt>, <tt class="docutils literal"><span class="pre">return</span>
<span class="pre">value</span></tt>) pairs:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">result</span>
<span class="go">[(<function receive_data at 0x...>, 'received!')]</span>
</pre></div>
</div>
</div>
<div class="section" id="anonymous-signals">
<h2>Anonymous Signals<a class="headerlink" href="#anonymous-signals" title="Permalink to this headline">¶</a></h2>
<p>Signals need not be named. The <tt class="xref py py-class docutils literal"><span class="pre">Signal</span></tt> 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:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">blinker</span> <span class="kn">import</span> <span class="n">Signal</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">AltProcessor</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">on_ready</span> <span class="o">=</span> <span class="n">Signal</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">on_complete</span> <span class="o">=</span> <span class="n">Signal</span><span class="p">()</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">go</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">on_ready</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"Alternate processing."</span><span class="p">)</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">on_complete</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s">'<AltProcessor </span><span class="si">%s</span><span class="s">>'</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span>
<span class="gp">...</span>
</pre></div>
</div>
</div>
<div class="section" id="connect-as-a-decorator">
<h2><tt class="docutils literal"><span class="pre">connect</span></tt> as a Decorator<a class="headerlink" href="#connect-as-a-decorator" title="Permalink to this headline">¶</a></h2>
<p>You may have noticed the return value of <tt class="xref py py-meth docutils literal"><span class="pre">connect()</span></tt> in
the console output in the sections above. This allows <tt class="docutils literal"><span class="pre">connect</span></tt> to
be used as a decorator on functions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">apc</span> <span class="o">=</span> <span class="n">AltProcessor</span><span class="p">(</span><span class="s">'c'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nd">@apc.on_complete.connect</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">completed</span><span class="p">(</span><span class="n">sender</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span> <span class="s">"AltProcessor </span><span class="si">%s</span><span class="s"> completed!"</span> <span class="o">%</span> <span class="n">sender</span><span class="o">.</span><span class="n">name</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="n">apc</span><span class="o">.</span><span class="n">go</span><span class="p">()</span>
<span class="go">Alternate processing.</span>
<span class="go">AltProcessor c completed!</span>
</pre></div>
</div>
<p>While convenient, this form unfortunately does not allow the
<tt class="docutils literal"><span class="pre">sender</span></tt> or <tt class="docutils literal"><span class="pre">weak</span></tt> arguments to be customized for the connected
function. For this, <tt class="xref py py-meth docutils literal"><span class="pre">connect_via()</span></tt> can be used:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">dice_roll</span> <span class="o">=</span> <span class="n">signal</span><span class="p">(</span><span class="s">'dice_roll'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nd">@dice_roll.connect_via</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">... </span><span class="nd">@dice_roll.connect_via</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
<span class="gp">... </span><span class="nd">@dice_roll.connect_via</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">odd_subscriber</span><span class="p">(</span><span class="n">sender</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"Observed dice roll </span><span class="si">%r</span><span class="s">."</span> <span class="o">%</span> <span class="n">sender</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">dice_roll</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
<span class="go">Observed dice roll 3.</span>
</pre></div>
</div>
</div>
<div class="section" id="optimizing-signal-sending">
<h2>Optimizing Signal Sending<a class="headerlink" href="#optimizing-signal-sending" title="Permalink to this headline">¶</a></h2>
<p>Signals are optimized to send very quickly, whether receivers are
connected or not. If the keyword data to be sent with a signal is
expensive to compute, it can be more efficient to check to see if any
receivers are connected first by testing the <tt class="xref py py-attr docutils literal"><span class="pre">receivers</span></tt>
property:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">bool</span><span class="p">(</span><span class="n">signal</span><span class="p">(</span><span class="s">'ready'</span><span class="p">)</span><span class="o">.</span><span class="n">receivers</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="nb">bool</span><span class="p">(</span><span class="n">signal</span><span class="p">(</span><span class="s">'complete'</span><span class="p">)</span><span class="o">.</span><span class="n">receivers</span><span class="p">)</span>
<span class="go">False</span>
<span class="gp">>>> </span><span class="nb">bool</span><span class="p">(</span><span class="n">AltProcessor</span><span class="o">.</span><span class="n">on_complete</span><span class="o">.</span><span class="n">receivers</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Checking for a receiver listening for a particular sender is also
possible:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">signal</span><span class="p">(</span><span class="s">'ready'</span><span class="p">)</span><span class="o">.</span><span class="n">has_receivers_for</span><span class="p">(</span><span class="n">processor_a</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
</div>
<div class="section" id="documenting-signals">
<h2>Documenting Signals<a class="headerlink" href="#documenting-signals" title="Permalink to this headline">¶</a></h2>
<p>Both named and anonymous signals can be passed a <tt class="docutils literal"><span class="pre">doc</span></tt> 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.</p>
<p>See the documentation of the <tt class="xref py py-obj docutils literal"><span class="pre">receiver_connected</span></tt> built-in signal
for an example.</p>
</div>
<div class="section" id="api-documentation">
<h2>API Documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2>
<p>All public API members can (and should) be imported from <tt class="docutils literal"><span class="pre">blinker</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">blinker</span> <span class="kn">import</span> <span class="n">ANY</span><span class="p">,</span> <span class="n">signal</span>
</pre></div>
</div>
<div class="section" id="basic-signals">
<h3>Basic Signals<a class="headerlink" href="#basic-signals" title="Permalink to this headline">¶</a></h3>
<dl class="data">
<dt id="blinker.base.ANY">
<tt class="descclassname">blinker.base.</tt><tt class="descname">ANY</tt><em class="property"> = ANY</em><a class="headerlink" href="#blinker.base.ANY" title="Permalink to this definition">¶</a></dt>
<dd><p>Token for “any sender”.</p>
</dd></dl>
<dl class="data">
<dt id="blinker.base.receiver_connected">
<tt class="descclassname">blinker.base.</tt><tt class="descname">receiver_connected</tt><em class="property"> = <blinker.base.Signal object at 0x1041516d0></em><a class="headerlink" href="#blinker.base.receiver_connected" title="Permalink to this definition">¶</a></dt>
<dd><p>Sent by a <a class="reference internal" href="#blinker.base.Signal" title="blinker.base.Signal"><tt class="xref py py-class docutils literal"><span class="pre">Signal</span></tt></a> after a receiver connects.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Argument :</th><td class="field-body"><p class="first">the Signal that was connected to</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>receiver_arg</strong> – the connected receiver</li>
<li><strong>sender_arg</strong> – the sender to connect to</li>
<li><strong>weak_arg</strong> – true if the connection to receiver_arg is a weak reference</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="deprecated">
<p><span>Deprecated since version 1.2.</span></p>
</div>
<p>As of 1.2, individual signals have their own private
<a class="reference internal" href="#blinker.base.Signal.receiver_connected" title="blinker.base.Signal.receiver_connected"><tt class="xref py py-attr docutils literal"><span class="pre">receiver_connected</span></tt></a> and
<a class="reference internal" href="#blinker.base.Signal.receiver_disconnected" title="blinker.base.Signal.receiver_disconnected"><tt class="xref py py-attr docutils literal"><span class="pre">receiver_disconnected</span></tt></a> signals with a slightly simplified
call signature. This global signal is planned to be removed in 1.6.</p>
</dd></dl>
<dl class="class">
<dt id="blinker.base.Signal">
<em class="property">class </em><tt class="descclassname">blinker.base.</tt><tt class="descname">Signal</tt><big>(</big><em>doc=None</em><big>)</big><a class="headerlink" href="#blinker.base.Signal" title="Permalink to this definition">¶</a></dt>
<dd><p>A notification emitter.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>doc</strong> – optional. If provided, will be assigned to the signal’s
__doc__ attribute.</td>
</tr>
</tbody>
</table>
<dl class="attribute">
<dt id="blinker.base.Signal.ANY">
<tt class="descname">ANY</tt><em class="property"> = ANY</em><a class="headerlink" href="#blinker.base.Signal.ANY" title="Permalink to this definition">¶</a></dt>
<dd><p>An <a class="reference internal" href="#blinker.base.ANY" title="blinker.base.ANY"><tt class="xref py py-obj docutils literal"><span class="pre">ANY</span></tt></a> convenience synonym, allows <tt class="docutils literal"><span class="pre">Signal.ANY</span></tt>
without an additional import.</p>
</dd></dl>
<dl class="attribute">
<dt id="blinker.base.Signal.receiver_connected">
<tt class="descname">receiver_connected</tt><a class="headerlink" href="#blinker.base.Signal.receiver_connected" title="Permalink to this definition">¶</a></dt>
<dd><p>Emitted after each <a class="reference internal" href="#blinker.base.Signal.connect" title="blinker.base.Signal.connect"><tt class="xref py py-meth docutils literal"><span class="pre">connect()</span></tt></a>.</p>
<p>The signal sender is the signal instance, and the <a class="reference internal" href="#blinker.base.Signal.connect" title="blinker.base.Signal.connect"><tt class="xref py py-meth docutils literal"><span class="pre">connect()</span></tt></a>
arguments are passed through: <em>receiver</em>, <em>sender</em>, and <em>weak</em>.</p>
<div class="versionadded">
<p><span>New in version 1.2.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="blinker.base.Signal.receiver_disconnected">
<tt class="descname">receiver_disconnected</tt><a class="headerlink" href="#blinker.base.Signal.receiver_disconnected" title="Permalink to this definition">¶</a></dt>
<dd><p>Emitted after <a class="reference internal" href="#blinker.base.Signal.disconnect" title="blinker.base.Signal.disconnect"><tt class="xref py py-meth docutils literal"><span class="pre">disconnect()</span></tt></a>.</p>
<p>The sender is the signal instance, and the <a class="reference internal" href="#blinker.base.Signal.disconnect" title="blinker.base.Signal.disconnect"><tt class="xref py py-meth docutils literal"><span class="pre">disconnect()</span></tt></a> arguments
are passed through: <em>receiver</em> and <em>sender</em>.</p>
<p>Note, this signal is emitted <strong>only</strong> when <a class="reference internal" href="#blinker.base.Signal.disconnect" title="blinker.base.Signal.disconnect"><tt class="xref py py-meth docutils literal"><span class="pre">disconnect()</span></tt></a> is
called explicitly.</p>
<p>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.</p>
<p>An alternative approach is available by subscribing to
<a class="reference internal" href="#blinker.base.receiver_connected" title="blinker.base.receiver_connected"><tt class="xref py py-attr docutils literal"><span class="pre">receiver_connected</span></tt></a> and setting up a custom weakref cleanup
callback on weak receivers and senders.</p>
<div class="versionadded">
<p><span>New in version 1.2.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="blinker.base.Signal.receivers">
<tt class="descname">receivers</tt><em class="property"> = None</em><a class="headerlink" href="#blinker.base.Signal.receivers" title="Permalink to this definition">¶</a></dt>
<dd><p>A mapping of connected receivers.</p>
<p>The values of this mapping are not meaningful outside of the
internal <a class="reference internal" href="#blinker.base.Signal" title="blinker.base.Signal"><tt class="xref py py-class docutils literal"><span class="pre">Signal</span></tt></a> 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.</p>
</dd></dl>
<dl class="method">
<dt id="blinker.base.Signal.connect">
<tt class="descname">connect</tt><big>(</big><em>receiver</em>, <em>sender=ANY</em>, <em>weak=True</em><big>)</big><a class="headerlink" href="#blinker.base.Signal.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Connect <em>receiver</em> to signal events sent by <em>sender</em>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>receiver</strong> – A callable. Will be invoked by <a class="reference internal" href="#blinker.base.Signal.send" title="blinker.base.Signal.send"><tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt></a> with
<cite>sender=</cite> as a single positional argument and any **kwargs that
were provided to a call to <a class="reference internal" href="#blinker.base.Signal.send" title="blinker.base.Signal.send"><tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt></a>.</li>
<li><strong>sender</strong> – Any object or <a class="reference internal" href="#blinker.base.ANY" title="blinker.base.ANY"><tt class="xref py py-obj docutils literal"><span class="pre">ANY</span></tt></a>, defaults to <tt class="docutils literal"><span class="pre">ANY</span></tt>.
Restricts notifications delivered to <em>receiver</em> to only those
<a class="reference internal" href="#blinker.base.Signal.send" title="blinker.base.Signal.send"><tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt></a> emissions sent by <em>sender</em>. If <tt class="docutils literal"><span class="pre">ANY</span></tt>, the receiver
will always be notified. A <em>receiver</em> may be connected to
multiple <em>sender</em> values on the same Signal through multiple calls
to <a class="reference internal" href="#blinker.base.Signal.connect" title="blinker.base.Signal.connect"><tt class="xref py py-meth docutils literal"><span class="pre">connect()</span></tt></a>.</li>
<li><strong>weak</strong> – If true, the Signal will hold a weakref to <em>receiver</em>
and automatically disconnect when <em>receiver</em> goes out of scope or
is garbage collected. Defaults to True.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="blinker.base.Signal.connect_via">
<tt class="descname">connect_via</tt><big>(</big><em>sender</em>, <em>weak=False</em><big>)</big><a class="headerlink" href="#blinker.base.Signal.connect_via" title="Permalink to this definition">¶</a></dt>
<dd><p>Connect the decorated function as a receiver for <em>sender</em>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>sender</strong> – Any object or <a class="reference internal" href="#blinker.base.ANY" title="blinker.base.ANY"><tt class="xref py py-obj docutils literal"><span class="pre">ANY</span></tt></a>. The decorated function
will only receive <a class="reference internal" href="#blinker.base.Signal.send" title="blinker.base.Signal.send"><tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt></a> emissions sent by <em>sender</em>. If
<tt class="docutils literal"><span class="pre">ANY</span></tt>, the receiver will always be notified. A function may be
decorated multiple times with differing <em>sender</em> values.</li>
<li><strong>weak</strong> – If true, the Signal will hold a weakref to the
decorated function and automatically disconnect when <em>receiver</em>
goes out of scope or is garbage collected. Unlike
<a class="reference internal" href="#blinker.base.Signal.connect" title="blinker.base.Signal.connect"><tt class="xref py py-meth docutils literal"><span class="pre">connect()</span></tt></a>, this defaults to False.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<dl class="docutils">
<dt>The decorated function will be invoked by <a class="reference internal" href="#blinker.base.Signal.send" title="blinker.base.Signal.send"><tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt></a> with</dt>
<dd><cite>sender=</cite> as a single positional argument and any **kwargs that
were provided to the call to <a class="reference internal" href="#blinker.base.Signal.send" title="blinker.base.Signal.send"><tt class="xref py py-meth docutils literal"><span class="pre">send()</span></tt></a>.</dd>
</dl>
<div class="versionadded">
<p><span>New in version 1.1.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="blinker.base.Signal.connected_to">
<tt class="descname">connected_to</tt><big>(</big><em>*args</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#blinker.base.Signal.connected_to" title="Permalink to this definition">¶</a></dt>
<dd><p>Execute a block with the signal temporarily connected to <em>receiver</em>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>receiver</strong> – a receiver callable</li>
<li><strong>sender</strong> – optional, a sender to filter on</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>This is a context manager for use in the <tt class="docutils literal"><span class="pre">with</span></tt> statement. It can
be useful in unit tests. <em>receiver</em> is connected to the signal for
the duration of the <tt class="docutils literal"><span class="pre">with</span></tt> block, and will be disconnected
automatically when exiting the block:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">on_ready</span><span class="o">.</span><span class="n">connected_to</span><span class="p">(</span><span class="n">receiver</span><span class="p">):</span>
<span class="c"># do stuff</span>
<span class="n">on_ready</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="mi">123</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span>New in version 1.1.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="blinker.base.Signal.disconnect">
<tt class="descname">disconnect</tt><big>(</big><em>receiver</em>, <em>sender=ANY</em><big>)</big><a class="headerlink" href="#blinker.base.Signal.disconnect" title="Permalink to this definition">¶</a></dt>
<dd><p>Disconnect <em>receiver</em> from this signal’s events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>receiver</strong> – a previously <a class="reference internal" href="#blinker.base.Signal.connect" title="blinker.base.Signal.connect"><tt class="xref py py-meth docutils literal"><span class="pre">connected</span></tt></a> callable</li>
<li><strong>sender</strong> – a specific sender to disconnect from, or <a class="reference internal" href="#blinker.base.ANY" title="blinker.base.ANY"><tt class="xref py py-obj docutils literal"><span class="pre">ANY</span></tt></a>
to disconnect from all senders. Defaults to <tt class="docutils literal"><span class="pre">ANY</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="blinker.base.Signal.has_receivers_for">
<tt class="descname">has_receivers_for</tt><big>(</big><em>sender</em><big>)</big><a class="headerlink" href="#blinker.base.Signal.has_receivers_for" title="Permalink to this definition">¶</a></dt>
<dd><p>True if there is probably a receiver for <em>sender</em>.</p>
<p>Performs an optimistic check only. Does not guarantee that all
weakly referenced receivers are still alive. See
<a class="reference internal" href="#blinker.base.Signal.receivers_for" title="blinker.base.Signal.receivers_for"><tt class="xref py py-meth docutils literal"><span class="pre">receivers_for()</span></tt></a> for a stronger search.</p>
</dd></dl>
<dl class="method">
<dt id="blinker.base.Signal.receivers_for">
<tt class="descname">receivers_for</tt><big>(</big><em>sender</em><big>)</big><a class="headerlink" href="#blinker.base.Signal.receivers_for" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate all live receivers listening for <em>sender</em>.</p>
</dd></dl>
<dl class="method">
<dt id="blinker.base.Signal.send">
<tt class="descname">send</tt><big>(</big><em>*sender</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#blinker.base.Signal.send" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit this signal on behalf of <em>sender</em>, passing on **kwargs.</p>
<p>Returns a list of 2-tuples, pairing receivers with their return
value. The ordering of receiver notification is undefined.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>*sender</strong> – Any object or <tt class="docutils literal"><span class="pre">None</span></tt>. If omitted, synonymous
with <tt class="docutils literal"><span class="pre">None</span></tt>. Only accepts one positional argument.</li>
<li><strong>**kwargs</strong> – Data to be sent to receivers.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="blinker.base.Signal.temporarily_connected_to">
<tt class="descname">temporarily_connected_to</tt><big>(</big><em>receiver</em>, <em>sender=ANY</em><big>)</big><a class="headerlink" href="#blinker.base.Signal.temporarily_connected_to" title="Permalink to this definition">¶</a></dt>
<dd><p>An alias for <a class="reference internal" href="#blinker.base.Signal.connected_to" title="blinker.base.Signal.connected_to"><tt class="xref py py-meth docutils literal"><span class="pre">connected_to()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>receiver</strong> – a receiver callable</li>
<li><strong>sender</strong> – optional, a sender to filter on</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.</span></p>
</div>
<div class="versionchanged">
<p><span>Changed in version 1.1: </span>Renamed to <a class="reference internal" href="#blinker.base.Signal.connected_to" title="blinker.base.Signal.connected_to"><tt class="xref py py-meth docutils literal"><span class="pre">connected_to()</span></tt></a>. <tt class="docutils literal"><span class="pre">temporarily_connected_to</span></tt> was
deprecated in 1.2 and will be removed in a subsequent version.</p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="named-signals">
<h3>Named Signals<a class="headerlink" href="#named-signals" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="blinker.base.signal">
<tt class="descclassname">blinker.base.</tt><tt class="descname">signal</tt><big>(</big><em>name</em>, <em>doc=None</em><big>)</big><a class="headerlink" href="#blinker.base.signal" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <a class="reference internal" href="#blinker.base.NamedSignal" title="blinker.base.NamedSignal"><tt class="xref py py-class docutils literal"><span class="pre">NamedSignal</span></tt></a> <em>name</em>, creating it if required.</p>
<p>Repeated calls to this function will return the same signal object.
Signals are created in a global <a class="reference internal" href="#blinker.base.Namespace" title="blinker.base.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>.</p>
</dd></dl>
<dl class="class">
<dt id="blinker.base.NamedSignal">
<em class="property">class </em><tt class="descclassname">blinker.base.</tt><tt class="descname">NamedSignal</tt><big>(</big><em>name</em>, <em>doc=None</em><big>)</big><a class="headerlink" href="#blinker.base.NamedSignal" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#blinker.base.Signal" title="blinker.base.Signal"><tt class="xref py py-class docutils literal"><span class="pre">blinker.base.Signal</span></tt></a></p>
<p>A named generic notification emitter.</p>
<dl class="attribute">
<dt id="blinker.base.NamedSignal.name">
<tt class="descname">name</tt><em class="property"> = None</em><a class="headerlink" href="#blinker.base.NamedSignal.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of this signal.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="blinker.base.Namespace">
<em class="property">class </em><tt class="descclassname">blinker.base.</tt><tt class="descname">Namespace</tt><a class="headerlink" href="#blinker.base.Namespace" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt></p>
<p>A mapping of signal names to signals.</p>
<dl class="method">
<dt id="blinker.base.Namespace.signal">
<tt class="descname">signal</tt><big>(</big><em>name</em>, <em>doc=None</em><big>)</big><a class="headerlink" href="#blinker.base.Namespace.signal" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <a class="reference internal" href="#blinker.base.NamedSignal" title="blinker.base.NamedSignal"><tt class="xref py py-class docutils literal"><span class="pre">NamedSignal</span></tt></a> <em>name</em>, creating it if required.</p>
<p>Repeated calls to this function will return the same signal object.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="blinker.base.WeakNamespace">
<em class="property">class </em><tt class="descclassname">blinker.base.</tt><tt class="descname">WeakNamespace</tt><big>(</big><em>*args</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#blinker.base.WeakNamespace" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">weakref.WeakValueDictionary</span></tt></p>
<p>A weak mapping of signal names to signals.</p>
<p>Automatically cleans up unused Signals when the last reference goes out
of scope. This namespace implementation exists for a measure of legacy
compatibility with Blinker <= 1.2, and may be dropped in the future.</p>
<div class="versionadded">
<p><span>New in version 1.3.</span></p>
</div>
<dl class="method">
<dt id="blinker.base.WeakNamespace.signal">
<tt class="descname">signal</tt><big>(</big><em>name</em>, <em>doc=None</em><big>)</big><a class="headerlink" href="#blinker.base.WeakNamespace.signal" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <a class="reference internal" href="#blinker.base.NamedSignal" title="blinker.base.NamedSignal"><tt class="xref py py-class docutils literal"><span class="pre">NamedSignal</span></tt></a> <em>name</em>, creating it if required.</p>
<p>Repeated calls to this function will return the same signal object.</p>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
<div class="section" id="blinker-changelog">
<h1>Blinker Changelog<a class="headerlink" href="#blinker-changelog" title="Permalink to this headline">¶</a></h1>
<div class="section" id="version-1-4">
<h2>Version 1.4<a class="headerlink" href="#version-1-4" title="Permalink to this headline">¶</a></h2>
<p>Released July 23, 2015</p>
<ul class="simple">
<li>Verified Python 3.4 support (no changes needed)</li>
<li>Additional bookkeeping cleanup for non-ANY connections at disconnect
time.</li>
<li>Added Signal._cleanup_bookeeping() to prune stale bookkeeping on
demand</li>
</ul>
</div>
<div class="section" id="version-1-3">
<h2>Version 1.3<a class="headerlink" href="#version-1-3" title="Permalink to this headline">¶</a></h2>
<p>Released July 3, 2013</p>
<ul class="simple">
<li>The global signal stash behind blinker.signal() is now backed by a
regular name-to-Signal dictionary. Previously, weak references were
held in the mapping and ephermal usage in code like
<tt class="docutils literal"><span class="pre">signal('foo').connect(...)</span></tt> could have surprising program behavior
depending on import order of modules.</li>
<li>blinker.Namespace is now built on a regular dict. Use
blinker.WeakNamespace for the older, weak-referencing behavior.</li>
<li>Signal.connect(‘text-sender’) uses an alterate hashing strategy to
avoid sharp edges in text identity.</li>
</ul>
</div>
<div class="section" id="version-1-2">
<h2>Version 1.2<a class="headerlink" href="#version-1-2" title="Permalink to this headline">¶</a></h2>
<p>Released October 26, 2011</p>
<ul class="simple">
<li>Added Signal.receiver_connected and
Signal.receiver_disconnected per-Signal signals.</li>
<li>Deprecated the global ‘receiver_connected’ signal.</li>
<li>Verified Python 3.2 support (no changes needed!)</li>
</ul>
</div>
<div class="section" id="version-1-1">
<h2>Version 1.1<a class="headerlink" href="#version-1-1" title="Permalink to this headline">¶</a></h2>
<p>Released July 21, 2010</p>
<ul class="simple">
<li>Added <tt class="docutils literal"><span class="pre">@signal.connect_via(sender)</span></tt> decorator</li>
<li>Added <tt class="docutils literal"><span class="pre">signal.connected_to</span></tt> shorthand name for the
<tt class="docutils literal"><span class="pre">temporarily_connected_to</span></tt> context manager.</li>
</ul>
</div>
<div class="section" id="version-1-0">
<h2>Version 1.0<a class="headerlink" href="#version-1-0" title="Permalink to this headline">¶</a></h2>
<p>Released March 28, 2010</p>
<ul class="simple">
<li>Python 3.0 and 3.1 compatibility</li>
</ul>
</div>
<div class="section" id="version-0-9">
<h2>Version 0.9<a class="headerlink" href="#version-0-9" title="Permalink to this headline">¶</a></h2>
<p>Released February 26, 2010</p>
<ul class="simple">
<li>Added <tt class="docutils literal"><span class="pre">Signal.temporarily_connected_to</span></tt> context manager</li>
<li>Docs! Sphinx docs, project web site.</li>
</ul>
</div>
<div class="section" id="version-0-8">
<h2>Version 0.8<a class="headerlink" href="#version-0-8" title="Permalink to this headline">¶</a></h2>
<p>Released February 14, 2010</p>
<ul class="simple">
<li>Initial release</li>
<li>Extracted from flatland.util.signals</li>
<li>Added Python 2.4 compatibility</li>
<li>Added nearly functional Python 3.1 compatibility (everything except
connecting to instance methods seems to work.)</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<a href="http://github.com/jek/blinker"><img style="position: fixed; top: 0; right: 0; border: 0;"
src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
3d11b2967e977eb9e95fd680625f7647
>
files
>
50
