1#@!#!123s

: / usr / share / doc / python-zope-interface-4.0.5 / docs /
Filename : api.rst
back
:mod:`zope.interface` API Documentation
=======================================


:class:`zope.interface.interface.Specification`
-----------------------------------------------

API
+++

Specification objects implement the API defined by
:class:`zope.interface.interfaces.ISpecification`:

.. autointerface:: zope.interface.interfaces.ISpecification
   :members:
   :member-order: bysource


Usage
+++++

For example:

.. doctest::

   >>> from zope.interface.interface import Specification
   >>> from zope.interface import Interface
   >>> class I1(Interface):
   ...     pass
   >>> class I2(I1):
   ...     pass
   >>> class I3(I2):
   ...     pass
   >>> [i.__name__ for i in I1.__bases__]
   ['Interface']
   >>> [i.__name__ for i in I2.__bases__]
   ['I1']
   >>> I3.extends(I1)
   True
   >>> I2.__bases__ = (Interface, )
   >>> [i.__name__ for i in I2.__bases__]
   ['Interface']
   >>> I3.extends(I1)
   False

Exmples for :meth:`Specification.providedBy`:

.. doctest::

   >>> from zope.interface import *
   >>> class I1(Interface):
   ...     pass
   >>> class C(object):
   ...     implements(I1)
   >>> c = C()
   >>> class X(object):
   ...     pass
   >>> x = X()
   >>> I1.providedBy(x)
   False
   >>> I1.providedBy(C)
   False
   >>> I1.providedBy(c)
   True
   >>> directlyProvides(x, I1)
   >>> I1.providedBy(x)
   True
   >>> directlyProvides(C, I1)
   >>> I1.providedBy(C)
   True

Examples for :meth:`Specification.isOrExtends`:

.. doctest::

   >>> from zope.interface import Interface
   >>> from zope.interface.declarations import Declaration
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> spec = Declaration()
   >>> int(spec.extends(Interface))
   1
   >>> spec = Declaration(I2)
   >>> int(spec.extends(Interface))
   1
   >>> int(spec.extends(I1))
   1
   >>> int(spec.extends(I2))
   1
   >>> int(spec.extends(I3))
   0
   >>> int(spec.extends(I4))
   0

Examples for :meth:`Specification.interfaces`:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> spec = Specification((I2, I3))
   >>> spec = Specification((I4, spec))
   >>> i = spec.interfaces()
   >>> [x.getName() for x in i]
   ['I4', 'I2', 'I3']
   >>> list(i)
   []

Exmples for :meth:`Specification.extends`:

.. doctest::

   >>> from zope.interface import Interface
   >>> from zope.interface.declarations import Declaration
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> spec = Declaration()
   >>> int(spec.extends(Interface))
   1
   >>> spec = Declaration(I2)
   >>> int(spec.extends(Interface))
   1
   >>> int(spec.extends(I1))
   1
   >>> int(spec.extends(I2))
   1
   >>> int(spec.extends(I3))
   0
   >>> int(spec.extends(I4))
   0
   >>> I2.extends(I2)
   False
   >>> I2.extends(I2, False)
   True
   >>> I2.extends(I2, strict=False)
   True


:class:`zope.interface.interface.InterfaceClass`
------------------------------------------------

API
+++

Specification objects implement the API defined by
:class:`zope.interface.interfaces.IInterface`:

.. autointerface:: zope.interface.interfaces.IInterface
   :members:
   :member-order: bysource


Usage
+++++

Exmples for :meth:`InterfaceClass.extends`:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>>
   >>> i = I1.interfaces()
   >>> [x.getName() for x in i]
   ['I1']
   >>> list(i)
   []


:class:`zope.interface.declarations.Declaration`
------------------------------------------------

API
+++

Specification objects implement the API defined by
:class:`zope.interface.interfaces.IDeclaration`:

.. autointerface:: zope.interface.interfaces.IDeclaration
   :members:
   :member-order: bysource


Usage
+++++

Exmples for :meth:`Declaration.__contains__`:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> spec = Declaration(I2, I3)
   >>> spec = Declaration(I4, spec)
   >>> int(I1 in spec)
   0
   >>> int(I2 in spec)
   1
   >>> int(I3 in spec)
   1
   >>> int(I4 in spec)
   1

