Merge pull request #121 from zopefoundation/docs-common-api-doc-split

Reorganize API docs
pull/122/head
Jason Madden 4 years ago committed by GitHub
commit 2a971f4024
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 13
      docs/api/adapters.rst
  2. 28
      docs/api/common.rst
  3. 84
      docs/api/components.rst
  4. 1282
      docs/api/declarations.rst
  5. 14
      docs/api/index.rst
  6. 207
      docs/api/specifications.rst
  7. 3
      docs/index.rst
  8. 46
      src/zope/interface/declarations.py
  9. 5
      src/zope/interface/interface.py
  10. 302
      src/zope/interface/interfaces.py

@ -0,0 +1,13 @@
==================
Adapter Registry
==================
Usage of the adapter registry is documented in :ref:`adapter-registry`.
The adapter registry's API is defined by
:class:`zope.interface.interfaces.IAdapterRegistry`:
.. autointerface:: zope.interface.adapter.IAdapterRegistry
:members:
:member-order: bysource

@ -0,0 +1,28 @@
====================================
Python Standard Library Interfaces
====================================
The ``zope.interface.common`` package provides interfaces for objects
distributed as part of the Python standard library. Importing these
modules has the effect of making the standard library objects
implement the correct interface.
``zope.interface.common.interfaces``
====================================
.. automodule:: zope.interface.common.interfaces
``zope.interface.common.idatetime``
===================================
.. automodule:: zope.interface.common.idatetime
``zope.interface.common.mapping``
=================================
.. automodule:: zope.interface.common.mapping
``zope.interface.common.sequence``
==================================
.. automodule:: zope.interface.common.sequence

@ -0,0 +1,84 @@
======================
Component Registries
======================
The component registry's API is defined by
``zope.interface.interfaces.IComponents``:
.. autointerface:: zope.interface.interfaces.IComponentLookup
:members:
:member-order: bysource
.. autointerface:: zope.interface.interfaces.IComponentRegistry
:members:
:member-order: bysource
.. autointerface:: zope.interface.interfaces.IComponents
:members:
:member-order: bysource
One default implementation of `~zope.interface.interfaces.IComponents` is provided.
.. autoclass:: zope.interface.registry.Components
Events
======
Adding and removing components from the component registry create
registration and unregistration events. Like most things, they are
defined by an interface and a default implementation is provided.
Registration
------------
.. autointerface:: zope.interface.interfaces.IObjectEvent
.. autointerface:: zope.interface.interfaces.IRegistrationEvent
.. autointerface:: zope.interface.interfaces.IRegistered
.. autoclass:: zope.interface.interfaces.Registered
.. autointerface:: zope.interface.interfaces.IUnregistered
.. autoclass:: zope.interface.interfaces.Unregistered
Details
-------
These are all types of ``IObjectEvent``, meaning they have an object
that provides specific details about the event. Component registries
create detail objects for four types of components they manage.
All four share a common base interface.
.. autointerface:: zope.interface.interfaces.IRegistration
* Utilties
.. autointerface:: zope.interface.interfaces.IUtilityRegistration
.. autoclass:: zope.interface.registry.UtilityRegistration
* Handlers
.. autointerface:: zope.interface.interfaces.IHandlerRegistration
.. autoclass:: zope.interface.registry.HandlerRegistration
* Adapters
For ease of implementation, a shared base class is used for these
events. It should not be referenced by clients, but it is documented
to show the common attributes.
.. autointerface:: zope.interface.interfaces._IBaseAdapterRegistration
.. autointerface:: zope.interface.interfaces.IAdapterRegistration
.. autoclass:: zope.interface.registry.AdapterRegistration
.. autointerface:: zope.interface.interfaces.ISubscriptionAdapterRegistration
.. autoclass:: zope.interface.registry.SubscriptionRegistration
Exceptions
==========
.. autoclass:: zope.interface.interfaces.ComponentLookupError
.. autoclass:: zope.interface.interfaces.Invalid

