Zope Annotation

6.0 · active · verified Fri Apr 17

The `zope.annotation` package provides a robust object annotation mechanism, allowing objects to be transparently extended with additional information without modifying their original class. It is part of the Zope Foundation ecosystem, currently at version 6.0, and maintains a stable release cadence aligned with Python and Zope community standards.

Common errors

```
TypeError: Could not adapt <__main__.MyObject object at 0x...> to <InterfaceClass zope.annotation.interfaces.IAnnotations>
```
cause The object you are trying to annotate does not provide the `IAnnotatable` interface, which is a prerequisite for `zope.annotation` to function.

fix Before attempting to get `IAnnotations(obj)`, ensure `obj` provides `IAnnotatable`. For testing or simple cases, use `from zope.interface import directlyProvides; directlyProvides(obj, IAnnotatable)`.
```
ImportError: cannot import name 'IAnnotations' from 'zope.annotation'
```
cause The `IAnnotations` interface is not directly under the `zope.annotation` package but within its `interfaces` submodule.

fix Change your import statement to `from zope.annotation.interfaces import IAnnotations`.
```
AttributeError: 'dict' object has no attribute '_p_jar'
```
cause You are attempting to store a non-persistent Python dictionary (or other non-persistent object) as an annotation on a persistent object within a ZODB, and ZODB is trying to make the *value* persistent but it doesn't know how.

fix If you need a persistent dictionary for annotations, use a persistent collection type from `ZODB.blob` or `BTrees`. For example, `from persistent.mapping import PersistentMapping; annotations['my_persistent_dict'] = PersistentMapping({'key': 'value'})`.

Warnings

breaking Version 6.0 of `zope.annotation` dropped support for Python 3.8. It now requires Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or a newer supported version. Alternatively, pin `zope.annotation` to `<6.0` if you must remain on Python 3.8.
gotcha Objects must explicitly provide the `IAnnotatable` interface to be annotated. If an object does not provide this interface, attempting to adapt it to `IAnnotations` will fail with a `TypeError`.
Fix: Ensure your object provides `IAnnotatable`. In simple cases, use `from zope.interface import directlyProvides; directlyProvides(obj, IAnnotatable)`. In more complex scenarios, objects might inherit from a base class providing `IAnnotatable` or have an adapter registered for it via `zope.component`.
gotcha When using `zope.annotation` with persistent objects (e.g., in a ZODB), any values stored as annotations must also be persistent objects themselves (or basic Python types like int, str, dict, list of basic types). Storing non-persistent objects will lead to `TypeError` or `AttributeError` during storage.
Fix: Ensure that the values you assign to `IAnnotations` are either basic Python types or objects that are themselves persistent (e.g., ZODB Persistent objects or types that can be pickled by ZODB).

Install

pip install zope.annotation Install stable version

Imports

IAnnotations
wrong:
```
from zope.annotation import IAnnotations
```
correct:
```
from zope.annotation.interfaces import IAnnotations
```
Interfaces are typically found in the `.interfaces` submodule within Zope packages.
IAnnotatable
```
from zope.annotation.interfaces import IAnnotatable
```
Required to mark an object as capable of being annotated.

Quickstart

This example demonstrates how to make an arbitrary object annotatable using `directlyProvides(obj, IAnnotatable)` and then use the `IAnnotations` adapter to store and retrieve key-value data on it. This pattern is fundamental for extending objects without inheritance in Zope-based applications.

from zope.interface import directlyProvides
from zope.annotation.interfaces import IAnnotations, IAnnotatable

# Define a simple class that can be annotated
class MyObject:
    pass

# Instantiate the object
obj = MyObject()

# An object must provide IAnnotatable to be annotated.
# In a real Zope application, this might be handled by decorators or base classes.
# For a standalone example, we directly provide the interface.
directlyProvides(obj, IAnnotatable)

# Get the annotations adapter for the object
# If no annotations exist, a new empty dictionary-like object is created.
annotations = IAnnotations(obj)

# Store and retrieve data on the object via annotations
annotations['my_data_key'] = 'This is some data stored as an annotation.'
annotations['another_key'] = {'list': [1, 2, 3], 'dict_val': 'value'}

print(f"Annotation 'my_data_key': {annotations['my_data_key']}")
print(f"Annotation 'another_key': {annotations['another_key']}")

# Check if an annotation exists
if 'my_data_key' in annotations:
    print("'my_data_key' exists in annotations.")

# Delete an annotation
del annotations['my_data_key']

if 'my_data_key' not in annotations:
    print("'my_data_key' successfully deleted.")

view raw JSON →