Exmples for :meth:`Declaration.__iter__`:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> spec = Declaration(I2, I3)
   >>> spec = Declaration(I4, spec)
   >>> i = iter(spec)
   >>> [x.getName() for x in i]
   ['I4', 'I2', 'I3']
   >>> list(i)
   []

Exmples for :meth:`Declaration.flattened`:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> spec = Declaration(I2, I3)
   >>> spec = Declaration(I4, spec)
   >>> i = spec.flattened()
   >>> [x.getName() for x in i]
   ['I4', 'I2', 'I1', 'I3', 'Interface']
   >>> list(i)
   []

Exmples for :meth:`Declaration.__sub__`:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> spec = Declaration()
   >>> [iface.getName() for iface in spec]
   []
   >>> spec -= I1
   >>> [iface.getName() for iface in spec]
   []
   >>> spec -= Declaration(I1, I2)
   >>> [iface.getName() for iface in spec]
   []
   >>> spec = Declaration(I2, I4)
   >>> [iface.getName() for iface in spec]
   ['I2', 'I4']
   >>> [iface.getName() for iface in spec - I4]
   ['I2']
   >>> [iface.getName() for iface in spec - I1]
   ['I4']
   >>> [iface.getName() for iface
   ...  in spec - Declaration(I3, I4)]
   ['I2']

Exmples for :meth:`Declaration.__add__`:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> spec = Declaration()
   >>> [iface.getName() for iface in spec]
   []
   >>> [iface.getName() for iface in spec+I1]
   ['I1']
   >>> [iface.getName() for iface in I1+spec]
   ['I1']
   >>> spec2 = spec
   >>> spec += I1
   >>> [iface.getName() for iface in spec]
   ['I1']
   >>> [iface.getName() for iface in spec2]
   []
   >>> spec2 += Declaration(I3, I4)
   >>> [iface.getName() for iface in spec2]
   ['I3', 'I4']
   >>> [iface.getName() for iface in spec+spec2]
   ['I1', 'I3', 'I4']
   >>> [iface.getName() for iface in spec2+spec]
   ['I3', 'I4', 'I1']


:func:`zope.interface.declarations.implementedBy`
-------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.implementedByFallback


Usage
+++++

Consider the following example:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(Interface): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(Interface): pass
   ...
   >>> class A(object):
   ...   implements(I3)
   >>> class B(object):
   ...   implements(I4)
   >>> class C(A, B):
   ...   pass
   >>> classImplementsOnly(C, I1, I2)
   >>> [i.getName() for i in implementedBy(C)]
   ['I1', 'I2']
   
Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
whatever interfaces instances of ``A`` and ``B`` implement.

Another example:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(I1): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(I3): pass
   ...
   >>> class C1(object):
   ...   implements(I2)
   >>> class C2(C1):
   ...   implements(I3)
   >>> [i.getName() for i in implementedBy(C2)]
   ['I3', 'I2']

Really, any object should be able to receive a successful answer, even
an instance:

.. doctest::

   >>> class Callable(object):
   ...     def __call__(self):
   ...         return self
   >>> implementedBy(Callable())
   <implementedBy __builtin__.?>

Note that the name of the spec ends with a '?', because the `Callable`
instance does not have a `__name__` attribute.

This also manages storage of implementation specifications


:func:`zope.interface.declarations.classImplementsOnly`
-------------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.classImplementsOnly


Usage
+++++

Consider the following example:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(Interface): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(Interface): pass
   ...
   >>> class A(object):
   ...   implements(I3)
   >>> class B(object):
   ...   implements(I4)
   >>> class C(A, B):
   ...   pass
   >>> classImplementsOnly(C, I1, I2)
   >>> [i.getName() for i in implementedBy(C)]
   ['I1', 'I2']
   
Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
whatever interfaces instances of ``A`` and ``B`` implement.


:func:`zope.interface.declarations.classImplements`
---------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.classImplements


Usage
+++++

