MINI MINI MANI MO
<!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>Zope Component Architecture — zope.configuration 4.0 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '4.0',
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="zope.configuration 4.0 documentation" href="index.html" />
<link rel="next" title="The Zope 3 Component Architecture (Socket Example)" href="socketexample.html" />
<link rel="prev" title="zope.component" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="socketexample.html" title="The Zope 3 Component Architecture (Socket Example)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="zope.component"
accesskey="P">previous</a> |</li>
<li><a href="index.html">zope.configuration 4.0 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="zope-component-architecture">
<h1>Zope Component Architecture<a class="headerlink" href="#zope-component-architecture" title="Permalink to this headline">¶</a></h1>
<p>This package, together with <cite>zope.interface</cite>, provides facilities for
defining, registering and looking up components. There are two basic
kinds of components: adapters and utilities.</p>
<div class="section" id="utilities">
<h2>Utilities<a class="headerlink" href="#utilities" title="Permalink to this headline">¶</a></h2>
<p>Utilities are just components that provide an interface and that are
looked up by an interface and a name. Let’s look at a trivial utility
definition:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">zope</span> <span class="kn">import</span> <span class="n">interface</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">IGreeter</span><span class="p">(</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">greet</span><span class="p">():</span>
<span class="gp">... </span> <span class="s">"say hello"</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">Greeter</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">interface</span><span class="o">.</span><span class="n">implements</span><span class="p">(</span><span class="n">IGreeter</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">other</span><span class="o">=</span><span class="s">"world"</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">other</span> <span class="o">=</span> <span class="n">other</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">greet</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="s">"Hello"</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">other</span>
</pre></div>
</div>
<p>We can register an instance this class using <cite>provideUtility</cite> <a class="footnote-reference" href="#id5" id="id1">[1]</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">zope</span> <span class="kn">import</span> <span class="n">component</span>
<span class="gp">>>> </span><span class="n">greet</span> <span class="o">=</span> <span class="n">Greeter</span><span class="p">(</span><span class="s">'bob'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideUtility</span><span class="p">(</span><span class="n">greet</span><span class="p">,</span> <span class="n">IGreeter</span><span class="p">,</span> <span class="s">'robert'</span><span class="p">)</span>
</pre></div>
</div>
<p>In this example we registered the utility as providing the <cite>IGreeter</cite>
interface with a name of ‘bob’. We can look the interface up with
either <cite>queryUtility</cite> or <cite>getUtility</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryUtility</span><span class="p">(</span><span class="n">IGreeter</span><span class="p">,</span> <span class="s">'robert'</span><span class="p">)</span><span class="o">.</span><span class="n">greet</span><span class="p">()</span>
<span class="go">Hello bob</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">getUtility</span><span class="p">(</span><span class="n">IGreeter</span><span class="p">,</span> <span class="s">'robert'</span><span class="p">)</span><span class="o">.</span><span class="n">greet</span><span class="p">()</span>
<span class="go">Hello bob</span>
</pre></div>
</div>
<p><cite>queryUtility</cite> and <cite>getUtility</cite> differ in how failed lookups are handled:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryUtility</span><span class="p">(</span><span class="n">IGreeter</span><span class="p">,</span> <span class="s">'ted'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryUtility</span><span class="p">(</span><span class="n">IGreeter</span><span class="p">,</span> <span class="s">'ted'</span><span class="p">,</span> <span class="mi">42</span><span class="p">)</span>
<span class="go">42</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">getUtility</span><span class="p">(</span><span class="n">IGreeter</span><span class="p">,</span> <span class="s">'ted'</span><span class="p">)</span>
<span class="gp">... </span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ComponentLookupError</span>: <span class="n">(<InterfaceClass ...IGreeter>, 'ted')</span>
</pre></div>
</div>
<p>If a component provides only one interface, as in the example above,
then we can omit the provided interface from the call to <cite>provideUtility</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">ted</span> <span class="o">=</span> <span class="n">Greeter</span><span class="p">(</span><span class="s">'ted'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideUtility</span><span class="p">(</span><span class="n">ted</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">'ted'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryUtility</span><span class="p">(</span><span class="n">IGreeter</span><span class="p">,</span> <span class="s">'ted'</span><span class="p">)</span><span class="o">.</span><span class="n">greet</span><span class="p">()</span>
<span class="go">Hello ted</span>
</pre></div>
</div>
<p>The name defaults to an empty string:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">world</span> <span class="o">=</span> <span class="n">Greeter</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideUtility</span><span class="p">(</span><span class="n">world</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryUtility</span><span class="p">(</span><span class="n">IGreeter</span><span class="p">)</span><span class="o">.</span><span class="n">greet</span><span class="p">()</span>
<span class="go">Hello world</span>
</pre></div>
</div>
</div>
<div class="section" id="adapters">
<h2>Adapters<a class="headerlink" href="#adapters" title="Permalink to this headline">¶</a></h2>
<p>Adapters are components that are computed from other components to
adapt them to some interface. Because they are computed from other
objects, they are provided as factories, usually classes. Here, we’ll
create a greeter for persons, so we can provide personalized greetings
for different people:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">IPerson</span><span class="p">(</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">name</span> <span class="o">=</span> <span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s">"Name"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">PersonGreeter</span><span class="p">:</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="n">component</span><span class="o">.</span><span class="n">adapts</span><span class="p">(</span><span class="n">IPerson</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">interface</span><span class="o">.</span><span class="n">implements</span><span class="p">(</span><span class="n">IGreeter</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">person</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">person</span> <span class="o">=</span> <span class="n">person</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">greet</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="s">"Hello"</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">person</span><span class="o">.</span><span class="n">name</span>
</pre></div>
</div>
<p>The class defines a constructor that takes an argument for every
object adapted.</p>
<p>We used <cite>component.adapts</cite> to declare what we adapt. We can find
out if an object declares that it adapts anything using adaptedBy:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">component</span><span class="o">.</span><span class="n">adaptedBy</span><span class="p">(</span><span class="n">PersonGreeter</span><span class="p">))</span> <span class="o">==</span> <span class="p">[</span><span class="n">IPerson</span><span class="p">]</span>
<span class="go">True</span>
</pre></div>
</div>
<p>If an object makes no declaration, then None is returned:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">adaptedBy</span><span class="p">(</span><span class="n">Greeter</span><span class="p">())</span> <span class="ow">is</span> <span class="bp">None</span>
<span class="go">True</span>
</pre></div>
</div>
<p>If we declare the interfaces adapted and if we provide only one
interface, as in the example above, then we can provide the adapter
very simply <a class="footnote-reference" href="#id5" id="id2">[1]</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideAdapter</span><span class="p">(</span><span class="n">PersonGreeter</span><span class="p">)</span>
</pre></div>
</div>
<p>For adapters that adapt a single interface to a single interface
without a name, we can get the adapter by simply calling the
interface:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Person</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">interface</span><span class="o">.</span><span class="n">implements</span><span class="p">(</span><span class="n">IPerson</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="n">IGreeter</span><span class="p">(</span><span class="n">Person</span><span class="p">(</span><span class="s">"Sally"</span><span class="p">))</span><span class="o">.</span><span class="n">greet</span><span class="p">()</span>
<span class="go">Hello Sally</span>
</pre></div>
</div>
<p>We can also provide arguments to be very specific about what
how to register the adapter.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">BobPersonGreeter</span><span class="p">(</span><span class="n">PersonGreeter</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">name</span> <span class="o">=</span> <span class="s">'Bob'</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">greet</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="s">"Hello"</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">person</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="s">"my name is"</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideAdapter</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">BobPersonGreeter</span><span class="p">,</span> <span class="p">[</span><span class="n">IPerson</span><span class="p">],</span> <span class="n">IGreeter</span><span class="p">,</span> <span class="s">'bob'</span><span class="p">)</span>
</pre></div>
</div>
<p>The arguments can also be provided as keyword arguments:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">TedPersonGreeter</span><span class="p">(</span><span class="n">BobPersonGreeter</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">name</span> <span class="o">=</span> <span class="s">"Ted"</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideAdapter</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">factory</span><span class="o">=</span><span class="n">TedPersonGreeter</span><span class="p">,</span> <span class="n">adapts</span><span class="o">=</span><span class="p">[</span><span class="n">IPerson</span><span class="p">],</span>
<span class="gp">... </span> <span class="n">provides</span><span class="o">=</span><span class="n">IGreeter</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">'ted'</span><span class="p">)</span>
</pre></div>
</div>
<p>For named adapters, use <cite>queryAdapter</cite>, or <cite>getAdapter</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryAdapter</span><span class="p">(</span><span class="n">Person</span><span class="p">(</span><span class="s">"Sally"</span><span class="p">),</span> <span class="n">IGreeter</span><span class="p">,</span> <span class="s">'bob'</span><span class="p">)</span><span class="o">.</span><span class="n">greet</span><span class="p">()</span>
<span class="go">Hello Sally my name is Bob</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">getAdapter</span><span class="p">(</span><span class="n">Person</span><span class="p">(</span><span class="s">"Sally"</span><span class="p">),</span> <span class="n">IGreeter</span><span class="p">,</span> <span class="s">'ted'</span><span class="p">)</span><span class="o">.</span><span class="n">greet</span><span class="p">()</span>
<span class="go">Hello Sally my name is Ted</span>
</pre></div>
</div>
<p>If an adapter can’t be found, <cite>queryAdapter</cite> returns a default value
and <cite>getAdapter</cite> raises an error:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryAdapter</span><span class="p">(</span><span class="n">Person</span><span class="p">(</span><span class="s">"Sally"</span><span class="p">),</span> <span class="n">IGreeter</span><span class="p">,</span> <span class="s">'frank'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryAdapter</span><span class="p">(</span><span class="n">Person</span><span class="p">(</span><span class="s">"Sally"</span><span class="p">),</span> <span class="n">IGreeter</span><span class="p">,</span> <span class="s">'frank'</span><span class="p">,</span> <span class="mi">42</span><span class="p">)</span>
<span class="go">42</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">getAdapter</span><span class="p">(</span><span class="n">Person</span><span class="p">(</span><span class="s">"Sally"</span><span class="p">),</span> <span class="n">IGreeter</span><span class="p">,</span> <span class="s">'frank'</span><span class="p">)</span>
<span class="gp">... </span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ComponentLookupError</span>: <span class="n">(...Person...>, <...IGreeter>, 'frank')</span>
</pre></div>
</div>
<p>Adapters can adapt multiple objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">TwoPersonGreeter</span><span class="p">:</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="n">component</span><span class="o">.</span><span class="n">adapts</span><span class="p">(</span><span class="n">IPerson</span><span class="p">,</span> <span class="n">IPerson</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">interface</span><span class="o">.</span><span class="n">implements</span><span class="p">(</span><span class="n">IGreeter</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">person</span><span class="p">,</span> <span class="n">greeter</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">person</span> <span class="o">=</span> <span class="n">person</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">greeter</span> <span class="o">=</span> <span class="n">greeter</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">greet</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="s">"Hello"</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">person</span><span class="o">.</span><span class="n">name</span>
<span class="gp">... </span> <span class="k">print</span> <span class="s">"my name is"</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">greeter</span><span class="o">.</span><span class="n">name</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideAdapter</span><span class="p">(</span><span class="n">TwoPersonGreeter</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that the declaration-order of the Interfaces beeing adapted to is
important for adapter look up. It must be the the same as the order of
parameters given to the adapter and used to query the adapter. This is
especially the case when different Interfaces are adapt to (opposed to
this example).</p>
<p>To look up a multi-adapter, use either <cite>queryMultiAdapter</cite> or
<cite>getMultiAdapter</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">queryMultiAdapter</span><span class="p">((</span><span class="n">Person</span><span class="p">(</span><span class="s">"Sally"</span><span class="p">),</span> <span class="n">Person</span><span class="p">(</span><span class="s">"Bob"</span><span class="p">)),</span>
<span class="gp">... </span> <span class="n">IGreeter</span><span class="p">)</span><span class="o">.</span><span class="n">greet</span><span class="p">()</span>
<span class="go">Hello Sally</span>
<span class="go">my name is Bob</span>
</pre></div>
</div>
<p>Adapters need not be classes. Any callable will do. We use the
adapter decorator to declare that a callable object adapts some interfaces
(or classes):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">IJob</span><span class="p">(</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="gp">... </span> <span class="s">"A job"</span>
<span class="gp">>>> </span><span class="nd">@interface.implementer</span><span class="p">(</span><span class="n">IJob</span><span class="p">)</span>
<span class="gp">... </span><span class="k">class</span> <span class="nc">Job</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">pass</span>
<span class="gp">>>> </span><span class="nd">@interface.implementer</span><span class="p">(</span><span class="n">IJob</span><span class="p">)</span>
<span class="gp">... </span><span class="nd">@component.adapter</span><span class="p">(</span><span class="n">IPerson</span><span class="p">)</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">personJob</span><span class="p">(</span><span class="n">person</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">person</span><span class="p">,</span> <span class="s">'job'</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
</pre></div>
</div>
<p>In this example, the personJob function simply returns the person’s
<cite>job</cite> attribute if present, or None if it’s not present. An adapter
factory can return None to indicate that adaptation wasn’t possible.
Let’s register this adapter and try it out:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideAdapter</span><span class="p">(</span><span class="n">personJob</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">sally</span> <span class="o">=</span> <span class="n">Person</span><span class="p">(</span><span class="s">"Sally"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">IJob</span><span class="p">(</span><span class="n">sally</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">TypeError</span>: <span class="n">('Could not adapt', ...</span>
</pre></div>
</div>
<p>The adaptation failed because sally didn’t have a job. Let’s give her
one:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">job</span> <span class="o">=</span> <span class="n">Job</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">sally</span><span class="o">.</span><span class="n">job</span> <span class="o">=</span> <span class="n">job</span>
<span class="gp">>>> </span><span class="n">IJob</span><span class="p">(</span><span class="n">sally</span><span class="p">)</span> <span class="ow">is</span> <span class="n">job</span>
<span class="go">True</span>
</pre></div>
</div>
</div>
<div class="section" id="subscription-adapters">
<h2>Subscription Adapters<a class="headerlink" href="#subscription-adapters" title="Permalink to this headline">¶</a></h2>
<p>Unlike regular adapters, subscription adapters are used when we want
all of the adapters that adapt an object to a particular adapter.</p>
<p>Consider a validation problem. We have objects and we want to assess
whether they meet some sort of standards. We define a validation
interface:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">IValidate</span><span class="p">(</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">validate</span><span class="p">(</span><span class="n">ob</span><span class="p">):</span>
<span class="gp">... </span> <span class="sd">"""Determine whether the object is valid</span>
<span class="gp">...</span><span class="sd"></span>
<span class="gp">... </span><span class="sd"> Return a string describing a validation problem.</span>
<span class="gp">... </span><span class="sd"> An empty string is returned to indicate that the</span>
<span class="gp">... </span><span class="sd"> object is valid.</span>
<span class="gp">... </span><span class="sd"> """</span>
</pre></div>
</div>
<p>Perhaps we have documents:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">IDocument</span><span class="p">(</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">summary</span> <span class="o">=</span> <span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s">"Document summary"</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">body</span> <span class="o">=</span> <span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s">"Document text"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">Document</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">interface</span><span class="o">.</span><span class="n">implements</span><span class="p">(</span><span class="n">IDocument</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">summary</span><span class="p">,</span> <span class="n">body</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">summary</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">body</span> <span class="o">=</span> <span class="n">summary</span><span class="p">,</span> <span class="n">body</span>
</pre></div>
</div>
<p>Now, we may want to specify various validation rules for
documents. For example, we might require that the summary be a single
line:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">SingleLineSummary</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">component</span><span class="o">.</span><span class="n">adapts</span><span class="p">(</span><span class="n">IDocument</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">interface</span><span class="o">.</span><span class="n">implements</span><span class="p">(</span><span class="n">IValidate</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">doc</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">doc</span> <span class="o">=</span> <span class="n">doc</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">validate</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">if</span> <span class="s">'</span><span class="se">\n</span><span class="s">'</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">doc</span><span class="o">.</span><span class="n">summary</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s">'Summary should only have one line'</span>
<span class="gp">... </span> <span class="k">else</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s">''</span>
</pre></div>
</div>
<p>Or we might require the body to be at least 1000 characters in length:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">AdequateLength</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">component</span><span class="o">.</span><span class="n">adapts</span><span class="p">(</span><span class="n">IDocument</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">interface</span><span class="o">.</span><span class="n">implements</span><span class="p">(</span><span class="n">IValidate</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">doc</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">doc</span> <span class="o">=</span> <span class="n">doc</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">validate</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">doc</span><span class="o">.</span><span class="n">body</span><span class="p">)</span> <span class="o"><</span> <span class="mi">1000</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s">'too short'</span>
<span class="gp">... </span> <span class="k">else</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s">''</span>
</pre></div>
</div>
<p>We can register these as subscription adapters <a class="footnote-reference" href="#id5" id="id3">[1]</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideSubscriptionAdapter</span><span class="p">(</span><span class="n">SingleLineSummary</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideSubscriptionAdapter</span><span class="p">(</span><span class="n">AdequateLength</span><span class="p">)</span>
</pre></div>
</div>
<p>We can then use the subscribers to validate objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">doc</span> <span class="o">=</span> <span class="n">Document</span><span class="p">(</span><span class="s">"A</span><span class="se">\n</span><span class="s">Document"</span><span class="p">,</span> <span class="s">"blah"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="p">[</span><span class="n">adapter</span><span class="o">.</span><span class="n">validate</span><span class="p">()</span>
<span class="gp">... </span> <span class="k">for</span> <span class="n">adapter</span> <span class="ow">in</span> <span class="n">component</span><span class="o">.</span><span class="n">subscribers</span><span class="p">([</span><span class="n">doc</span><span class="p">],</span> <span class="n">IValidate</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">if</span> <span class="n">adapter</span><span class="o">.</span><span class="n">validate</span><span class="p">()]</span>
<span class="go">['Summary should only have one line', 'too short']</span>
<span class="gp">>>> </span><span class="n">doc</span> <span class="o">=</span> <span class="n">Document</span><span class="p">(</span><span class="s">"A</span><span class="se">\n</span><span class="s">Document"</span><span class="p">,</span> <span class="s">"blah"</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">)</span>
<span class="gp">>>> </span><span class="p">[</span><span class="n">adapter</span><span class="o">.</span><span class="n">validate</span><span class="p">()</span>
<span class="gp">... </span> <span class="k">for</span> <span class="n">adapter</span> <span class="ow">in</span> <span class="n">component</span><span class="o">.</span><span class="n">subscribers</span><span class="p">([</span><span class="n">doc</span><span class="p">],</span> <span class="n">IValidate</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">if</span> <span class="n">adapter</span><span class="o">.</span><span class="n">validate</span><span class="p">()]</span>
<span class="go">['Summary should only have one line']</span>
<span class="gp">>>> </span><span class="n">doc</span> <span class="o">=</span> <span class="n">Document</span><span class="p">(</span><span class="s">"A Document"</span><span class="p">,</span> <span class="s">"blah"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="p">[</span><span class="n">adapter</span><span class="o">.</span><span class="n">validate</span><span class="p">()</span>
<span class="gp">... </span> <span class="k">for</span> <span class="n">adapter</span> <span class="ow">in</span> <span class="n">component</span><span class="o">.</span><span class="n">subscribers</span><span class="p">([</span><span class="n">doc</span><span class="p">],</span> <span class="n">IValidate</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">if</span> <span class="n">adapter</span><span class="o">.</span><span class="n">validate</span><span class="p">()]</span>
<span class="go">['too short']</span>
</pre></div>
</div>
</div>
<div class="section" id="handlers">
<h2>Handlers<a class="headerlink" href="#handlers" title="Permalink to this headline">¶</a></h2>
<p>Handlers are subscription adapter factories that don’t produce
anything. They do all of their work when called. Handlers
are typically used to handle events.</p>
<p>Event subscribers are different from other subscription adapters in
that the caller of event subscribers doesn’t expect to interact with
them in any direct way. For example, an event publisher doesn’t
expect to get any return value. Because subscribers don’t need to
provide an API to their callers, it is more natural to define them
with functions, rather than classes. For example, in a
document-management system, we might want to record creation times for
documents:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">datetime</span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">documentCreated</span><span class="p">(</span><span class="n">event</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">event</span><span class="o">.</span><span class="n">doc</span><span class="o">.</span><span class="n">created</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()</span>
</pre></div>
</div>
<p>In this example, we have a function that takes an event and performs
some processing. It doesn’t actually return anything. This is a
special case of a subscription adapter that adapts an event to
nothing. All of the work is done when the adapter “factory” is
called. We call subscribers that don’t actually create anything
“handlers”. There are special APIs for registering and calling
them.</p>
<p>To register the subscriber above, we define a document-created event:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">IDocumentCreated</span><span class="p">(</span><span class="n">interface</span><span class="o">.</span><span class="n">Interface</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">doc</span> <span class="o">=</span> <span class="n">interface</span><span class="o">.</span><span class="n">Attribute</span><span class="p">(</span><span class="s">"The document that was created"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">DocumentCreated</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">interface</span><span class="o">.</span><span class="n">implements</span><span class="p">(</span><span class="n">IDocumentCreated</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">doc</span><span class="p">):</span>
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">doc</span> <span class="o">=</span> <span class="n">doc</span>
</pre></div>
</div>
<p>We’ll also change our handler definition to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@component.adapter</span><span class="p">(</span><span class="n">IDocumentCreated</span><span class="p">)</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">documentCreated</span><span class="p">(</span><span class="n">event</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">event</span><span class="o">.</span><span class="n">doc</span><span class="o">.</span><span class="n">created</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()</span>
</pre></div>
</div>
<p>This marks the handler as an adapter of <cite>IDocumentCreated</cite> events.</p>
<p>Now we’ll register the handler <a class="footnote-reference" href="#id5" id="id4">[1]</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">provideHandler</span><span class="p">(</span><span class="n">documentCreated</span><span class="p">)</span>
</pre></div>
</div>
<p>Now, if we can create an event and use the <cite>handle</cite> function to call
handlers registered for the event:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">component</span><span class="o">.</span><span class="n">handle</span><span class="p">(</span><span class="n">DocumentCreated</span><span class="p">(</span><span class="n">doc</span><span class="p">))</span>
<span class="gp">>>> </span><span class="n">doc</span><span class="o">.</span><span class="n">created</span><span class="o">.</span><span class="n">__class__</span><span class="o">.</span><span class="n">__name__</span>
<span class="go">'datetime'</span>
</pre></div>
</div>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>, <a class="fn-backref" href="#id3">3</a>, <a class="fn-backref" href="#id4">4</a>)</em> CAUTION: This API should only be used from test or
application-setup code. This API shouldn’t be used by regular
library modules, as component registration is a configuration
activity.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Zope Component Architecture</a><ul>
<li><a class="reference internal" href="#utilities">Utilities</a></li>
<li><a class="reference internal" href="#adapters">Adapters</a></li>
<li><a class="reference internal" href="#subscription-adapters">Subscription Adapters</a></li>
<li><a class="reference internal" href="#handlers">Handlers</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter"><tt class="docutils literal"><span class="pre">zope.component</span></tt></a></p>
<h4>Next topic</h4>
<p class="topless"><a href="socketexample.html"
title="next chapter">The Zope 3 Component Architecture (Socket Example)</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/narr.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="socketexample.html" title="The Zope 3 Component Architecture (Socket Example)"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="zope.component"
>previous</a> |</li>
<li><a href="index.html">zope.configuration 4.0 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2012, Zope Foundation Contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
OHA YOOOO