zope.annotation API

Framework Interfaces

These interfaces define the source and targets for adaptation under the zope.annotation framework:

Annotations store arbitrary application data under package-unique keys.

interface zope.annotation.interfaces.IAnnotatable[source]

Marker interface for objects that support storing annotations.

This interface says “There exists an adapter to an IAnnotations for an object that implements IAnnotatable”.

Classes should not directly declare that they implement this interface. Instead they should implement an interface derived from this one, which details how the annotations are to be stored, such as IAttributeAnnotatable.

interface zope.annotation.interfaces.IAnnotations[source]

Extends: zope.annotation.interfaces.IAnnotatable

Stores arbitrary application data under package-unique keys.

By “package-unique keys”, we mean keys that are are unique by virtue of including the dotted name of a package as a prefix. A package name is used to limit the authority for picking names for a package to the people using that package.

For example, when implementing annotations for storing Zope Dublin-Core meta-data, we use the key:

"zope.app.dublincore.ZopeDublinCore"
__nonzero__()

Test whether there are any annotations

Must be identical to __bool__()

__bool__()

Test whether there are any annotations

Must be identical to __nonzero__()

__getitem__(key)

Return the annotation stored under key.

Raises KeyError if key not found.

get(key, default=None)

Return the annotation stored under key, or default if not found.

__setitem__(key, value)

Store annotation under key.

In order to avoid key collisions, users of this interface must use their dotted package name as part of the key name.

__delitem__(key)

Removes the annotation stored under key.

Raises a KeyError if the key is not found.

__iter__()

Return an iterator for the keys in the container.

__contains__(key)

Return True if ‘key’ is in the container, else False.

items()

Return ‘(key, value)’ pairs for the keys in the container.

interface zope.annotation.interfaces.IAttributeAnnotatable[source]

Extends: zope.annotation.interfaces.IAnnotatable

Marker indicating that annotations can be stored on an attribute.

This is a marker interface giving permission for an IAnnotations adapter to store data in an attribute named __annotations__.

Attribute-Based Annotations

The default adapter implementation uses a special attribute, __annotations__, on the annotated object:

class zope.annotation.attribute.AttributeAnnotations(obj, context=None)[source]

Bases: _abcoll.MutableMapping

Store annotations on an object

Store annotations in the __annotations__ attribute on a IAttributeAnnotatable object.

get(key, default=None)[source]

See zope.annotation.interfaces.IAnnotations

Because setting an attribute is somewhat intrusive (as opposed to storing annotations elsewhere), this adapter requires that its context implment zope.annotation.interfaces.IAttributeAnnotatable to signal that this attribute can be used.

Factories

Annotation factory helper

zope.annotation.factory.factory(factory, key=None)[source]

Adapter factory to help create annotations easily.