Consider the following example:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(Interface): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I4(Interface): pass
   ...
   >>> class I5(Interface): pass
   ...
   >>> class A(object):
   ...   implements(I3)
   >>> class B(object):
   ...   implements(I4)
   >>> class C(A, B):
   ...   pass
   >>> classImplements(C, I1, I2)
   >>> [i.getName() for i in implementedBy(C)]
   ['I1', 'I2', 'I3', 'I4']
   >>> classImplements(C, I5)
   >>> [i.getName() for i in implementedBy(C)]
   ['I1', 'I2', 'I5', 'I3', 'I4']

Instances of ``C`` provide ``I1``, ``I2``, ``I5``, and whatever
interfaces instances of ``A`` and ``B`` provide.


:class:`zope.interface.declarations.implementer`
------------------------------------------------

API
+++

.. autoclass:: zope.interface.declarations.implementer
   :members:
   :member-order: bysource


:class:`zope.interface.declarations.implementer_only`
-----------------------------------------------------

API
+++

.. autoclass:: zope.interface.declarations.implementer_only
   :members:
   :member-order: bysource


:func:`zope.interface.declarations.implements`
----------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.implements



:func:`zope.interface.declarations.implementsOnly`
--------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.implementsOnly



:class:`zope.interface.declarations.ProvidesClass`
--------------------------------------------------

API
+++

.. autoclass:: zope.interface.declarations.ProvidesClass
   :members:
   :member-order: bysource


Usage
+++++

Descriptor semantics (via ``Provides.__get__``):

.. doctest::

   >>> from zope.interface import Interface
   >>> class IFooFactory(Interface): pass
   ...
   >>> class C(object):
   ...   pass
   >>> from zope.interface.declarations import ProvidesClass
   >>> C.__provides__ = ProvidesClass(C, IFooFactory)
   >>> [i.getName() for i in C.__provides__]
   ['IFooFactory']
   >>> getattr(C(), '__provides__', 0)
   0



:func:`zope.interface.declarations.Provides`
--------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.Provides


Usage
+++++

In the examples below, we are going to make assertions about
the size of the weakvalue dictionary.  For the assertions to be
meaningful, we need to force garbage collection to make sure garbage
objects are, indeed, removed from the system. Depending on how Python
is run, we may need to make multiple calls to be sure.  We provide a
collect function to help with this:

.. doctest::

   >>> import gc
   >>> def collect():
   ...     for i in range(4):
   ...         gc.collect()
   >>> collect()
   >>> from zope.interface.declarations import InstanceDeclarations
   >>> before = len(InstanceDeclarations)
   >>> class C(object):
   ...    pass
   >>> from zope.interface import Interface
   >>> class I(Interface):
   ...    pass
   >>> c1 = C()
   >>> c2 = C()
   >>> len(InstanceDeclarations) == before
   True
   >>> directlyProvides(c1, I)
   >>> len(InstanceDeclarations) == before + 1
   True
   >>> directlyProvides(c2, I)
   >>> len(InstanceDeclarations) == before + 1
   True
   >>> del c1
   >>> collect()
   >>> len(InstanceDeclarations) == before + 1
   True
   >>> del c2
   >>> collect()
   >>> len(InstanceDeclarations) == before
   True


:func:`zope.interface.declarations.directlyProvides`
----------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.directlyProvides


Usage
+++++

Consider the following example:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(Interface): pass
   ...
   >>> class IA1(Interface): pass
   ...
   >>> class IA2(Interface): pass
   ...
   >>> class IB(Interface): pass
   ...
   >>> class IC(Interface): pass
   ...
   >>> class A(object):
   ...     implements(IA1, IA2)
   >>> class B(object):
   ...     implements(IB)
   >>> class C(A, B):
   ...    implements(IC)
   >>> ob = C()
   >>> directlyProvides(ob, I1, I2)
   >>> int(I1 in providedBy(ob))
   1
   >>> int(I2 in providedBy(ob))
   1
   >>> int(IA1 in providedBy(ob))
   1
   >>> int(IA2 in providedBy(ob))
   1
   >>> int(IB in providedBy(ob))
   1
   >>> int(IC in providedBy(ob))
   1

The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
instances have been declared for instances of ``C``.

To remove directly provided interfaces, use ``directlyProvidedBy`` and
subtract the unwanted interfaces. For example:

.. doctest::

   >>> directlyProvides(ob, directlyProvidedBy(ob)-I2)
   >>> int(I1 in providedBy(ob))
   1
   >>> int(I2 in providedBy(ob))
   0

