Interface Specifications¶
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
ISpecification
:
- interface zope.interface.interfaces.ISpecification[source]¶
Object Behavioral specifications
- providedBy(object)¶
Test whether the interface is implemented by the object
Return true of the object asserts that it implements the interface, including asserting that it implements an extended interface.
- implementedBy(class_)¶
Test whether the interface is implemented by instances of the class
Return true of the class asserts that its instances implement the interface, including asserting that they implement an extended interface.
- isOrExtends(other)¶
Test whether the specification is or extends another
- extends(other, strict=True)¶
Test whether a specification extends another
The specification extends other if it has other as a base interface or if one of it’s bases extends other.
If strict is false, then the specification extends itself.
- weakref(callback=None)¶
Return a weakref to the specification
This method is, regrettably, needed to allow weakrefs to be computed to security-proxied specifications. While the zope.interface package does not require zope.security or zope.proxy, it has to be able to coexist with it.
- __bases__¶
Base specifications
A tuple of specifications from which this specification is directly derived.
- __sro__¶
Specification-resolution order
A tuple of the specification and all of it’s ancestor specifications from most specific to least specific. The specification itself is the first element.
(This is similar to the method-resolution order for new-style classes.)
- __iro__¶
Interface-resolution order
A tuple of the specification’s ancestor interfaces from most specific to least specific. The specification itself is included if it is an interface.
(This is similar to the method-resolution order for new-style classes.)
- get(name, default=None)¶
Look up the description for a name
If the named attribute is not defined, the default is returned.
- class zope.interface.interface.Specification(bases=())[source]¶
Bases:
SpecificationBase
Specifications
An interface specification is used to track interface declarations and component registrations.
This class is a base class for both interfaces themselves and for interface specifications (declarations).
Specifications are mutable. If you reassign their bases, their relations with other specifications are adjusted accordingly.
For example:
>>> 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 Specification.providedBy()
:
>>> from zope.interface import *
>>> class I1(Interface):
... pass
>>> @implementer(I1)
... class C(object):
... pass
>>> 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 Specification.isOrExtends()
:
>>> 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 Specification.interfaces()
:
>>> 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 Specification.extends()
:
>>> 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
Equality, Hashing, and Comparisons¶
Specifications (including their notable subclass Interface
), are
hashed and compared (sorted) based solely on their __name__
and
__module__
, not including any information about their enclosing
scope, if any (e.g., their __qualname__
). This means that any two
objects created with the same name and module are considered equal and
map to the same value in a dictionary.
>>> from zope.interface import Interface
>>> class I1(Interface): pass
>>> orig_I1 = I1
>>> class I1(Interface): pass
>>> I1 is orig_I1
False
>>> I1 == orig_I1
True
>>> d = {I1: 42}
>>> d[orig_I1]
42
>>> def make_nested():
... class I1(Interface): pass
... return I1
>>> nested_I1 = make_nested()
>>> I1 == orig_I1 == nested_I1
True
Caveats¶
While this behaviour works will with pickling (persistence), it has some potential downsides to be aware of.
Weak References
The first downside involves weak references. Because weak references
hash the same as their underlying object, this can lead to surprising
results when weak references are involved, especially if there are
cycles involved or if the garbage collector is not based on reference
counting (e.g., PyPy). For example, if you redefine an interface named
the same as an interface being used in a WeakKeyDictionary
, you
can get a KeyError
, even if you put the new interface into the
dictionary.
>>> from zope.interface import Interface
>>> import gc
>>> from weakref import WeakKeyDictionary
>>> wr_dict = WeakKeyDictionary()
>>> class I1(Interface): pass
>>> wr_dict[I1] = 42
>>> orig_I1 = I1 # Make sure it stays alive
>>> class I1(Interface): pass
>>> wr_dict[I1] = 2020
>>> del orig_I1
>>> _ = gc.collect() # Sometime later, gc runs and makes sure the original is gone
>>> wr_dict[I1] # Cleaning up the original weakref removed the new one
Traceback (most recent call last):
...
KeyError: ...
This is mostly likely a problem in test cases where it is tempting to
use the same named interfaces in different test methods. If references
to them escape, especially if they are used as the bases of other
interfaces, you may find surprising KeyError
exceptions. For this
reason, it is best to use distinct names for local interfaces within
the same test module.
Providing Dynamic Interfaces
If you return an interface created inside a function or method, or otherwise let it escape outside the bounds of that function (such as by having an object provide it), it’s important to be aware that it will compare and hash equal to any other interface defined in that same module with the same name. This includes interface objects created by other invocations of that function.
This can lead to surprising results when querying against those interfaces. We can demonstrate by creating a module-level interface with a common name, and checking that it is provided by an object:
>>> from zope.interface import Interface, alsoProvides, providedBy
>>> class ICommon(Interface):
... pass
>>> class Obj(object):
... pass
>>> obj = Obj()
>>> alsoProvides(obj, ICommon)
>>> len(list(providedBy(obj)))
1
>>> ICommon.providedBy(obj)
True
Next, in the same module, we will define a function that dynamically creates an interface of the same name and adds it to an object.
>>> def add_interfaces(obj):
... class ICommon(Interface):
... pass
... class I2(Interface):
... pass
... alsoProvides(obj, ICommon, I2)
... return ICommon
...
>>> dynamic_ICommon = add_interfaces(obj)
The two instances are not identical, but they are equal, and obj provides them both:
>>> ICommon is dynamic_ICommon
False
>>> ICommon == dynamic_ICommon
True
>>> ICommon.providedBy(obj)
True
>>> dynamic_ICommon.providedBy(obj)
True
At this point, we’ve effectively called alsoProvides(obj, ICommon,
dynamic_ICommon, I2)
, where the last two interfaces were locally
defined in the function. So checking how many interfaces obj now
provides should return three, right?
>>> len(list(providedBy(obj)))
2
Because ICommon == dynamic_ICommon
due to having the same
__name__
and __module__
, only one of them is actually provided
by the object, for a total of two provided interfaces. (Exactly which
one is undefined.) Likewise, if we run the same function again, obj
will still only provide two interfaces
>>> _ = add_interfaces(obj)
>>> len(list(providedBy(obj)))
2
Interface¶
Interfaces are a particular type of ISpecification
and implement the
API defined by IInterface
.
Before we get there, we need to discuss two related concepts. The
first is that of an “element”, which provides us a simple way to query
for information generically (this is important because we’ll see that
IInterface
implements this interface):
- interface zope.interface.interfaces.IElement[source]¶
Objects that have basic documentation and tagged values.
Known derivatives include
IAttribute
and its derivativeIMethod
; these have no notion of inheritance.IInterface
is also a derivative, and it does have a notion of inheritance, expressed through its__bases__
and ordered in its__iro__
(both defined byISpecification
).- __name__¶
The object name
- __doc__¶
The object doc string
- getTaggedValue(tag)¶
Returns the value associated with tag.
Raise a
KeyError
if the tag isn’t set.If the object has a notion of inheritance, this searches through the inheritance hierarchy and returns the nearest result. If there is no such notion, this looks only at this object.
Changed in version 4.7.0: This method should respect inheritance if present.
- queryTaggedValue(tag, default=None)¶
As for
getTaggedValue
, but instead of raising aKeyError
, returns default.Changed in version 4.7.0: This method should respect inheritance if present.
- getTaggedValueTags()¶
Returns a collection of all tags in no particular order.
If the object has a notion of inheritance, this includes all the inherited tagged values. If there is no such notion, this looks only at this object.
Changed in version 4.7.0: This method should respect inheritance if present.
- setTaggedValue(tag, value)¶
Associates value with key directly in this object.
- getDirectTaggedValue(tag)¶
As for
getTaggedValue
, but never includes inheritance.New in version 5.0.0.
- queryDirectTaggedValue(tag, default=None)¶
As for
queryTaggedValue
, but never includes inheritance.New in version 5.0.0.
- getDirectTaggedValueTags()¶
As for
getTaggedValueTags
, but includes only tags directly set on this object.New in version 5.0.0.
- class zope.interface.interface.Element(__name__, __doc__='')[source]¶
Bases:
object
Default implementation of
zope.interface.interfaces.IElement
.
Next, we look at IAttribute
and IMethod
. These make up the
content, or body, of an Interface
.
- interface zope.interface.interfaces.IAttribute[source]¶
Extends:
zope.interface.interfaces.IElement
Attribute descriptors
- interface¶
Stores the interface instance in which the attribute is located.
- class zope.interface.interface.Attribute(__name__, __doc__='')[source]¶
Bases:
Element
Attribute descriptions
- interface zope.interface.interfaces.IMethod[source]¶
Extends:
zope.interface.interfaces.IAttribute
Method attributes
- getSignatureInfo()¶
Returns the signature information.
This method returns a dictionary with the following string keys:
- positional
A sequence of the names of positional arguments.
- required
A sequence of the names of required arguments.
- optional
A dictionary mapping argument names to their default values.
- varargs
The name of the varargs argument (or None).
- kwargs
The name of the kwargs argument (or None).
- getSignatureString()¶
Return a signature string suitable for inclusion in documentation.
This method returns the function signature string. For example, if you have
def func(a, b, c=1, d='f')
, then the signature string is"(a, b, c=1, d='f')"
.
- class zope.interface.interface.Method(__name__, __doc__='')[source]¶
Bases:
Attribute
Method interfaces
The idea here is that you have objects that describe methods. This provides an opportunity for rich meta-data.
Finally we can look at the definition of IInterface
.
- interface zope.interface.interfaces.IInterface[source]¶
Extends:
zope.interface.interfaces.ISpecification
,zope.interface.interfaces.IElement
Interface objects
Interface objects describe the behavior of an object by containing useful information about the object. This information includes:
Prose documentation about the object. In Python terms, this is called the “doc string” of the interface. In this element, you describe how the object works in prose language and any other useful information about the object.
Descriptions of attributes. Attribute descriptions include the name of the attribute and prose documentation describing the attributes usage.
Descriptions of methods. Method descriptions can include:
Prose “doc string” documentation about the method and its usage.
A description of the methods arguments; how many arguments are expected, optional arguments and their default values, the position or arguments in the signature, whether the method accepts arbitrary arguments and whether the method accepts arbitrary keyword arguments.
Optional tagged data. Interface objects (and their attributes and methods) can have optional, application specific tagged data associated with them. Examples uses for this are examples, security assertions, pre/post conditions, and other possible information you may want to associate with an Interface or its attributes.
Not all of this information is mandatory. For example, you may only want the methods of your interface to have prose documentation and not describe the arguments of the method in exact detail. Interface objects are flexible and let you give or take any of these components.
Interfaces are created with the Python class statement using either
zope.interface.Interface
or another interface, as in:from zope.interface import Interface class IMyInterface(Interface): '''Interface documentation''' def meth(arg1, arg2): '''Documentation for meth''' # Note that there is no self argument class IMySubInterface(IMyInterface): '''Interface documentation''' def meth2(): '''Documentation for meth2'''
You use interfaces in two ways:
You assert that your object implement the interfaces.
There are several ways that you can declare that an object provides an interface:
Call
zope.interface.implementer
on your class definition.Call
zope.interface.directlyProvides
on your object.Call
zope.interface.classImplements
to declare that instances of a class implement an interface.For example:
from zope.interface import classImplements classImplements(some_class, some_interface)
This approach is useful when it is not an option to modify the class source. Note that this doesn’t affect what the class itself implements, but only what its instances implement.
You query interface meta-data. See the IInterface methods and attributes for details.
- names(all=False)¶
Get the interface attribute names
Return a collection of the names of the attributes, including methods, included in the interface definition.
Normally, only directly defined attributes are included. If a true positional or keyword argument is given, then attributes defined by base classes will be included.
- namesAndDescriptions(all=False)¶
Get the interface attribute names and descriptions
Return a collection of the names and descriptions of the attributes, including methods, as name-value pairs, included in the interface definition.
Normally, only directly defined attributes are included. If a true positional or keyword argument is given, then attributes defined by base classes will be included.
- __getitem__(name)¶
Get the description for a name
If the named attribute is not defined, a
KeyError
is raised.
- direct(name)¶
Get the description for the name if it was defined by the interface
If the interface doesn’t define the name, returns None.
- validateInvariants(obj, errors=None)¶
Validate invariants
Validate object to defined invariants. If errors is None, raises first Invalid error; if errors is a list, appends all errors to list, then raises Invalid with the errors as the first element of the “args” tuple.
- __contains__(name)¶
Test whether the name is defined by the interface
- __iter__()¶
Return an iterator over the names defined by the interface
The names iterated include all of the names defined by the interface directly and indirectly by base interfaces.
- __module__¶
The name of the module defining the interface
- interface zope.interface.Interface¶
Usage¶
Exmples for InterfaceClass.extends()
:
>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>>
>>> i = I1.interfaces()
>>> [x.getName() for x in i]
['I1']
>>> list(i)
[]