@ -1,435 +1,68 @@
=========================================
: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']
==================================================
Declaring and Checking The Interfaces of Objects
==================================================
Exmples for :meth:`Declaration.__add__`:
Declaring what interfaces an object implements or provides, and later
being able to check those, is an important part of this package.
Declaring interfaces, in particular, can be done both statically at
object definition time and dynamically later on.
.. doctest::
The functionality that allows declaring and checking interfaces is
provided directly in the ``zope.interface`` module. It is described by
the interface ``zope.interface.interfaces.IInterfaceDeclaration``. We
will first look at that interface, and then we will look more
carefully at each object it documents, including providing examples.
>>> 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']
.. autointerface:: zope.interface.interfaces.IInterfaceDeclaration
:func:`zope.interface.declarations.implementedBy`
=================================================
.. currentmodule:: zope.interface.declarations
API
---
Declaring The Interfaces of Objects
===================================
.. autofunction:: zope.interface.declarations.implementedByFallback
implementer
-----------
Usage
-----
.. autoclass:: implementer
Consider the following example:
.. doctest::
implementer_only
----------------
>>> 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']
.. autoclass:: implementer_only
Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
whatever interfaces instances of ``A`` and ``B`` implement.
Another example:
implements
----------
.. doctest::
(The `implementer` decorator is preferred to this.)
>>> 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']
.. autofunction:: implements
Really, any object should be able to receive a successful answer, even
an instance:
.. doctest::
implementsOnly
--------------
>>> 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.
(The `implementer_only` decorator is preferred to this.)
.. autofunction:: implementsOnly
:func:`zope.interface.declarations.classImplementsOnly`
=======================================================
API
---
classImplementsOnly
-------------------
.. autofunction:: zope.interface.declarations.classImplementsOnly
.. autofunction:: classImplementsOnly
Usage
-----
Consider the following example:
.. doctest::
>>> from zope.interface import implementedBy
>>> from zope.interface import implements
>>> from zope.interface import classImplementsOnly
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
@ -453,194 +86,57 @@ Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
whatever interfaces instances of ``A`` and ``B`` implement.
:func:`zope.interface.declarations.classImplements`
===================================================
classImplements
---------------
API
---
.. autofunction:: zope.interface.declarations.classImplements
Usage
-----
.. autofunction:: classImplements
Consider the following example:
.. doctest::
>>> from zope.interface import Interface
>>> from zope.interface import classImplements
>>> 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
...
>>> 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']
:func:`zope.interface.declarations.directlyProvides`
====================================================
Instances of ``C`` provide ``I1``, ``I2``, ``I5``, and whatever
interfaces instances of ``A`` and ``B`` provide.
API
---
.. autofunction:: zope.interface.declarations.directlyProvides
directlyProvides
----------------
.. autofunction:: directlyProvides
Usage
-----
Consider the following example:
.. doctest::
>>> from zope.interface import Interface
>>> from zope.interface import providedBy
>>> from zope.interface import directlyProvides
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
@ -682,6 +178,7 @@ subtract the unwanted interfaces. For example:
.. doctest::
>>> from zope.interface import directlyProvidedBy
>>> directlyProvides(ob, directlyProvidedBy(ob)-I2)
>>> int(I1 in providedBy(ob))
1
@ -699,6 +196,7 @@ include additional interfaces. For example:
>>> int(I2 in providedBy(ob))
0
>>> from zope.interface import directlyProvidedBy
>>> directlyProvides(ob, directlyProvidedBy(ob), I2)
adds ``I2`` to the interfaces directly provided by ``ob``:
@ -714,23 +212,18 @@ don't support descriptors.
We can do away with this check when we get rid of the old EC
:func:`zope.interface.declarations.alsoProvides`
================================================
alsoProvides
------------
API
---
.. autofunction:: alsoProvides
.. autofunction:: zope.interface.declarations.alsoProvides
Usage
-----
Consider the following example:
.. doctest::
>>> from zope.interface import Interface
>>> from zope.interface import alsoProvides
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
@ -782,154 +275,468 @@ instances have been declared for instances of ``C``. Notice that the
``alsoProvides`` just extends the provided interfaces.
:func:`zope.interface.declarations.noLongerProvides`
====================================================
noLongerProvides
----------------
.. autofunction:: noLongerProvides
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::
>>> from zope.interface import noLongerProvides
>>> 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.
classProvides
-------------
.. autofunction:: classProvides
For example:
.. doctest::
>>> from zope.interface import Interface
>>> from zope.interface.declarations import implementer
>>> from zope.interface import classProvides
>>> 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']
API
---
provider
--------
.. autofunction:: zope.interface.declarations.noLongerProvides
.. autoclass:: provider
Usage
moduleProvides
--------------
.. autofunction:: moduleProvides
named
-----
Consider the following two interfaces:
.. autoclass:: zope.interface.declarations.named
For example:
.. doctest::
>>> from zope.interface.declarations import named
>>> @named('foo')
... class Foo(object):
... pass
>>> Foo.__component_name__
'foo'
When registering an adapter or utility component, the registry looks for the
``__component_name__`` attribute and uses it, if no name was explicitly
provided.
Querying The Interfaces Of Objects
==================================
All of these functions return an
`~zope.interface.interfaces.IDeclaration`.
You'll notice that an ``IDeclaration`` is a type of
`~zope.interface.interfaces.ISpecification`, as is
``zope.interface.Interface``, so they share some common behaviour.
.. autointerface:: zope.interface.interfaces.IDeclaration
:members:
:member-order: bysource
implementedBy
-------------
.. autofunction:: implementedByFallback
Consider the following example:
.. doctest::
>>> from zope.interface import Interface
>>> from zope.interface import implements
>>> from zope.interface import classImplementsOnly
>>> from zope.interface import implementedBy
>>> 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.
providedBy
----------
.. autofunction:: providedBy
directlyProvidedBy
------------------
.. autofunction:: directlyProvidedBy
Classes
=======
Declarations
------------
Declaration objects implement the API defined by
:class:`~zope.interface.interfaces.IDeclaration`.
.. autoclass:: Declaration
Exmples for :meth:`Declaration.__contains__`:
.. doctest::
>>> from zope.interface.declarations import Declaration
>>> 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(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)
[]
``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:
Exmples for :meth:`Declaration.__sub__`:
.. doctest::
>>> noLongerProvides(c, I2)
>>> I2.providedBy(c)
False
>>> 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']
Removing an interface that is provided through the class is not possible:
Exmples for :meth:`Declaration.__add__`:
.. doctest::
>>> noLongerProvides(c, I1)
Traceback (most recent call last):
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
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
>>> 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']
Usage
-----
For example:
ProvidesClass
-------------
.. doctest::
.. autoclass:: ProvidesClass
>>> 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:
Descriptor semantics (via ``Provides.__get__``):
.. doctest::
>>> from zope.interface import Interface
>>> class IFoo(Interface): pass
...
>>> class IFooFactory(Interface): pass
...
>>> @implementer(IFoo)
... class C(object):
>>> class C(object):
... pass
>>> directlyProvides(C, IFooFactory)
>>> [i.getName() for i in C.__providedBy__]
>>> from zope.interface.declarations import ProvidesClass
>>> C.__provides__ = ProvidesClass(C, IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']
>>> [i.getName() for i in C().__providedBy__]
['IFoo']
:class:`zope.interface.declarations.provider`
=============================================
API
---
>>> getattr(C(), '__provides__', 0)
0
.. autoclass:: zope.interface.declarations.provider
:members:
:member-order: bysource
Implementation Details
======================
:func:`zope.interface.declarations.moduleProvides`
==================================================
The following section discusses some implementation details and
demonstrates their use. You'll notice that they are all demonstrated
using the previously-defined functions.
API
---
Provides
--------
.. autofunction:: zope.interface.declarations.moduleProvides
.. autofunction:: Provides
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::
:func:`zope.interface.declarations.ObjectSpecification`
=======================================================
>>> import gc
>>> def collect():
... for i in range(4):
... gc.collect()
>>> collect()
>>> from zope.interface import directlyProvides
>>> 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
API
---
.. autofunction:: zope.interface.declarations.ObjectSpecification
ObjectSpecification
-------------------
.. autofunction:: ObjectSpecification
Usage
-----
For example:
.. doctest::
>>> from zope.interface import Interface
>>> from zope.interface import implementsOnly
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
@ -987,28 +794,10 @@ For example:
>>> int(providedBy(c).extends(I5))
1
ObjectSpecificationDescriptor
-----------------------------
: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
-----
.. autoclass:: ObjectSpecificationDescriptor
For example:
@ -1029,104 +818,3 @@ For example:
Get an ObjectSpecification bound to either an instance or a class,
depending on how we were accessed.
:class:`zope.interface.declarations.named`
==========================================
API
---
.. autoclass:: zope.interface.declarations.named
:members:
:member-order: bysource
Usage
-----
For example:
.. doctest::
>>> from zope.interface.declarations import named
>>> @named('foo')
... class Foo(object):
... pass
>>> Foo.__component_name__
'foo'
When registering an adapter or utility component, the registry looks for the
``__component_name__`` attribute and uses it, if no name was explicitly
provided.
:class:`zope.interface.adapter.AdapterRegistry`
===============================================
API
---
The adapter registry's API is defined by
:class:`zope.interface.interfaces.IAdapterRegistry`:
.. autointerface:: zope.interface.adapter.IAdapterRegistry
:members:
:member-order: bysource
Usage
-----
See :ref:`adapter-registry`.
``zope.interface.registry.Components``
======================================
API
---
The component registry's API is defined by
``zope.interface.interfaces.IComponents``:
.. autointerface:: zope.interface.interfaces.IComponents
:members:
:member-order: bysource
.. autointerface:: zope.interface.interfaces.IComponentLookup
:members:
:member-order: bysource
.. autointerface:: zope.interface.interfaces.IComponentRegistry
:members:
:member-order: bysource
Python Standard Library Interfaces
==================================
The ``zope.interface.common`` package provides interfaces for objects
distributed as part of the Python standard library. Importing these
modules has the effect of making the standard library objects
implement the correct interface.
``zope.interface.common.interfaces``
------------------------------------
.. automodule:: zope.interface.common.interfaces
``zope.interface.common.idatetime``
-----------------------------------
.. automodule:: zope.interface.common.idatetime
``zope.interface.common.mapping``
---------------------------------
.. automodule:: zope.interface.common.mapping
``zope.interface.common.sequence``
----------------------------------
.. automodule:: zope.interface.common.sequence

@ -0,0 +1,14 @@
===============
API Reference
===============
Contents:
.. toctree::
:maxdepth: 2
specifications
declarations
adapters
components
common

@ -0,0 +1,207 @@
==========================
Interface Specifications
==========================
.. currentmodule:: zope.interface.interfaces
This document discusses the actual interface objects themselves. We
begin with a basic concept of specifying an object's behaviour (with
an `ISpecification`), and then we describe the way we write such a
specification (`IInterface`). Combinations of specifications (e.g., an
object that provides multiple interfaces) are covered by
`IDeclaration`.
Specification
=============
Specification objects implement the API defined by
:class:`ISpecification`:
.. autointerface:: ISpecification
:members:
:member-order: bysource
.. autoclass:: zope.interface.interface.Specification
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