Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

pypm install zope.principalannotation

How to install zope.principalannotation

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install zope.principalannotation
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
4.0.0a2Never BuiltWhy not?
3.6.1 Available View build log
Windows (64-bit)
4.0.0a2Never BuiltWhy not?
3.6.1 Available View build log
Mac OS X (10.5+)
4.0.0a2 Available View build log
3.6.1 Available View build log
Linux (32-bit)
4.0.0a2 Available View build log
3.6.1 Available View build log
Linux (64-bit)
4.0.0a2 Available View build log
3.6.1 Available View build log
4.0.0a2 Available View build log
ZPL 2.1
Lastest release
version 4.0.0a2 on Feb 26th, 2013

Principal Annotations

This package implements annotations for zope.security principals. To make it clear, the principal here is the object that provides zope.security.interfaces.IPrincipal interface and annotations is the object providing zope.annotation.interfaces.IAnnotations.

The problem is that principals is dynamic, non-persistent objects created on the fly for every security participation (request or something), so common annotation techniques, like AttributeAnnotations cannot be applied to them.

This package provides a persistent storage of principal annotations, storing annotations by principal ID as well as an adapter from IPrincipal to IAnnotations.


The core of this package is the PrincipalAnnotationUtility class that stores annotations for principals and allows to get them easily.

It provides the IPrincipalAnnotationUtility interface:

>>> from zope.principalannotation.interfaces import IPrincipalAnnotationUtility
>>> from zope.principalannotation.utility import PrincipalAnnotationUtility
>>> from zope.interface.verify import verifyObject
>>> util = PrincipalAnnotationUtility()
>>> verifyObject(IPrincipalAnnotationUtility, util)

It provides three methods: getAnnotations, getAnnotationsById and hasAnnotations. Let's create a testing principal and check out these methods:

>>> from zope.security.testing import Principal
>>> nadako = Principal('nadako')
>>> nadako.id

We can check if our principal has any annotations. Of course, it currently doesn't have any:

>>> util.hasAnnotations(nadako)

We can get IAnnotations object using principal object itself:

>>> util.getAnnotations(nadako)
<zope.principalannotation.utility.Annotations object at 0x...>

Or using principal id:

>>> util.getAnnotationsById(nadako.id)
<zope.principalannotation.utility.Annotations object at 0x...>

Let's get the IAnnotations object for our principal and play with it:

>>> annots = util.getAnnotations(nadako)

>>> from zope.interface.verify import verifyObject
>>> from zope.annotation.interfaces import IAnnotations
>>> verifyObject(IAnnotations, annots)

Let's check the IAnnotation contract:

>>> bool(annots)

>>> annots['not.here']
Traceback (most recent call last):
KeyError: 'not.here'

>>> annots.get('not.here') is None

>>> annots.get('not.here', 42)

Note, that the IAnnotations object gets stored in the utility only when we set a key for it. This is a simple optimization that allows us not to store any data when all we do is simply checking for presense of annotation. The hasAnnotations method will return True after storing a key in the annotations:

>>> util.hasAnnotations(nadako)

>>> annots['its.here'] = 'some info'

>>> util.hasAnnotations(nadako)

We can also delete the existing key:

>>> del annots['its.here']

But we can't delete the key that is (no more) existant:

>>> del annots['its.here']
Traceback (most recent call last):
KeyError: 'its.here'
Multiple annotation utilities

Imagine that your application has a root site object with its component registry (a.k.a. site manager) and that object has a sub-site object with its own component registry, and that component registry has the root's component registry as its base.

In that case, we want the IAnnotations object to be available to retrieve annotations from higher-level utilities.

Let's register our utility in the root site and create a sub-site with its own IPrincipalAnnotationUtility:

>>> root['util'] = util
>>> rootsm = root.getSiteManager()
>>> rootsm.registerUtility(util, IPrincipalAnnotationUtility)

>>> from zope.site.folder import Folder
>>> from zope.site.site import LocalSiteManager

>>> subsite = Folder()
>>> root['subsite'] = subsite
>>> subsm = LocalSiteManager(subsite)
>>> subsm.__bases__ = (rootsm,)
>>> subsite.setSiteManager(subsm)

>>> util2 = PrincipalAnnotationUtility()
>>> subsite['util2'] = util2
>>> subsm.registerUtility(util2, IPrincipalAnnotationUtility)

Now, let's create a key in the IAnnotations, provided by root utility:

>>> annots = util.getAnnotations(nadako)
>>> annots['root.number'] = 42

The subsite utility should get the annotation successfully:

>>> annots2 = util2.getAnnotations(nadako)
>>> bool(annots2)

>>> annots2['root.number']

If we have the key both in higher-level annotations and lower-level ones, the lower-level will have priority, but higher-level won't be deleted or overriden:

>>> annots['another.number'] = 1
>>> annots2['another.number'] = 42

>>> annots['another.number']
>>> annots2['another.number']

If we'll delete the key from lower-level, it will not be deleted from a higher level utility:

>>> del annots2['another.number']

>>> annots['another.number']
>>> annots2['another.number']
IPrincipal -> IAnnotations adapter

Of course, the most nice feature is that we can simply adapt our principal object to IAnnotations and get those annotations using standard way documented in zope.annotation package.

>>> annots = IAnnotations(nadako)
>>> annots
<zope.principalannotation.utility.Annotations object at 0x...>
>>> annots['root.number']

By default, the IAnnotation adapter uses the current site's utility:

>>> IAnnotations(nadako) is util.getAnnotations(nadako)

>>> from zope.site.hooks import setSite
>>> setSite(subsite)

>>> IAnnotations(nadako) is util2.getAnnotations(nadako)

Howerver, we can use a binary multi-adapter to IAnnotations to specify some context object from which to get the annotations utility:

>>> from zope.component import getMultiAdapter

>>> annots = getMultiAdapter((nadako, root), IAnnotations)
>>> annots is util.getAnnotations(nadako)

>>> annots = getMultiAdapter((nadako, subsite), IAnnotations)
>>> annots is util2.getAnnotations(nadako)


4.0.0a2 (2013-02-25)
  • Corrected Trove classifiers.
4.0.0a1 (2013-02-24)
  • Added support for Python 3.3.
  • Replaced deprecated zope.interface.implements usage with equivalent zope.interface.implementer decorator.
  • Dropped support for Python 2.4 and 2.5.
3.6.1 (2010-05-05)
  • Fixed a test failure in nested local site manager setup.
  • Removed dependency on zope.container.
3.6.0 (2009-03-09)

Initial release. This package was splitted off zope.app.principalannotation to remove its dependencies on "zope 3 application server" components.

In addition, the following changes were made after split off:

  • The IAnnotations implementation was fixed to look in the higher-level utility not only on __getitem__, but also on get and __nonzero.
  • Tests was reworked into the README.txt doctest.
  • Added a buildout part that generates Sphinx documentation from the README.txt

Subscribe to package updates

Last updated Feb 26th, 2013

Download Stats

Last month:8

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.