removes I2 from the interfaces directly provided by ``ob``. The object,
``ob`` no longer directly provides ``I2``, although it might still
provide ``I2`` if it's class implements ``I2``.

To add directly provided interfaces, use ``directlyProvidedBy`` and
include additional interfaces.  For example:

.. doctest::

   >>> int(I2 in providedBy(ob))
   0
   >>> directlyProvides(ob, directlyProvidedBy(ob), I2)
   
adds ``I2`` to the interfaces directly provided by ob:

.. doctest::

   >>> int(I2 in providedBy(ob))
   1

We need to avoid setting this attribute on meta classes that
don't support descriptors.

We can do away with this check when we get rid of the old EC


:func:`zope.interface.declarations.alsoProvides`
------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.alsoProvides


Usage
+++++

Consider the following example:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(Interface): pass
   ...
   >>> class IA1(Interface): pass
   ...
   >>> class IA2(Interface): pass
   ...
   >>> class IB(Interface): pass
   ...
   >>> class IC(Interface): pass
   ...
   >>> class A(object):
   ...     implements(IA1, IA2)
   >>> class B(object):
   ...     implements(IB)
   >>> class C(A, B):
   ...    implements(IC)
   >>> ob = C()
   >>> directlyProvides(ob, I1)
   >>> int(I1 in providedBy(ob))
   1
   >>> int(I2 in providedBy(ob))
   0
   >>> int(IA1 in providedBy(ob))
   1
   >>> int(IA2 in providedBy(ob))
   1
   >>> int(IB in providedBy(ob))
   1
   >>> int(IC in providedBy(ob))
   1
   >>> alsoProvides(ob, I2)
   >>> int(I1 in providedBy(ob))
   1
   >>> int(I2 in providedBy(ob))
   1
   >>> int(IA1 in providedBy(ob))
   1
   >>> int(IA2 in providedBy(ob))
   1
   >>> int(IB in providedBy(ob))
   1
   >>> int(IC in providedBy(ob))
   1

The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
instances have been declared for instances of ``C``. Notice that the
alsoProvides just extends the provided interfaces.


:func:`zope.interface.declarations.noLongerProvides`
----------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.noLongerProvides


Usage
+++++

Consider the following two interfaces:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(Interface): pass
   ...

``I1`` is provided through the class, ``I2`` is directly provided
by the object:

.. doctest::

   >>> class C(object):
   ...    implements(I1)
   >>> c = C()
   >>> alsoProvides(c, I2)
   >>> I2.providedBy(c)
   True

Remove I2 from c again:

.. doctest::

   >>> noLongerProvides(c, I2)
   >>> I2.providedBy(c)
   False

Removing an interface that is provided through the class is not possible:

.. doctest::

   >>> noLongerProvides(c, I1)
   Traceback (most recent call last):
   ...
   ValueError: Can only remove directly provided interfaces.


:func:`zope.interface.declarations.directlyProvidedBy`
------------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.directlyProvidedBy


:func:`zope.interface.declarations.classProvides`
-------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.classProvides


Usage
+++++

For example:

.. doctest::

   >>> from zope.interface import Interface
   >>> from zope.interface.declarations import implementer
   >>> class IFooFactory(Interface):
   ...     pass
   >>> class IFoo(Interface):
   ...     pass
   >>> @implementer(IFoo)
   ... class C(object):
   ...     classProvides(IFooFactory)
   >>> [i.getName() for i in C.__provides__]
   ['IFooFactory']
   >>> [i.getName() for i in C().__provides__]
   ['IFoo']

Which is equivalent to:

.. doctest::

   >>> from zope.interface import Interface
   >>> class IFoo(Interface): pass
   ...
   >>> class IFooFactory(Interface): pass
   ...
   >>> @implementer(IFoo)
   ... class C(object):
   ...   pass
   >>> directlyProvides(C, IFooFactory)
   >>> [i.getName() for i in C.__providedBy__]
   ['IFooFactory']
   >>> [i.getName() for i in C().__providedBy__]
   ['IFoo']


:class:`zope.interface.declarations.provider`
---------------------------------------------

API
+++

.. autoclass:: zope.interface.declarations.provider
   :members:
   :member-order: bysource


