LADI
/
py-zope.interface
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add more cross refs to documentation and fix a couple sphinx warnings about duplicates in the index.

This commit is contained in:
Jason Madden 2020-04-03 05:53:27 -05:00
parent 6c2f71487e
commit 139bab56a7
No known key found for this signature in database
GPG Key ID: 349F84431A08B99E
3 changed files with 115 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/README.rst
View File

@ -299,6 +299,9 @@ Note that class decorators using the ``@implementer(IFoo)`` syntax are only
supported in Python 2.6 and later.
.. autofunction:: implementer
:noindex:
.. XXX: Duplicate description.
Declaring provided interfaces
-----------------------------
@ -416,6 +419,9 @@ We can find out what interfaces are directly provided by an object:
[]
.. autofunction:: provider
:noindex:
.. XXX: Duplicate description.
Inherited declarations
----------------------
@ -472,6 +478,7 @@ be used for this purpose:
[<InterfaceClass builtins.IFoo>]
.. autofunction:: classImplements
:noindex:
We can use ``classImplementsOnly`` to exclude inherited interfaces:
@ -485,7 +492,9 @@ We can use ``classImplementsOnly`` to exclude inherited interfaces:
[<InterfaceClass builtins.ISpecial>]
.. autofunction:: classImplementsOnly
:noindex:
.. XXX: Duplicate description.
Declaration Objects
-------------------

10
docs/conf.py
View File

@ -264,6 +264,12 @@ texinfo_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/': None}
autodoc_default_flags = ['members', 'show-inheritance']
autoclass_content = 'both'
# Sphinx 1.8+ prefers this to `autodoc_default_flags`. It's documented that
# either True or None mean the same thing as just setting the flag, but
# only None works in 1.8 (True works in 2.0)
autodoc_default_options = {
'members': None,
'show-inheritance': None,
}
autodoc_member_order = 'bysource'
autoclass_content = 'both'

140
src/zope/interface/interfaces.py
View File

