[Checkins] SVN: grokcore.annotation/trunk/README.txt Write a cool README.txt.
Sylvain Viollon
sylvain at infrae.com
Thu Jun 18 04:44:44 EDT 2009
Log message for revision 101121:
Write a cool README.txt.
Changed:
U grokcore.annotation/trunk/README.txt
-=-
Modified: grokcore.annotation/trunk/README.txt
===================================================================
--- grokcore.annotation/trunk/README.txt 2009-06-18 08:37:00 UTC (rev 101120)
+++ grokcore.annotation/trunk/README.txt 2009-06-18 08:44:44 UTC (rev 101121)
@@ -1 +1,79 @@
-FIXME
+
+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.
+
+
+In addition, the ``grokcore.annotation`` package exposes the
+`grokcore.component`_ API.
+
+.. _grokcore.component: http://pypi.python.org/pypi/grokcore.component
+
+
More information about the Checkins
mailing list