Grok-like configuration for Zope annotations
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


This package provides a support to simplify the use of annotations in

.. contents::

Setting up ``grokcore.annotation``

This package is essentially set up like the `grokcore.component`_
package, please refer to its documentation for details.  The only
additional ZCML line you will need is::

  <include package="grokcore.annotation" />

Put this somewhere near the top of your root ZCML file but below the
line where you include ``grokcore.component``'s configuration.


Here a simple example of use of an annotation::

    import grokcore.annotation
    from zope import interface

    # Create a model and an interface you want to adapt it to
    # and an annotation class to implement the persistent adapter.
    class Mammoth(grokcore.annotation.Model):

    class ISerialBrand(interface.Interface):
        unique = interface.Attribute("Brands")

    class Branding(grokcore.annotation.Annotation):
        unique = 0

    # Grok the above code, then create some mammoths
    manfred = Mammoth()
    mumbles = Mammoth()

    # creating Annotations work just like Adapters
    livestock1 = ISerialBrand(manfred)
    livestock2 = ISerialBrand(mumbles)

    # except you can store data in them, this data will transparently persist
    # in the database for as long as the object exists
    livestock1.unique = 101
    livestock2.unique = 102

    # attributes not listed in the interface will also be persisted
    # on the annotation = "something"

API Overview

Base classes

   Base class for an Annotation. Inherits from the
   persistent.Persistent class.

   Base class for a Model on which you want to use an annotation.

``queryAnnotation(model, interface)``
   Query the annotation on the given model for the given
   interface. Return the annotation if found, None otherwise. This
   will not *make* any write operation.

``deleteAnnotation(model, interface)``
   Look for the given annotation and delete it from the model.

   Base class for an annotation. It only writes a database object when
   explicitly setting values on the lazy properties.

   Property implementation that works with ``LazyAnnotation``.

In addition, the ``grokcore.annotation`` package exposes the
`grokcore.component`_ API.

.. _grokcore.component: