[z3-five] Re: Annotations

[Philipp von Weitershausen]

Tim Hicks wrote:
> Hi all,
> 
> First up, I'm new around these parts (both Zope3 parts and Five parts), so
> go easy ;-). (I'm also not subscribed here, so cc's to me direct would be
> appreciated.)

I would recommend reading some Zope3 documentation. Five does nothing on 
its own; it is just a layer to allow you to use Zope3 features in Zope2. 
That's a good thing because we don't need extra documentation.

Recommended reading:

- Python Programmer Tutorial:
   http://dev.zope.org/Zope3/ProgrammerTutorial
   (great for getting to know the Component Architecture)

- Zope3 for Zope2 Developers:
   http://philikon.de/files/zope3-for-zope2-developers.pdf
   (a little outdated on a few details, but good for experienced Zope2
   developers to see the differences)

- Stephan Richter's cookbook:
   http://dev.zope.org/Zope3/Zope3Book
   (great when you need to read about a specific feature)

> I want to write an adapter for a class (an archetype in case that makes
> any difference) that allows me to store and retrieve some additional
> attributes that are not part of the basic schema.  I figure annotations
> are a good way to go for this, right?

Indeed. The easiest thing would probably be to use attribute 
annotations, where annotations are simply stored in an __annotations__ 
attribute on the objects.

> If so, what would I need to do to use zope3 annotations in Five?

99.9% of what you need to do when you want to use annotations in Zope3 
itself. Only if you want to use attribute annotations (which I 
recommend), you should make sure you load the configuration file of the 
zope.app.annotations package, e.g. in your product's configure.zcml, 
include this statement:

   <include package="zope.app.annotations" />

You can then acquire an adapter from your objects to IAnnotations which 
allow you store arbitrary data. If you want to make it even more 
comfortable for the programmer, you can make an additional adapter 
yourself; it would use annotations under the hood and offer a nice API 
for whatever values you need to store. Look at zope.app.dublincore (the 
ZopeDublinCore adapter) to see an adapter that provides the DublinCore 
API and uses annotations underneath.

Philipp