Grok-like configuration for Zope annotations
Python
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/grokcore
.coveragerc
.gitignore
.travis.yml
CHANGES.txt
COPYRIGHT.txt
LICENSE.txt
MANIFEST.in
README.txt
bootstrap.py
buildout.cfg
setup.py
tox.ini

README.txt

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

.. 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.

Example
=======

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):
        pass

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

    class Branding(grokcore.annotation.Annotation):
        grokcore.annotation.implements(ISerialBrand)
        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
    livestock2.foo = "something"

API Overview
============

Base classes
------------

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

``Model``
   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.

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

``LazyAnnotationProperty``
   Property implementation that works with ``LazyAnnotation``.

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

.. _grokcore.component: http://pypi.python.org/pypi/grokcore.component