=========== Five Manual =========== Zope interfaces --------------- Interfaces? =========== An interface is simply a description of what an object provides to the world, i.e. its public attribute and methods. It looks very much like a class, but contains no implementation:: from zope.interface import Interface # by convention, all interfaces are prefixed with ``I`` class IElephant(Interface): """An elephant is a big object that barely fits in the cupboard. """ def getAngerLevel(): """Anger level, maximum of 100. The longer the elephant has been in the cupboard, the angrier. """ def isInCupboard(): """Returns true if the elephant is indeed in cupboard. """ def trunkSmash(target): """Smash the target with trunk. The anger level determines the force of the hit. """ def trample(target): """Trample the target. The anger level determines the rate of flattening of the target. """ A concrete class somewhere can now claim that it implements the interface (i.e. its instance will provide the interface):: class PinkElephant: # this says all instances of this class provide IElephant implements(IElephant) def getAngerLevel(self): return 0 # this elephant is peaceful def isInCupboard(self): return False # it's never in a cupboard but can be found in bottles def trunkSmash(self, target): target.tickle() def trample(self, target): target.patOnHead() Interfaces themselves are good for a number of reasons: * They provide API documentation. * They help you make explicit the design of your application, hopefully improving it. * If an object provides an interface, that object is considered to be a *component*. This means you can use Zope's component architecture with these objects. In order to use the component architecture, you'll have to make your objects provide interfaces. Sometimes, you cannot change the code of class (as you are not the maintainer), but you still want to make it implement an interface. Zope provides a ZCML directive to do this:: Adapters -------- From a Python programmer's perspective, the immediate thing that Five brings to do the table are adapters. This section goes through some demo code to explain how everything is tied together. Zope adapters depend on Zope interfaces. To create a Zope interface you need to subclass it from ``zope.interface.Interface``. Here is an example:: from zope.interface import Interface class IMyInterface(Interface): """This is an interface. """ def someMethod(): """This method does amazing stuff. """ Now to make some class declare that it implements this interface, you need to use the ``implements()`` function in the class:: from zope.interface import implements from interfaces import IMyInterface class MyClass: implements(IMyInterface) def someMethod(self): return "I am alive! Alive!" Now let's set up the interface that we are adapting to:: class INewInterface(Interface): """The interface we adapt to. """ def anotherMethod(): """This method does more stuff. """ Next we'll work on the class that implements the adapter. The requirement to make a class that is an adapter is very simple; you only need to take a context object as the constructor. The context object is the object being adapted. An example:: from zope.interface import implements from interfaces import INewInterface class MyAdapter: implements(INewInterface) def __init__(self, context): self.context = context def anotherMethod(self): return "We have adapted: %s" % self.context.someMethod() Next, we hook it all up using zcml. If the classes are in a module called ``classes.py`` and the interfaces in a module called ``interfaces.py``, we can declare ``MyAdapter`` to be an adapter for ``IMyInterface`` to ``INewInterface`` like this (in a file called ``configure.zcml``):: Zope will automatically pickup ``configure.zcml`` when it's placed in the product's directory. Any object that provides ``IMyInterface`` can now be adapted to ``INewInterface``, like this:: from classes import MyClass from interfaces import INewInterface object = MyClass() adapted = INewInterface(object) print adapted.anotherMethod() Views ----- This section will give a brief introduction on how to use the Zope view system. Zope enables you to create views for your own objects, or even built-in Zope objects, as long as two things are the case: * The object provides a Zope interface, typically through its class. * The object (typically its class) is made traversable. This allows Zope views, resources and other things to be attached to a Zope object. Typically you give your classes an interface using the ``implements`` directive in the class body:: class MyClass: implements(ISomeInterface) For existing objects that you cannot modify this is not possible. Instead, we provide a ZCML directive to accomplish this. As an example, to make Zope's ``Folder`` (and all its subclasses) implement ``IFolder`` (an interface you defined), you can do the following in ZCML:: Views in Zope are simple classes. The only requirements for a view class are: * They need an ``__init__()`` that take a context and a request attribute. Typically this comes from a base class, such as ``BrowserView``. An example of a simple view:: from zope.publisher.browser import BrowserView class SimpleFolderView(BrowserView): def eagle(self): """Test """ return "The eagle has landed: %s" % self.context.keys() Note that it is not a good idea to give a view class its own ``index_html``, as this confuses Zope's view lookup machinery. This view uses methods in Python, but you can also use other mechanisms such as ``ViewPageTemplateFile``. Finally, we need to hook up the pages through ZCML:: ``browser`` in this refers to the XML namespace for browser related things; it's ``http://namespace.zope.org/browser``. ``permission`` declares the Zope 2 permission needs in order to access this view. The file ``permissions.zcml`` in AccessControl contains a mapping of Zope 2 permissions to their zope.security names.