@ -451,46 +451,54 @@ class IDeclaration(ISpecification):
"""
class IInterfaceDeclaration(Interface):
"""Declare and check the interfaces of objects
"""
Declare and check the interfaces of objects.
The functions defined in this interface are used to declare the
interfaces that objects provide and to query the interfaces that have
been declared.
interfaces that objects provide and to query the interfaces that
have been declared.
Interfaces can be declared for objects in two ways:
- Interfaces are declared for instances of the object's class
- Interfaces are declared for instances of the object's class
- Interfaces are declared for the object directly.
- Interfaces are declared for the object directly.
The interfaces declared for an object are, therefore, the union of
interfaces declared for the object directly and the interfaces
declared for instances of the object's class.
Note that we say that a class implements the interfaces provided
by it's instances. An instance can also provide interfaces
directly. The interfaces provided by an object are the union of
by it's instances. An instance can also provide interfaces
directly. The interfaces provided by an object are the union of
the interfaces provided directly and the interfaces implemented by
the class.
"""
def providedBy(ob):
"""Return the interfaces provided by an object
"""
Return the interfaces provided by an object.
This is the union of the interfaces directly provided by an
object and interfaces implemented by it's class.
The value returned is an `IDeclaration`.
.. seealso:: `zope.interface.providedBy`
"""
def implementedBy(class_):
"""Return the interfaces implemented for a class' instances
"""
Return the interfaces implemented for a class's instances.
The value returned is an `IDeclaration`.
.. seealso:: `zope.interface.implementedBy`
"""
def classImplements(class_, *interfaces):
"""Declare additional interfaces implemented for instances of a class
"""
Declare additional interfaces implemented for instances of a class.
The arguments after the class are one or more interfaces or
interface specifications (`IDeclaration` objects).
@ -508,7 +516,14 @@ class IInterfaceDeclaration(Interface):
Instances of ``C`` provide ``I1``, ``I2``, and whatever interfaces
instances of ``A`` and ``B`` provide.
instances of ``A`` and ``B`` provide. This is equivalent to::
@implementer(I1, I2)
class C(A, B):
pass
.. seealso:: `zope.interface.classImplements`
.. seealso:: `zope.interface.implementer`
"""
def classImplementsFirst(cls, interface):
@ -517,14 +532,19 @@ class IInterfaceDeclaration(Interface):
"""
def implementer(*interfaces):
"""Create a decorator for declaring interfaces implemented by a factory.
"""
Create a decorator for declaring interfaces implemented by a
factory.
A callable is returned that makes an implements declaration on
objects passed to it.
.. seealso:: :meth:`classImplements`
"""
def classImplementsOnly(class_, *interfaces):
"""Declare the only interfaces implemented by instances of a class
"""
Declare the only interfaces implemented by instances of a class.
The arguments after the class are one or more interfaces or
interface specifications (`IDeclaration` objects).
@ -542,30 +562,41 @@ class IInterfaceDeclaration(Interface):
Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
whatever interfaces instances of ``A`` and ``B`` implement.
.. seealso:: `zope.interface.classImplementsOnly`
"""
def implementer_only(*interfaces):
"""Create a decorator for declaring the only interfaces implemented
"""
Create a decorator for declaring the only interfaces implemented.
A callable is returned that makes an implements declaration on
objects passed to it.
.. seealso:: `zope.interface.implementer_only`
"""
def directlyProvidedBy(object):
"""Return the interfaces directly provided by the given object
"""
Return the interfaces directly provided by the given object.
The value returned is an `IDeclaration`.
.. seealso:: `zope.interface.directlyProvidedBy`
"""
def directlyProvides(object, *interfaces):
"""Declare interfaces declared directly for an object
"""
Declare interfaces declared directly for an object.
The arguments after the object are one or more interfaces or
interface specifications (`IDeclaration` objects).
The interfaces given (including the interfaces in the
specifications) replace interfaces previously
declared for the object.
.. caution::
The interfaces given (including the interfaces in the
specifications) *replace* interfaces previously
declared for the object. See :meth:`alsoProvides` to add
additional interfaces.
Consider the following example::
@ -594,21 +625,31 @@ class IInterfaceDeclaration(Interface):
directlyProvides(ob, directlyProvidedBy(ob), I2)
adds I2 to the interfaces directly provided by ob.
.. seealso:: `zope.interface.directlyProvides`
"""
def alsoProvides(object, *interfaces):
"""Declare additional interfaces directly for an object::
"""
Declare additional interfaces directly for an object.
For example::
alsoProvides(ob, I1)
is equivalent to::
directlyProvides(ob, directlyProvidedBy(ob), I1)
.. seealso:: `zope.interface.alsoProvides`
"""
def noLongerProvides(object, interface):
"""Remove an interface from the list of an object's directly
provided interfaces::
"""
Remove an interface from the list of an object's directly provided
interfaces.
For example::
noLongerProvides(ob, I1)
@ -619,10 +660,17 @@ class IInterfaceDeclaration(Interface):
with the exception that if ``I1`` is an interface that is
provided by ``ob`` through the class's implementation,
`ValueError` is raised.
.. seealso:: `zope.interface.noLongerProvides`
"""
def implements(*interfaces):
"""Declare interfaces implemented by instances of a class
"""
Declare interfaces implemented by instances of a class.
.. deprecated:: 5.0
This only works for Python 2. The `implementer` decorator
is preferred for all versions.
This function is called in a class definition (Python 2.x only).
@ -655,14 +703,15 @@ class IInterfaceDeclaration(Interface):
Instances of ``C`` implement ``I1``, ``I2``, and whatever interfaces
instances of ``A`` and ``B`` implement.
.. deprecated:: 5.0
This only works for Python 2. The `implementer` decorator
is preferred for all versions.
"""
def implementsOnly(*interfaces):
"""Declare the only interfaces implemented by instances of a class
"""
Declare the only interfaces implemented by instances of a class.
.. deprecated:: 5.0
This only works for Python 2. The `implementer_only` decorator
is preferred for all versions.
This function is called in a class definition (Python 2.x only).
@ -691,14 +740,15 @@ class IInterfaceDeclaration(Interface):
Instances of ``C`` implement ``I1``, ``I2``, regardless of what
instances of ``A`` and ``B`` implement.
.. deprecated:: 5.0
This only works for Python 2. The `implementer_only` decorator
is preferred for all versions.
"""
def classProvides(*interfaces):
"""Declare interfaces provided directly by a class
"""
Declare interfaces provided directly by a class.
.. deprecated:: 5.0
This only works for Python 2. The `provider` decorator
is preferred for all versions.
This function is called in a class definition.
@ -725,17 +775,18 @@ class IInterfaceDeclaration(Interface):
directlyProvides(theclass, I1)
after the class has been created.
.. deprecated:: 5.0
This only works for Python 2. The `provider` decorator
is preferred for all versions.
"""
def provider(*interfaces):
"""A class decorator version of `classProvides`"""
"""
A class decorator version of `classProvides`.
.. seealso:: `zope.interface.provider`
"""
def moduleProvides(*interfaces):
"""Declare interfaces provided by a module
"""
Declare interfaces provided by a module.
This function is used in a module definition.
@ -757,16 +808,21 @@ class IInterfaceDeclaration(Interface):
is equivalent to::
directlyProvides(sys.modules[__name__], I1)
.. seealso:: `zope.interface.moduleProvides`
"""
def Declaration(*interfaces):
"""Create an interface specification
"""
Create an interface specification.
The arguments are one or more interfaces or interface
specifications (`IDeclaration` objects).
A new interface specification (`IDeclaration`) with
the given interfaces is returned.
A new interface specification (`IDeclaration`) with the given
interfaces is returned.
.. seealso:: `zope.interface.Declaration`
"""
class IAdapterRegistry(Interface):