Metadata-Version: 1.1
Name: grokcore.annotation
Version: 1.5
Summary: Grok-like configuration for Zope annotations
Home-page: http://grok.zope.org
Author: Grok Team
Author-email: grok-dev@zope.org
License: ZPL
Download-URL: http://pypi.python.org/pypi/grokcore.annotation
Description: 
        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.
        
        In addition, the ``grokcore.annotation`` package exposes the
        `grokcore.component`_ API.
        
        .. _grokcore.component: http://pypi.python.org/pypi/grokcore.component
        
        
        
        Changes
        =======
        
        1.5 (2014-10-20)
        ----------------
        
        - Updating MANIFEST.in, fixing a brown paper bag release.
        
        1.4 (2014-10-17)
        ----------------
        
        - Add ``queryAnnotation()`` to return an annotation. Return None if it
          doesn't exists. This helper will never do any write operation in the
          database.
        
        - Add ``deleteAnnotation()`` to delete an annotation (if it exists).
        
        1.3 (2012-05-01)
        ----------------
        
        - Use ``provideAdapter()`` from grokcore.component.util.
        
        - Made package comply to zope.org repository policy.
        
        1.2 (2009-12-13)
        ----------------
        
        * Use zope.container instead of zope.app.container.
        
        1.1 (2009-09-18)
        ----------------
        
        * The annotation object become really a contained object to be aware
          of its context, and name.
        
        * Use 1.0b1 versions.cfg in Grok's release info instead of a local
          copy; a local copy for all grokcore packages is just too hard to
          maintain.
        
        1.0.1 (2009-06-30)
        ------------------
        
        * Reupload to pypi with a correct version of Python which doesn't
          have a distutils bug.
        
        1.0 (2009-06-29)
        ----------------
        
        * Created ``grokcore.Annotation`` by factoring annotation components,
          grokkers and directives out of Grok.
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Framework :: Zope3
