Why Gemfury?
Push, build, and install
RubyGems
npm packages
Python packages
Maven artifacts
PHP packages
Go Modules
Debian packages
RPM packages
NuGet packages
squarecapadmin
squarecapadmin / zope.interface python
Repository URL to install this package:
|
Version:
4.1.2 ▾
|
<!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.interface.interfaces — zope.interface 4.0.1 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.1',
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.interface 4.0.1 documentation" href="../../../index.html" />
<link rel="up" title="zope.interface" href="../interface.html" />
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li><a href="../../../index.html">zope.interface 4.0.1 documentation</a> »</li>
<li><a href="../../index.html" >Module code</a> »</li>
<li><a href="../interface.html" accesskey="U">zope.interface</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<h1>Source code for zope.interface.interfaces</h1><div class="highlight"><pre>
<span class="c">##############################################################################</span>
<span class="c">#</span>
<span class="c"># Copyright (c) 2002 Zope Foundation and Contributors.</span>
<span class="c"># All Rights Reserved.</span>
<span class="c">#</span>
<span class="c"># This software is subject to the provisions of the Zope Public License,</span>
<span class="c"># Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.</span>
<span class="c"># THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED</span>
<span class="c"># WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED</span>
<span class="c"># WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS</span>
<span class="c"># FOR A PARTICULAR PURPOSE.</span>
<span class="c">#</span>
<span class="c">##############################################################################</span>
<span class="sd">"""Interface Package Interfaces</span>
<span class="sd">"""</span>
<span class="n">__docformat__</span> <span class="o">=</span> <span class="s">'restructuredtext'</span>
<span class="kn">from</span> <span class="nn">zope.interface.interface</span> <span class="kn">import</span> <span class="n">Attribute</span>
<span class="kn">from</span> <span class="nn">zope.interface.interface</span> <span class="kn">import</span> <span class="n">Interface</span>
<span class="kn">from</span> <span class="nn">zope.interface.declarations</span> <span class="kn">import</span> <span class="n">implementer</span>
<span class="kn">from</span> <span class="nn">zope.interface._compat</span> <span class="kn">import</span> <span class="n">_u</span>
<span class="n">_BLANK</span> <span class="o">=</span> <span class="n">_u</span><span class="p">(</span><span class="s">''</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">IElement</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Objects that have basic documentation and tagged values.</span>
<span class="sd"> """</span>
<span class="n">__name__</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="s">'The object name'</span><span class="p">)</span>
<span class="n">__doc__</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">'__doc__'</span><span class="p">,</span> <span class="s">'The object doc string'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">getTaggedValue</span><span class="p">(</span><span class="n">tag</span><span class="p">):</span>
<span class="sd">"""Returns the value associated with `tag`.</span>
<span class="sd"> Raise a `KeyError` of the tag isn't set.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">queryTaggedValue</span><span class="p">(</span><span class="n">tag</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Returns the value associated with `tag`.</span>
<span class="sd"> Return the default value of the tag isn't set.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">getTaggedValueTags</span><span class="p">():</span>
<span class="sd">"""Returns a list of all tags."""</span>
<span class="k">def</span> <span class="nf">setTaggedValue</span><span class="p">(</span><span class="n">tag</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
<span class="sd">"""Associates `value` with `key`."""</span>
<span class="k">class</span> <span class="nc">IAttribute</span><span class="p">(</span><span class="n">IElement</span><span class="p">):</span>
<span class="sd">"""Attribute descriptors"""</span>
<span class="n">interface</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">'interface'</span><span class="p">,</span>
<span class="s">'Stores the interface instance in which the '</span>
<span class="s">'attribute is located.'</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">IMethod</span><span class="p">(</span><span class="n">IAttribute</span><span class="p">):</span>
<span class="sd">"""Method attributes"""</span>
<span class="k">def</span> <span class="nf">getSignatureInfo</span><span class="p">():</span>
<span class="sd">"""Returns the signature information.</span>
<span class="sd"> This method returns a dictionary with the following keys:</span>
<span class="sd"> o `positional` - All positional arguments.</span>
<span class="sd"> o `required` - A list of all required arguments.</span>
<span class="sd"> o `optional` - A list of all optional arguments.</span>
<span class="sd"> o `varargs` - The name of the varargs argument.</span>
<span class="sd"> o `kwargs` - The name of the kwargs argument.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">getSignatureString</span><span class="p">():</span>
<span class="sd">"""Return a signature string suitable for inclusion in documentation.</span>
<span class="sd"> This method returns the function signature string. For example, if you</span>
<span class="sd"> have `func(a, b, c=1, d='f')`, then the signature string is `(a, b,</span>
<span class="sd"> c=1, d='f')`.</span>
<span class="sd"> """</span>
<div class="viewcode-block" id="ISpecification"><a class="viewcode-back" href="../../../api.html#zope.interface.interfaces.ISpecification">[docs]</a><span class="k">class</span> <span class="nc">ISpecification</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Object Behavioral specifications"""</span>
<span class="k">def</span> <span class="nf">providedBy</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="sd">"""Test whether the interface is implemented by the object</span>
<span class="sd"> Return true of the object asserts that it implements the</span>
<span class="sd"> interface, including asserting that it implements an extended</span>
<span class="sd"> interface.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">implementedBy</span><span class="p">(</span><span class="n">class_</span><span class="p">):</span>
<span class="sd">"""Test whether the interface is implemented by instances of the class</span>
<span class="sd"> Return true of the class asserts that its instances implement the</span>
<span class="sd"> interface, including asserting that they implement an extended</span>
<span class="sd"> interface.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">isOrExtends</span><span class="p">(</span><span class="n">other</span><span class="p">):</span>
<span class="sd">"""Test whether the specification is or extends another</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">extends</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">strict</span><span class="o">=</span><span class="bp">True</span><span class="p">):</span>
<span class="sd">"""Test whether a specification extends another</span>
<span class="sd"> The specification extends other if it has other as a base</span>
<span class="sd"> interface or if one of it's bases extends other.</span>
<span class="sd"> If strict is false, then the specification extends itself.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">weakref</span><span class="p">(</span><span class="n">callback</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Return a weakref to the specification</span>
<span class="sd"> This method is, regrettably, needed to allow weakrefs to be</span>
<span class="sd"> computed to security-proxied specifications. While the</span>
<span class="sd"> zope.interface package does not require zope.security or</span>
<span class="sd"> zope.proxy, it has to be able to coexist with it.</span>
<span class="sd"> """</span>
<span class="n">__bases__</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"""Base specifications</span>
<span class="s"> A tuple if specifications from which this specification is</span>
<span class="s"> directly derived.</span>
<span class="s"> """</span><span class="p">)</span>
<span class="n">__sro__</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"""Specification-resolution order</span>
<span class="s"> A tuple of the specification and all of it's ancestor</span>
<span class="s"> specifications from most specific to least specific.</span>
<span class="s"> (This is similar to the method-resolution order for new-style classes.)</span>
<span class="s"> """</span><span class="p">)</span>
<span class="n">__iro__</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"""Interface-resolution order</span>
<span class="s"> A tuple of the of the specification's ancestor interfaces from</span>
<span class="s"> most specific to least specific. The specification itself is</span>
<span class="s"> included if it is an interface.</span>
<span class="s"> (This is similar to the method-resolution order for new-style classes.)</span>
<span class="s"> """</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Look up the description for a name</span>
<span class="sd"> If the named attribute is not defined, the default is</span>
<span class="sd"> returned.</span>
<span class="sd"> """</span>
</div>
<div class="viewcode-block" id="IInterface"><a class="viewcode-back" href="../../../api.html#zope.interface.interfaces.IInterface">[docs]</a><span class="k">class</span> <span class="nc">IInterface</span><span class="p">(</span><span class="n">ISpecification</span><span class="p">,</span> <span class="n">IElement</span><span class="p">):</span>
<span class="sd">"""Interface objects</span>
<span class="sd"> Interface objects describe the behavior of an object by containing</span>
<span class="sd"> useful information about the object. This information includes:</span>
<span class="sd"> o Prose documentation about the object. In Python terms, this</span>
<span class="sd"> is called the "doc string" of the interface. In this element,</span>
<span class="sd"> you describe how the object works in prose language and any</span>
<span class="sd"> other useful information about the object.</span>
<span class="sd"> o Descriptions of attributes. Attribute descriptions include</span>
<span class="sd"> the name of the attribute and prose documentation describing</span>
<span class="sd"> the attributes usage.</span>
<span class="sd"> o Descriptions of methods. Method descriptions can include:</span>
<span class="sd"> - Prose "doc string" documentation about the method and its</span>
<span class="sd"> usage.</span>
<span class="sd"> - A description of the methods arguments; how many arguments</span>
<span class="sd"> are expected, optional arguments and their default values,</span>
<span class="sd"> the position or arguments in the signature, whether the</span>
<span class="sd"> method accepts arbitrary arguments and whether the method</span>
<span class="sd"> accepts arbitrary keyword arguments.</span>
<span class="sd"> o Optional tagged data. Interface objects (and their attributes and</span>
<span class="sd"> methods) can have optional, application specific tagged data</span>
<span class="sd"> associated with them. Examples uses for this are examples,</span>
<span class="sd"> security assertions, pre/post conditions, and other possible</span>
<span class="sd"> information you may want to associate with an Interface or its</span>
<span class="sd"> attributes.</span>
<span class="sd"> Not all of this information is mandatory. For example, you may</span>
<span class="sd"> only want the methods of your interface to have prose</span>
<span class="sd"> documentation and not describe the arguments of the method in</span>
<span class="sd"> exact detail. Interface objects are flexible and let you give or</span>
<span class="sd"> take any of these components.</span>
<span class="sd"> Interfaces are created with the Python class statement using</span>
<span class="sd"> either Interface.Interface or another interface, as in::</span>
<span class="sd"> from zope.interface import Interface</span>
<span class="sd"> class IMyInterface(Interface):</span>
<span class="sd"> '''Interface documentation'''</span>
<span class="sd"> def meth(arg1, arg2):</span>
<span class="sd"> '''Documentation for meth'''</span>
<span class="sd"> # Note that there is no self argument</span>
<span class="sd"> class IMySubInterface(IMyInterface):</span>
<span class="sd"> '''Interface documentation'''</span>
<span class="sd"> def meth2():</span>
<span class="sd"> '''Documentation for meth2'''</span>
<span class="sd"> You use interfaces in two ways:</span>
<span class="sd"> o You assert that your object implement the interfaces.</span>
<span class="sd"> There are several ways that you can assert that an object</span>
<span class="sd"> implements an interface:</span>
<span class="sd"> 1. Call zope.interface.implements in your class definition.</span>
<span class="sd"> 2. Call zope.interfaces.directlyProvides on your object.</span>
<span class="sd"> 3. Call 'zope.interface.classImplements' to assert that instances</span>
<span class="sd"> of a class implement an interface.</span>
<span class="sd"> For example::</span>
<span class="sd"> from zope.interface import classImplements</span>
<span class="sd"> classImplements(some_class, some_interface)</span>
<span class="sd"> This approach is useful when it is not an option to modify</span>
<span class="sd"> the class source. Note that this doesn't affect what the</span>
<span class="sd"> class itself implements, but only what its instances</span>
<span class="sd"> implement.</span>
<span class="sd"> o You query interface meta-data. See the IInterface methods and</span>
<span class="sd"> attributes for details.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">names</span><span class="p">(</span><span class="nb">all</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
<span class="sd">"""Get the interface attribute names</span>
<span class="sd"> Return a sequence of the names of the attributes, including</span>
<span class="sd"> methods, included in the interface definition.</span>
<span class="sd"> Normally, only directly defined attributes are included. If</span>
<span class="sd"> a true positional or keyword argument is given, then</span>
<span class="sd"> attributes defined by base classes will be included.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">namesAndDescriptions</span><span class="p">(</span><span class="nb">all</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
<span class="sd">"""Get the interface attribute names and descriptions</span>
<span class="sd"> Return a sequence of the names and descriptions of the</span>
<span class="sd"> attributes, including methods, as name-value pairs, included</span>
<span class="sd"> in the interface definition.</span>
<span class="sd"> Normally, only directly defined attributes are included. If</span>
<span class="sd"> a true positional or keyword argument is given, then</span>
<span class="sd"> attributes defined by base classes will be included.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">__getitem__</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="sd">"""Get the description for a name</span>
<span class="sd"> If the named attribute is not defined, a KeyError is raised.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">direct</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="sd">"""Get the description for the name if it was defined by the interface</span>
<span class="sd"> If the interface doesn't define the name, returns None.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">validateInvariants</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">errors</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Validate invariants</span>
<span class="sd"> Validate object to defined invariants. If errors is None,</span>
<span class="sd"> raises first Invalid error; if errors is a list, appends all errors</span>
<span class="sd"> to list, then raises Invalid with the errors as the first element</span>
<span class="sd"> of the "args" tuple."""</span>
<span class="k">def</span> <span class="nf">__contains__</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="sd">"""Test whether the name is defined by the interface"""</span>
<span class="k">def</span> <span class="nf">__iter__</span><span class="p">():</span>
<span class="sd">"""Return an iterator over the names defined by the interface</span>
<span class="sd"> The names iterated include all of the names defined by the</span>
<span class="sd"> interface directly and indirectly by base interfaces.</span>
<span class="sd"> """</span>
<span class="n">__module__</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"""The name of the module defining the interface"""</span><span class="p">)</span>
</div>
<div class="viewcode-block" id="IDeclaration"><a class="viewcode-back" href="../../../api.html#zope.interface.interfaces.IDeclaration">[docs]</a><span class="k">class</span> <span class="nc">IDeclaration</span><span class="p">(</span><span class="n">ISpecification</span><span class="p">):</span>
<span class="sd">"""Interface declaration</span>
<span class="sd"> Declarations are used to express the interfaces implemented by</span>
<span class="sd"> classes or provided by objects.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">__contains__</span><span class="p">(</span><span class="n">interface</span><span class="p">):</span>
<span class="sd">"""Test whether an interface is in the specification</span>
<span class="sd"> Return true if the given interface is one of the interfaces in</span>
<span class="sd"> the specification and false otherwise.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">__iter__</span><span class="p">():</span>
<span class="sd">"""Return an iterator for the interfaces in the specification</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">flattened</span><span class="p">():</span>
<span class="sd">"""Return an iterator of all included and extended interfaces</span>
<span class="sd"> An iterator is returned for all interfaces either included in</span>
<span class="sd"> or extended by interfaces included in the specifications</span>
<span class="sd"> without duplicates. The interfaces are in "interface</span>
<span class="sd"> resolution order". The interface resolution order is such that</span>
<span class="sd"> base interfaces are listed after interfaces that extend them</span>
<span class="sd"> and, otherwise, interfaces are included in the order that they</span>
<span class="sd"> were defined in the specification.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">__sub__</span><span class="p">(</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Create an interface specification with some interfaces excluded</span>
<span class="sd"> The argument can be an interface or an interface</span>
<span class="sd"> specifications. The interface or interfaces given in a</span>
<span class="sd"> specification are subtracted from the interface specification.</span>
<span class="sd"> Removing an interface that is not in the specification does</span>
<span class="sd"> not raise an error. Doing so has no effect.</span>
<span class="sd"> Removing an interface also removes sub-interfaces of the interface.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">__add__</span><span class="p">(</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Create an interface specification with some interfaces added</span>
<span class="sd"> The argument can be an interface or an interface</span>
<span class="sd"> specifications. The interface or interfaces given in a</span>
<span class="sd"> specification are added to the interface specification.</span>
<span class="sd"> Adding an interface that is already in the specification does</span>
<span class="sd"> not raise an error. Doing so has no effect.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">__nonzero__</span><span class="p">():</span>
<span class="sd">"""Return a true value of the interface specification is non-empty</span>
<span class="sd"> """</span>
</div>
<span class="k">class</span> <span class="nc">IInterfaceDeclaration</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Declare and check the interfaces of objects</span>
<span class="sd"> The functions defined in this interface are used to declare the</span>
<span class="sd"> interfaces that objects provide and to query the interfaces that have</span>
<span class="sd"> been declared.</span>
<span class="sd"> Interfaces can be declared for objects in two ways:</span>
<span class="sd"> - Interfaces are declared for instances of the object's class</span>
<span class="sd"> - Interfaces are declared for the object directly.</span>
<span class="sd"> The interfaces declared for an object are, therefore, the union of</span>
<span class="sd"> interfaces declared for the object directly and the interfaces</span>
<span class="sd"> declared for instances of the object's class.</span>
<span class="sd"> Note that we say that a class implements the interfaces provided</span>
<span class="sd"> by it's instances. An instance can also provide interfaces</span>
<span class="sd"> directly. The interfaces provided by an object are the union of</span>
<span class="sd"> the interfaces provided directly and the interfaces implemented by</span>
<span class="sd"> the class.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">providedBy</span><span class="p">(</span><span class="n">ob</span><span class="p">):</span>
<span class="sd">"""Return the interfaces provided by an object</span>
<span class="sd"> This is the union of the interfaces directly provided by an</span>
<span class="sd"> object and interfaces implemented by it's class.</span>
<span class="sd"> The value returned is an IDeclaration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">implementedBy</span><span class="p">(</span><span class="n">class_</span><span class="p">):</span>
<span class="sd">"""Return the interfaces implemented for a class' instances</span>
<span class="sd"> The value returned is an IDeclaration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">classImplements</span><span class="p">(</span><span class="n">class_</span><span class="p">,</span> <span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Declare additional interfaces implemented for instances of a class</span>
<span class="sd"> The arguments after the class are one or more interfaces or</span>
<span class="sd"> interface specifications (IDeclaration objects).</span>
<span class="sd"> The interfaces given (including the interfaces in the</span>
<span class="sd"> specifications) are added to any interfaces previously</span>
<span class="sd"> declared.</span>
<span class="sd"> Consider the following example::</span>
<span class="sd"> class C(A, B):</span>
<span class="sd"> ...</span>
<span class="sd"> classImplements(C, I1, I2)</span>
<span class="sd"> Instances of ``C`` provide ``I1``, ``I2``, and whatever interfaces</span>
<span class="sd"> instances of ``A`` and ``B`` provide.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">implementer</span><span class="p">(</span><span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Create a decorator for declaring interfaces implemented by a facory</span>
<span class="sd"> A callable is returned that makes an implements declaration on</span>
<span class="sd"> objects passed to it.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">classImplementsOnly</span><span class="p">(</span><span class="n">class_</span><span class="p">,</span> <span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Declare the only interfaces implemented by instances of a class</span>
<span class="sd"> The arguments after the class are one or more interfaces or</span>
<span class="sd"> interface specifications (IDeclaration objects).</span>
<span class="sd"> The interfaces given (including the interfaces in the</span>
<span class="sd"> specifications) replace any previous declarations.</span>
<span class="sd"> Consider the following example::</span>
<span class="sd"> class C(A, B):</span>
<span class="sd"> ...</span>
<span class="sd"> classImplements(C, IA, IB. IC)</span>
<span class="sd"> classImplementsOnly(C. I1, I2)</span>
<span class="sd"> Instances of ``C`` provide only ``I1``, ``I2``, and regardless of</span>
<span class="sd"> whatever interfaces instances of ``A`` and ``B`` implement.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">implementer_only</span><span class="p">(</span><span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Create a decorator for declaring the only interfaces implemented </span>
<span class="sd"> </span>
<span class="sd"> A callable is returned that makes an implements declaration on</span>
<span class="sd"> objects passed to it.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">directlyProvidedBy</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="sd">"""Return the interfaces directly provided by the given object</span>
<span class="sd"> The value returned is an IDeclaration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">directlyProvides</span><span class="p">(</span><span class="nb">object</span><span class="p">,</span> <span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Declare interfaces declared directly for an object</span>
<span class="sd"> The arguments after the object are one or more interfaces or</span>
<span class="sd"> interface specifications (IDeclaration objects).</span>
<span class="sd"> The interfaces given (including the interfaces in the</span>
<span class="sd"> specifications) replace interfaces previously</span>
<span class="sd"> declared for the object.</span>
<span class="sd"> Consider the following example::</span>
<span class="sd"> class C(A, B):</span>
<span class="sd"> ...</span>
<span class="sd"> ob = C()</span>
<span class="sd"> directlyProvides(ob, I1, I2)</span>
<span class="sd"> The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces</span>
<span class="sd"> instances have been declared for instances of ``C``.</span>
<span class="sd"> To remove directly provided interfaces, use ``directlyProvidedBy`` and</span>
<span class="sd"> subtract the unwanted interfaces. For example::</span>
<span class="sd"> directlyProvides(ob, directlyProvidedBy(ob)-I2)</span>
<span class="sd"> removes I2 from the interfaces directly provided by</span>
<span class="sd"> ``ob``. The object, ``ob`` no longer directly provides ``I2``,</span>
<span class="sd"> although it might still provide ``I2`` if it's class</span>
<span class="sd"> implements ``I2``.</span>
<span class="sd"> To add directly provided interfaces, use ``directlyProvidedBy`` and</span>
<span class="sd"> include additional interfaces. For example::</span>
<span class="sd"> directlyProvides(ob, directlyProvidedBy(ob), I2)</span>
<span class="sd"> adds I2 to the interfaces directly provided by ob.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">alsoProvides</span><span class="p">(</span><span class="nb">object</span><span class="p">,</span> <span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Declare additional interfaces directly for an object::</span>
<span class="sd"> alsoProvides(ob, I1)</span>
<span class="sd"> is equivalent to::</span>
<span class="sd"> directlyProvides(ob, directlyProvidedBy(ob), I1)</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">noLongerProvides</span><span class="p">(</span><span class="nb">object</span><span class="p">,</span> <span class="n">interface</span><span class="p">):</span>
<span class="sd">"""Remove an interface from the list of an object's directly</span>
<span class="sd"> provided interfaces::</span>
<span class="sd"> noLongerProvides(ob, I1)</span>
<span class="sd"> is equivalent to::</span>
<span class="sd"> directlyProvides(ob, directlyProvidedBy(ob)-I1)</span>
<span class="sd"> with the exception that if ``I1`` is an interface that is</span>
<span class="sd"> provided by ``ob`` through the class's implementation,</span>
<span class="sd"> ValueError is raised.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">implements</span><span class="p">(</span><span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Declare interfaces implemented by instances of a class</span>
<span class="sd"> This function is called in a class definition (Python 2.x only).</span>
<span class="sd"> The arguments are one or more interfaces or interface</span>
<span class="sd"> specifications (IDeclaration objects).</span>
<span class="sd"> The interfaces given (including the interfaces in the</span>
<span class="sd"> specifications) are added to any interfaces previously</span>
<span class="sd"> declared.</span>
<span class="sd"> Previous declarations include declarations for base classes</span>
<span class="sd"> unless implementsOnly was used.</span>
<span class="sd"> This function is provided for convenience. It provides a more</span>
<span class="sd"> convenient way to call classImplements. For example::</span>
<span class="sd"> implements(I1)</span>
<span class="sd"> is equivalent to calling::</span>
<span class="sd"> classImplements(C, I1)</span>
<span class="sd"> after the class has been created.</span>
<span class="sd"> Consider the following example (Python 2.x only)::</span>
<span class="sd"> class C(A, B):</span>
<span class="sd"> implements(I1, I2)</span>
<span class="sd"> Instances of ``C`` implement ``I1``, ``I2``, and whatever interfaces</span>
<span class="sd"> instances of ``A`` and ``B`` implement.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">implementsOnly</span><span class="p">(</span><span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Declare the only interfaces implemented by instances of a class</span>
<span class="sd"> This function is called in a class definition (Python 2.x only).</span>
<span class="sd"> The arguments are one or more interfaces or interface</span>
<span class="sd"> specifications (IDeclaration objects).</span>
<span class="sd"> Previous declarations including declarations for base classes</span>
<span class="sd"> are overridden.</span>
<span class="sd"> This function is provided for convenience. It provides a more</span>
<span class="sd"> convenient way to call classImplementsOnly. For example::</span>
<span class="sd"> implementsOnly(I1)</span>
<span class="sd"> is equivalent to calling::</span>
<span class="sd"> classImplementsOnly(I1)</span>
<span class="sd"> after the class has been created.</span>
<span class="sd"> Consider the following example (Python 2.x only)::</span>
<span class="sd"> class C(A, B):</span>
<span class="sd"> implementsOnly(I1, I2)</span>
<span class="sd"> Instances of ``C`` implement ``I1``, ``I2``, regardless of what</span>
<span class="sd"> instances of ``A`` and ``B`` implement.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">classProvides</span><span class="p">(</span><span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Declare interfaces provided directly by a class</span>
<span class="sd"> This function is called in a class definition.</span>
<span class="sd"> The arguments are one or more interfaces or interface</span>
<span class="sd"> specifications (IDeclaration objects).</span>
<span class="sd"> The given interfaces (including the interfaces in the</span>
<span class="sd"> specifications) are used to create the class's direct-object</span>
<span class="sd"> interface specification. An error will be raised if the module</span>
<span class="sd"> class has an direct interface specification. In other words, it is</span>
<span class="sd"> an error to call this function more than once in a class</span>
<span class="sd"> definition.</span>
<span class="sd"> Note that the given interfaces have nothing to do with the</span>
<span class="sd"> interfaces implemented by instances of the class.</span>
<span class="sd"> This function is provided for convenience. It provides a more</span>
<span class="sd"> convenient way to call directlyProvides for a class. For example::</span>
<span class="sd"> classProvides(I1)</span>
<span class="sd"> is equivalent to calling::</span>
<span class="sd"> directlyProvides(theclass, I1)</span>
<span class="sd"> after the class has been created.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">provider</span><span class="p">(</span><span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""A class decorator version of classProvides"""</span>
<span class="k">def</span> <span class="nf">moduleProvides</span><span class="p">(</span><span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Declare interfaces provided by a module</span>
<span class="sd"> This function is used in a module definition.</span>
<span class="sd"> The arguments are one or more interfaces or interface</span>
<span class="sd"> specifications (IDeclaration objects).</span>
<span class="sd"> The given interfaces (including the interfaces in the</span>
<span class="sd"> specifications) are used to create the module's direct-object</span>
<span class="sd"> interface specification. An error will be raised if the module</span>
<span class="sd"> already has an interface specification. In other words, it is</span>
<span class="sd"> an error to call this function more than once in a module</span>
<span class="sd"> definition.</span>
<span class="sd"> This function is provided for convenience. It provides a more</span>
<span class="sd"> convenient way to call directlyProvides for a module. For example::</span>
<span class="sd"> moduleImplements(I1)</span>
<span class="sd"> is equivalent to::</span>
<span class="sd"> directlyProvides(sys.modules[__name__], I1)</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">Declaration</span><span class="p">(</span><span class="o">*</span><span class="n">interfaces</span><span class="p">):</span>
<span class="sd">"""Create an interface specification</span>
<span class="sd"> The arguments are one or more interfaces or interface</span>
<span class="sd"> specifications (IDeclaration objects).</span>
<span class="sd"> A new interface specification (IDeclaration) with</span>
<span class="sd"> the given interfaces is returned.</span>
<span class="sd"> """</span>
<span class="k">class</span> <span class="nc">IAdapterRegistry</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Provide an interface-based registry for adapters</span>
<span class="sd"> This registry registers objects that are in some sense "from" a</span>
<span class="sd"> sequence of specification to an interface and a name.</span>
<span class="sd"> No specific semantics are assumed for the registered objects,</span>
<span class="sd"> however, the most common application will be to register factories</span>
<span class="sd"> that adapt objects providing required specifications to a provided</span>
<span class="sd"> interface.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">register</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
<span class="sd">"""Register a value</span>
<span class="sd"> A value is registered for a *sequence* of required specifications, a</span>
<span class="sd"> provided interface, and a name.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registered</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Return the component registered for the given interfaces and name</span>
<span class="sd"> Unlike the lookup method, this methods won't retrieve</span>
<span class="sd"> components registered for more specific required interfaces or</span>
<span class="sd"> less specific provided interfaces.</span>
<span class="sd"> If no component was registered exactly for the given</span>
<span class="sd"> interfaces and name, then None is returned.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">lookup</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">''</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Lookup a value</span>
<span class="sd"> A value is looked up based on a *sequence* of required</span>
<span class="sd"> specifications, a provided interface, and a name.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">queryMultiAdapter</span><span class="p">(</span><span class="n">objects</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Adapt a sequence of objects to a named, provided, interface</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">lookup1</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Lookup a value using a single required interface</span>
<span class="sd"> A value is looked up based on a single required</span>
<span class="sd"> specifications, a provided interface, and a name.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">queryAdapter</span><span class="p">(</span><span class="nb">object</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Adapt an object using a registered adapter factory.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">adapter_hook</span><span class="p">(</span><span class="n">provided</span><span class="p">,</span> <span class="nb">object</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Adapt an object using a registered adapter factory.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">lookupAll</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="n">provided</span><span class="p">):</span>
<span class="sd">"""Find all adapters from the required to the provided interfaces</span>
<span class="sd"> An iterable object is returned that provides name-value two-tuples.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">names</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="n">provided</span><span class="p">):</span>
<span class="sd">"""Return the names for which there are registered objects</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">subscribe</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">subscriber</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Register a subscriber</span>
<span class="sd"> A subscriber is registered for a *sequence* of required</span>
<span class="sd"> specifications, a provided interface, and a name.</span>
<span class="sd"> Multiple subscribers may be registered for the same (or</span>
<span class="sd"> equivalent) interfaces.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">subscriptions</span><span class="p">(</span><span class="n">required</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Get a sequence of subscribers</span>
<span class="sd"> Subscribers for a *sequence* of required interfaces, and a provided</span>
<span class="sd"> interface are returned.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">subscribers</span><span class="p">(</span><span class="n">objects</span><span class="p">,</span> <span class="n">provided</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Get a sequence of subscription adapters</span>
<span class="sd"> """</span>
<span class="c"># begin formerly in zope.component</span>
<span class="k">class</span> <span class="nc">ComponentLookupError</span><span class="p">(</span><span class="ne">LookupError</span><span class="p">):</span>
<span class="sd">"""A component could not be found."""</span>
<span class="k">class</span> <span class="nc">Invalid</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span>
<span class="sd">"""A component doesn't satisfy a promise."""</span>
<span class="k">class</span> <span class="nc">IObjectEvent</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""An event related to an object.</span>
<span class="sd"> The object that generated this event is not necessarily the object</span>
<span class="sd"> refered to by location.</span>
<span class="sd"> """</span>
<span class="nb">object</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"The subject of the event."</span><span class="p">)</span>
<span class="nd">@implementer</span><span class="p">(</span><span class="n">IObjectEvent</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">ObjectEvent</span><span class="p">(</span><span class="nb">object</span><span class="p">):</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="nb">object</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">object</span> <span class="o">=</span> <span class="nb">object</span>
<span class="k">class</span> <span class="nc">IComponentLookup</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Component Manager for a Site</span>
<span class="sd"> This object manages the components registered at a particular site. The</span>
<span class="sd"> definition of a site is intentionally vague.</span>
<span class="sd"> """</span>
<span class="n">adapters</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span>
<span class="s">"Adapter Registry to manage all registered adapters."</span><span class="p">)</span>
<span class="n">utilities</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span>
<span class="s">"Adapter Registry to manage all registered utilities."</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">queryAdapter</span><span class="p">(</span><span class="nb">object</span><span class="p">,</span> <span class="n">interface</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Look for a named adapter to an interface for an object</span>
<span class="sd"> If a matching adapter cannot be found, returns the default.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">getAdapter</span><span class="p">(</span><span class="nb">object</span><span class="p">,</span> <span class="n">interface</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Look for a named adapter to an interface for an object</span>
<span class="sd"> If a matching adapter cannot be found, a ComponentLookupError</span>
<span class="sd"> is raised.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">queryMultiAdapter</span><span class="p">(</span><span class="n">objects</span><span class="p">,</span> <span class="n">interface</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Look for a multi-adapter to an interface for multiple objects</span>
<span class="sd"> If a matching adapter cannot be found, returns the default.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">getMultiAdapter</span><span class="p">(</span><span class="n">objects</span><span class="p">,</span> <span class="n">interface</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Look for a multi-adapter to an interface for multiple objects</span>
<span class="sd"> If a matching adapter cannot be found, a ComponentLookupError</span>
<span class="sd"> is raised.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">getAdapters</span><span class="p">(</span><span class="n">objects</span><span class="p">,</span> <span class="n">provided</span><span class="p">):</span>
<span class="sd">"""Look for all matching adapters to a provided interface for objects</span>
<span class="sd"> Return an iterable of name-adapter pairs for adapters that</span>
<span class="sd"> provide the given interface.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">subscribers</span><span class="p">(</span><span class="n">objects</span><span class="p">,</span> <span class="n">provided</span><span class="p">):</span>
<span class="sd">"""Get subscribers</span>
<span class="sd"> Subscribers are returned that provide the provided interface</span>
<span class="sd"> and that depend on and are comuted from the sequence of</span>
<span class="sd"> required objects.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">handle</span><span class="p">(</span><span class="o">*</span><span class="n">objects</span><span class="p">):</span>
<span class="sd">"""Call handlers for the given objects</span>
<span class="sd"> Handlers registered for the given objects are called.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">queryUtility</span><span class="p">(</span><span class="n">interface</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">''</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Look up a utility that provides an interface.</span>
<span class="sd"> If one is not found, returns default.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">getUtilitiesFor</span><span class="p">(</span><span class="n">interface</span><span class="p">):</span>
<span class="sd">"""Look up the registered utilities that provide an interface.</span>
<span class="sd"> Returns an iterable of name-utility pairs.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">getAllUtilitiesRegisteredFor</span><span class="p">(</span><span class="n">interface</span><span class="p">):</span>
<span class="sd">"""Return all registered utilities for an interface</span>
<span class="sd"> This includes overridden utilities.</span>
<span class="sd"> An iterable of utility instances is returned. No names are</span>
<span class="sd"> returned.</span>
<span class="sd"> """</span>
<span class="k">class</span> <span class="nc">IRegistration</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""A registration-information object</span>
<span class="sd"> """</span>
<span class="n">registry</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"The registry having the registration"</span><span class="p">)</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"The registration name"</span><span class="p">)</span>
<span class="n">info</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"""Information about the registration</span>
<span class="s"> This is information deemed useful to people browsing the</span>
<span class="s"> configuration of a system. It could, for example, include</span>
<span class="s"> commentary or information about the source of the configuration.</span>
<span class="s"> """</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">IUtilityRegistration</span><span class="p">(</span><span class="n">IRegistration</span><span class="p">):</span>
<span class="sd">"""Information about the registration of a utility</span>
<span class="sd"> """</span>
<span class="n">factory</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"The factory used to create the utility. Optional."</span><span class="p">)</span>
<span class="n">component</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"The object registered"</span><span class="p">)</span>
<span class="n">provided</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"The interface provided by the component"</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">_IBaseAdapterRegistration</span><span class="p">(</span><span class="n">IRegistration</span><span class="p">):</span>
<span class="sd">"""Information about the registration of an adapter</span>
<span class="sd"> """</span>
<span class="n">factory</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"The factory used to create adapters"</span><span class="p">)</span>
<span class="n">required</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"""The adapted interfaces</span>
<span class="s"> This is a sequence of interfaces adapters by the registered</span>
<span class="s"> factory. The factory will be caled with a sequence of objects, as</span>
<span class="s"> positional arguments, that provide these interfaces.</span>
<span class="s"> """</span><span class="p">)</span>
<span class="n">provided</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"""The interface provided by the adapters.</span>
<span class="s"> This interface is implemented by the factory</span>
<span class="s"> """</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">IAdapterRegistration</span><span class="p">(</span><span class="n">_IBaseAdapterRegistration</span><span class="p">):</span>
<span class="sd">"""Information about the registration of an adapter</span>
<span class="sd"> """</span>
<span class="k">class</span> <span class="nc">ISubscriptionAdapterRegistration</span><span class="p">(</span><span class="n">_IBaseAdapterRegistration</span><span class="p">):</span>
<span class="sd">"""Information about the registration of a subscription adapter</span>
<span class="sd"> """</span>
<span class="k">class</span> <span class="nc">IHandlerRegistration</span><span class="p">(</span><span class="n">IRegistration</span><span class="p">):</span>
<span class="n">handler</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"An object called used to handle an event"</span><span class="p">)</span>
<span class="n">required</span> <span class="o">=</span> <span class="n">Attribute</span><span class="p">(</span><span class="s">"""The handled interfaces</span>
<span class="s"> This is a sequence of interfaces handled by the registered</span>
<span class="s"> handler. The handler will be caled with a sequence of objects, as</span>
<span class="s"> positional arguments, that provide these interfaces.</span>
<span class="s"> """</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">IRegistrationEvent</span><span class="p">(</span><span class="n">IObjectEvent</span><span class="p">):</span>
<span class="sd">"""An event that involves a registration"""</span>
<span class="nd">@implementer</span><span class="p">(</span><span class="n">IRegistrationEvent</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">RegistrationEvent</span><span class="p">(</span><span class="n">ObjectEvent</span><span class="p">):</span>
<span class="sd">"""There has been a change in a registration</span>
<span class="sd"> """</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="k">return</span> <span class="s">"</span><span class="si">%s</span><span class="s"> event:</span><span class="se">\n</span><span class="si">%r</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__class__</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">object</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">IRegistered</span><span class="p">(</span><span class="n">IRegistrationEvent</span><span class="p">):</span>
<span class="sd">"""A component or factory was registered</span>
<span class="sd"> """</span>
<span class="nd">@implementer</span><span class="p">(</span><span class="n">IRegistered</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Registered</span><span class="p">(</span><span class="n">RegistrationEvent</span><span class="p">):</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">IUnregistered</span><span class="p">(</span><span class="n">IRegistrationEvent</span><span class="p">):</span>
<span class="sd">"""A component or factory was unregistered</span>
<span class="sd"> """</span>
<span class="nd">@implementer</span><span class="p">(</span><span class="n">IUnregistered</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Unregistered</span><span class="p">(</span><span class="n">RegistrationEvent</span><span class="p">):</span>
<span class="sd">"""A component or factory was unregistered</span>
<span class="sd"> """</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">IComponentRegistry</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
<span class="sd">"""Register components</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registerUtility</span><span class="p">(</span><span class="n">component</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">provided</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span>
<span class="n">info</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">factory</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Register a utility</span>
<span class="sd"> factory</span>
<span class="sd"> Factory for the component to be registerd.</span>
<span class="sd"> component</span>
<span class="sd"> The registered component</span>
<span class="sd"> provided</span>
<span class="sd"> This is the interface provided by the utility. If the</span>
<span class="sd"> component provides a single interface, then this</span>
<span class="sd"> argument is optional and the component-implemented</span>
<span class="sd"> interface will be used.</span>
<span class="sd"> name</span>
<span class="sd"> The utility name.</span>
<span class="sd"> info</span>
<span class="sd"> An object that can be converted to a string to provide</span>
<span class="sd"> information about the registration.</span>
<span class="sd"> Only one of component and factory can be used.</span>
<span class="sd"> A Registered event is generated with an IUtilityRegistration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">unregisterUtility</span><span class="p">(</span><span class="n">component</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">provided</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span>
<span class="n">factory</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">"""Unregister a utility</span>
<span class="sd"> A boolean is returned indicating whether the registry was</span>
<span class="sd"> changed. If the given component is None and there is no</span>
<span class="sd"> component registered, or if the given component is not</span>
<span class="sd"> None and is not registered, then the function returns</span>
<span class="sd"> False, otherwise it returns True.</span>
<span class="sd"> factory</span>
<span class="sd"> Factory for the component to be unregisterd.</span>
<span class="sd"> component</span>
<span class="sd"> The registered component The given component can be</span>
<span class="sd"> None, in which case any component registered to provide</span>
<span class="sd"> the given provided interface with the given name is</span>
<span class="sd"> unregistered.</span>
<span class="sd"> provided</span>
<span class="sd"> This is the interface provided by the utility. If the</span>
<span class="sd"> component is not None and provides a single interface,</span>
<span class="sd"> then this argument is optional and the</span>
<span class="sd"> component-implemented interface will be used.</span>
<span class="sd"> name</span>
<span class="sd"> The utility name.</span>
<span class="sd"> Only one of component and factory can be used.</span>
<span class="sd"> An UnRegistered event is generated with an IUtilityRegistration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registeredUtilities</span><span class="p">():</span>
<span class="sd">"""Return an iterable of IUtilityRegistration instances.</span>
<span class="sd"> These registrations describe the current utility registrations</span>
<span class="sd"> in the object.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registerAdapter</span><span class="p">(</span><span class="n">factory</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">provided</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span>
<span class="n">info</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Register an adapter factory</span>
<span class="sd"> Parameters:</span>
<span class="sd"> factory</span>
<span class="sd"> The object used to compute the adapter</span>
<span class="sd"> required</span>
<span class="sd"> This is a sequence of specifications for objects to be</span>
<span class="sd"> adapted. If omitted, then the value of the factory's</span>
<span class="sd"> __component_adapts__ attribute will be used. The</span>
<span class="sd"> __component_adapts__ attribute is usually attribute is</span>
<span class="sd"> normally set in class definitions using adapts</span>
<span class="sd"> function, or for callables using the adapter</span>
<span class="sd"> decorator. If the factory doesn't have a</span>
<span class="sd"> __component_adapts__ adapts attribute, then this</span>
<span class="sd"> argument is required.</span>
<span class="sd"> provided</span>
<span class="sd"> This is the interface provided by the adapter and</span>
<span class="sd"> implemented by the factory. If the factory</span>
<span class="sd"> implements a single interface, then this argument is</span>
<span class="sd"> optional and the factory-implemented interface will be</span>
<span class="sd"> used.</span>
<span class="sd"> name</span>
<span class="sd"> The adapter name.</span>
<span class="sd"> info</span>
<span class="sd"> An object that can be converted to a string to provide</span>
<span class="sd"> information about the registration.</span>
<span class="sd"> A Registered event is generated with an IAdapterRegistration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">unregisterAdapter</span><span class="p">(</span><span class="n">factory</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
<span class="n">provided</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Register an adapter factory</span>
<span class="sd"> A boolean is returned indicating whether the registry was</span>
<span class="sd"> changed. If the given component is None and there is no</span>
<span class="sd"> component registered, or if the given component is not</span>
<span class="sd"> None and is not registered, then the function returns</span>
<span class="sd"> False, otherwise it returns True.</span>
<span class="sd"> Parameters:</span>
<span class="sd"> factory</span>
<span class="sd"> This is the object used to compute the adapter. The</span>
<span class="sd"> factory can be None, in which case any factory</span>
<span class="sd"> registered to implement the given provided interface</span>
<span class="sd"> for the given required specifications with the given</span>
<span class="sd"> name is unregistered.</span>
<span class="sd"> required</span>
<span class="sd"> This is a sequence of specifications for objects to be</span>
<span class="sd"> adapted. If the factory is not None and the required</span>
<span class="sd"> arguments is omitted, then the value of the factory's</span>
<span class="sd"> __component_adapts__ attribute will be used. The</span>
<span class="sd"> __component_adapts__ attribute attribute is normally</span>
<span class="sd"> set in class definitions using adapts function, or for</span>
<span class="sd"> callables using the adapter decorator. If the factory</span>
<span class="sd"> is None or doesn't have a __component_adapts__ adapts</span>
<span class="sd"> attribute, then this argument is required.</span>
<span class="sd"> provided</span>
<span class="sd"> This is the interface provided by the adapter and</span>
<span class="sd"> implemented by the factory. If the factory is not</span>
<span class="sd"> None and implements a single interface, then this</span>
<span class="sd"> argument is optional and the factory-implemented</span>
<span class="sd"> interface will be used.</span>
<span class="sd"> name</span>
<span class="sd"> The adapter name.</span>
<span class="sd"> An Unregistered event is generated with an IAdapterRegistration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registeredAdapters</span><span class="p">():</span>
<span class="sd">"""Return an iterable of IAdapterRegistration instances.</span>
<span class="sd"> These registrations describe the current adapter registrations</span>
<span class="sd"> in the object.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registerSubscriptionAdapter</span><span class="p">(</span><span class="n">factory</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">provides</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
<span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">info</span><span class="o">=</span><span class="s">''</span><span class="p">):</span>
<span class="sd">"""Register a subscriber factory</span>
<span class="sd"> Parameters:</span>
<span class="sd"> factory</span>
<span class="sd"> The object used to compute the adapter</span>
<span class="sd"> required</span>
<span class="sd"> This is a sequence of specifications for objects to be</span>
<span class="sd"> adapted. If omitted, then the value of the factory's</span>
<span class="sd"> __component_adapts__ attribute will be used. The</span>
<span class="sd"> __component_adapts__ attribute is usually attribute is</span>
<span class="sd"> normally set in class definitions using adapts</span>
<span class="sd"> function, or for callables using the adapter</span>
<span class="sd"> decorator. If the factory doesn't have a</span>
<span class="sd"> __component_adapts__ adapts attribute, then this</span>
<span class="sd"> argument is required.</span>
<span class="sd"> provided</span>
<span class="sd"> This is the interface provided by the adapter and</span>
<span class="sd"> implemented by the factory. If the factory implements</span>
<span class="sd"> a single interface, then this argument is optional and</span>
<span class="sd"> the factory-implemented interface will be used.</span>
<span class="sd"> name</span>
<span class="sd"> The adapter name.</span>
<span class="sd"> Currently, only the empty string is accepted. Other</span>
<span class="sd"> strings will be accepted in the future when support for</span>
<span class="sd"> named subscribers is added.</span>
<span class="sd"> info</span>
<span class="sd"> An object that can be converted to a string to provide</span>
<span class="sd"> information about the registration.</span>
<span class="sd"> A Registered event is generated with an</span>
<span class="sd"> ISubscriptionAdapterRegistration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">unregisterSubscriptionAdapter</span><span class="p">(</span><span class="n">factory</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
<span class="n">provides</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Unregister a subscriber factory.</span>
<span class="sd"> A boolean is returned indicating whether the registry was</span>
<span class="sd"> changed. If the given component is None and there is no</span>
<span class="sd"> component registered, or if the given component is not</span>
<span class="sd"> None and is not registered, then the function returns</span>
<span class="sd"> False, otherwise it returns True.</span>
<span class="sd"> Parameters:</span>
<span class="sd"> factory</span>
<span class="sd"> This is the object used to compute the adapter. The</span>
<span class="sd"> factory can be None, in which case any factories</span>
<span class="sd"> registered to implement the given provided interface</span>
<span class="sd"> for the given required specifications with the given</span>
<span class="sd"> name are unregistered.</span>
<span class="sd"> required</span>
<span class="sd"> This is a sequence of specifications for objects to be</span>
<span class="sd"> adapted. If the factory is not None and the required</span>
<span class="sd"> arguments is omitted, then the value of the factory's</span>
<span class="sd"> __component_adapts__ attribute will be used. The</span>
<span class="sd"> __component_adapts__ attribute attribute is normally</span>
<span class="sd"> set in class definitions using adapts function, or for</span>
<span class="sd"> callables using the adapter decorator. If the factory</span>
<span class="sd"> is None or doesn't have a __component_adapts__ adapts</span>
<span class="sd"> attribute, then this argument is required.</span>
<span class="sd"> provided</span>
<span class="sd"> This is the interface provided by the adapter and</span>
<span class="sd"> implemented by the factory. If the factory is not</span>
<span class="sd"> None implements a single interface, then this argument</span>
<span class="sd"> is optional and the factory-implemented interface will</span>
<span class="sd"> be used.</span>
<span class="sd"> name</span>
<span class="sd"> The adapter name.</span>
<span class="sd"> Currently, only the empty string is accepted. Other</span>
<span class="sd"> strings will be accepted in the future when support for</span>
<span class="sd"> named subscribers is added.</span>
<span class="sd"> An Unregistered event is generated with an</span>
<span class="sd"> ISubscriptionAdapterRegistration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registeredSubscriptionAdapters</span><span class="p">():</span>
<span class="sd">"""Return an iterable of ISubscriptionAdapterRegistration instances.</span>
<span class="sd"> These registrations describe the current subscription adapter</span>
<span class="sd"> registrations in the object.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registerHandler</span><span class="p">(</span><span class="n">handler</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">,</span> <span class="n">info</span><span class="o">=</span><span class="s">''</span><span class="p">):</span>
<span class="sd">"""Register a handler.</span>
<span class="sd"> A handler is a subscriber that doesn't compute an adapter</span>
<span class="sd"> but performs some function when called.</span>
<span class="sd"> Parameters:</span>
<span class="sd"> handler</span>
<span class="sd"> The object used to handle some event represented by</span>
<span class="sd"> the objects passed to it.</span>
<span class="sd"> required</span>
<span class="sd"> This is a sequence of specifications for objects to be</span>
<span class="sd"> adapted. If omitted, then the value of the factory's</span>
<span class="sd"> __component_adapts__ attribute will be used. The</span>
<span class="sd"> __component_adapts__ attribute is usually attribute is</span>
<span class="sd"> normally set in class definitions using adapts</span>
<span class="sd"> function, or for callables using the adapter</span>
<span class="sd"> decorator. If the factory doesn't have a</span>
<span class="sd"> __component_adapts__ adapts attribute, then this</span>
<span class="sd"> argument is required.</span>
<span class="sd"> name</span>
<span class="sd"> The handler name.</span>
<span class="sd"> Currently, only the empty string is accepted. Other</span>
<span class="sd"> strings will be accepted in the future when support for</span>
<span class="sd"> named handlers is added.</span>
<span class="sd"> info</span>
<span class="sd"> An object that can be converted to a string to provide</span>
<span class="sd"> information about the registration.</span>
<span class="sd"> A Registered event is generated with an IHandlerRegistration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">unregisterHandler</span><span class="p">(</span><span class="n">handler</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">_BLANK</span><span class="p">):</span>
<span class="sd">"""Unregister a handler.</span>
<span class="sd"> A handler is a subscriber that doesn't compute an adapter</span>
<span class="sd"> but performs some function when called.</span>
<span class="sd"> A boolean is returned indicating whether the registry was</span>
<span class="sd"> changed.</span>
<span class="sd"> Parameters:</span>
<span class="sd"> handler</span>
<span class="sd"> This is the object used to handle some event</span>
<span class="sd"> represented by the objects passed to it. The handler</span>
<span class="sd"> can be None, in which case any handlers registered for</span>
<span class="sd"> the given required specifications with the given are</span>
<span class="sd"> unregistered.</span>
<span class="sd"> required</span>
<span class="sd"> This is a sequence of specifications for objects to be</span>
<span class="sd"> adapted. If omitted, then the value of the factory's</span>
<span class="sd"> __component_adapts__ attribute will be used. The</span>
<span class="sd"> __component_adapts__ attribute is usually attribute is</span>
<span class="sd"> normally set in class definitions using adapts</span>
<span class="sd"> function, or for callables using the adapter</span>
<span class="sd"> decorator. If the factory doesn't have a</span>
<span class="sd"> __component_adapts__ adapts attribute, then this</span>
<span class="sd"> argument is required.</span>
<span class="sd"> name</span>
<span class="sd"> The handler name.</span>
<span class="sd"> Currently, only the empty string is accepted. Other</span>
<span class="sd"> strings will be accepted in the future when support for</span>
<span class="sd"> named handlers is added.</span>
<span class="sd"> An Unregistered event is generated with an IHandlerRegistration.</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">registeredHandlers</span><span class="p">():</span>
<span class="sd">"""Return an iterable of IHandlerRegistration instances.</span>
<span class="sd"> These registrations describe the current handler registrations</span>
<span class="sd"> in the object.</span>
<span class="sd"> """</span>
<span class="k">class</span> <span class="nc">IComponents</span><span class="p">(</span><span class="n">IComponentLookup</span><span class="p">,</span> <span class="n">IComponentRegistry</span><span class="p">):</span>
<span class="sd">"""Component registration and access</span>
<span class="sd"> """</span>
<span class="c"># end formerly in zope.component</span>
</pre></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="display: none" role="search">
<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" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../../genindex.html" title="General Index"
>index</a></li>
<li><a href="../../../index.html">zope.interface 4.0.1 documentation</a> »</li>
<li><a href="../../index.html" >Module code</a> »</li>
<li><a href="../interface.html" >zope.interface</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2012, Zope Foundation contributors.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3b2.
</div>
</body>
</html>