Interface objects
Interface objects describe the behavior of an object by containing useful information about the object. This information includes:
- o 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.
- o Descriptions of attributes. Attribute descriptions include
- the name of the attribute and prose documentation describing the attributes usage.
o 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.
- o 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 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:
o You assert that your object implement the interfaces.
There are several ways that you can assert that an object implements an interface:
Call zope.interface.implements in your class definition.
Call zope.interfaces.directlyProvides on your object.
Call 'zope.interface.classImplements' to assert 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.
__module__
(Attribute)
The name of the module defining the interface
__sro__
(Attribute)
Specification-resolution order
A tuple of the specification and all of it's ancestor specifications from most specific to least specific.
(This is similar to the method-resolution order for new-style classes.)
__bases__
(Attribute)
Base specifications
A tuple if specifications from which this specification is directly derived.
__doc__
(Attribute)
The object doc string
__name__
(Attribute)
The object name
* = required
isOrExtends(other)
Test whether the specification is or extends another
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.
queryTaggedValue(tag, default=None)
Returns the value associated with tag.
Return the default value of the tag isn't set.
getTaggedValueTags()
Returns a list of all tags.
__getitem__(name)
Get the description for a name
If the named attribute is not defined, a KeyError is raised.
get(name, default=None)
Look up the description for a name
If the named attribute is not defined, the default is returned.
setTaggedValue(tag, value)
Associates value with key.
__contains__(name)
Test whether the name is defined by the interface
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.
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.
__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.
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.
names(all=False)
Get the interface attribute names
Return a sequence 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.
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.
namesAndDescriptions(all=False)
Get the interface attribute names and descriptions
Return a sequence 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.
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.
getTaggedValue(tag)
Returns the value associated with tag.
Raise a KeyError of the tag isn't set.