:func:`zope.interface.declarations.moduleProvides`
--------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.moduleProvides



:func:`zope.interface.declarations.ObjectSpecification`
-------------------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.ObjectSpecification


Usage
+++++

For example:

.. doctest::

   >>> from zope.interface import Interface
   >>> class I1(Interface): pass
   ...
   >>> class I2(Interface): pass
   ...
   >>> class I3(Interface): pass
   ...
   >>> class I31(I3): pass
   ...
   >>> class I4(Interface): pass
   ...
   >>> class I5(Interface): pass
   ...
   >>> class A(object):
   ...     implements(I1)
   >>> class B(object): __implemented__ = I2
   ...
   >>> class C(A, B):
   ...     implements(I31)
   >>> c = C()
   >>> directlyProvides(c, I4)
   >>> [i.getName() for i in providedBy(c)]
   ['I4', 'I31', 'I1', 'I2']
   >>> [i.getName() for i in providedBy(c).flattened()]
   ['I4', 'I31', 'I3', 'I1', 'I2', 'Interface']
   >>> int(I1 in providedBy(c))
   1
   >>> int(I3 in providedBy(c))
   0
   >>> int(providedBy(c).extends(I3))
   1
   >>> int(providedBy(c).extends(I31))
   1
   >>> int(providedBy(c).extends(I5))
   0
   >>> class COnly(A, B):
   ...     implementsOnly(I31)
   >>> class D(COnly):
   ...     implements(I5)
   >>> c = D()
   >>> directlyProvides(c, I4)
   >>> [i.getName() for i in providedBy(c)]
   ['I4', 'I5', 'I31']
   >>> [i.getName() for i in providedBy(c).flattened()]
   ['I4', 'I5', 'I31', 'I3', 'Interface']
   >>> int(I1 in providedBy(c))
   0
   >>> int(I3 in providedBy(c))
   0
   >>> int(providedBy(c).extends(I3))
   1
   >>> int(providedBy(c).extends(I1))
   0
   >>> int(providedBy(c).extends(I31))
   1
   >>> int(providedBy(c).extends(I5))
   1


:func:`zope.interface.declarations.providedBy`
----------------------------------------------

API
+++

.. autofunction:: zope.interface.declarations.providedBy


:class:`zope.interface.declarations.ObjectSpecificationDescriptor`
------------------------------------------------------------------

API
+++

.. autoclass:: zope.interface.declarations.ObjectSpecificationDescriptor
   :members:
   :member-order: bysource

Usage
+++++

For example:

.. doctest::

   >>> from zope.interface import Interface
   >>> class IFoo(Interface): pass
   ...
   >>> class IFooFactory(Interface): pass
   ...
   >>> @implementer(IFoo)
   ... class C(object):
   ...   classProvides(IFooFactory)
   >>> [i.getName() for i in C.__providedBy__]
   ['IFooFactory']
   >>> [i.getName() for i in C().__providedBy__]
   ['IFoo']

Get an ObjectSpecification bound to either an instance or a class,
depending on how we were accessed.
Name	Size	Last Modified	Owner	Permissions
Makefile	5.461 KB	February 28 2013 6:51:06	root	0644
README.rst	24.32 KB	February 28 2013 6:51:06	root	0644
README.ru.rst	33.185 KB	February 28 2013 6:51:06	root	0644
adapter.rst	14.796 KB	February 28 2013 6:51:06	root	0644
adapter.ru.rst	20.673 KB	February 28 2013 6:51:06	root	0644
api.rst	21.021 KB	February 28 2013 6:51:06	root	0644
conf.py	7.985 KB	February 28 2013 6:51:06	root	0644
foodforthought.rst	1.701 KB	February 28 2013 6:51:06	root	0644
hacking.rst	10.583 KB	February 28 2013 6:51:06	root	0644
human.rst	6.275 KB	February 28 2013 6:51:06	root	0644
human.ru.rst	10.431 KB	February 28 2013 6:51:06	root	0644
index.rst	0.608 KB	February 28 2013 6:51:06	root	0644
make.bat	4.99 KB	February 28 2013 6:51:06	root	0644
verify.rst	3.52 KB	February 28 2013 6:51:06	root	0644
2017 © D7net \| D704T team