plone.uuid

This is a minimal package that can be used to obtain a universally unique identifier (UUID) for an object.

The default implementation uses the Python standard library uuid module to generate an RFC 4122-compliant UUID, using the uuid4() function. It will assign a UUID upon object creation (by subscribing to IObjectCreatedEvent from zope.lifecycleevent) and store it in an attribute on the object.

> Why use an attribute and not annotations? The most common form of > annotation is the one provided by IAttributeAnnotations. This stores > annotations in a BTree in an attribute called __annotations__, which > means that annotation values do not end up in the same ZODB persistent > object as the parent. This is good for "large" values, but not very > good for small ones that are frequently required, as it requires a > separate ZODB object load.

Simple usage

To automatically assign a UUID to your objects using the default implementation outlined above, you should:

• Make sure they implement plone.uuid.interfaces.IAttributeUUID. You can do this in code, via the implements() directive, or in ZCML, with a statement like:

• Make sure that an IObjectCreatedEvent is fired for this object when it is first created.

Once the event handler has triggered, you can obtain a UUID by adapting the object to the IUUID interface:

from plone.uuid.interfaces import IUUID
uuid = IUUID(context)

The uuid variable will now be a (byte) string containing a UUID. If the UUID has not yet been assigned, adaptation will fail with a TypeError.

If you would rather get None instead of a TypeError, you can do:

uuid = IUUID(context, None)

UUID view

If you require a UUID in a page template or remotely, you can use the @@uuid view, which is registered for all objects that provide the IUUIDAware marker interface (which is a super-interface of the IAttributeUUID marker seen above).

For example:

<div>
    ...
</div>

The view simply returns the UUID string as looked up by the IUUID adapter.

Customising behaviour

There are two primary customisation points for this package:

• You can change the default UUID generating algorithm by overriding the unnamed utility providing the IUUIDGenerator interface. The default implementation simply calls uuid.uuid4() and casts the result to a str.

• You can change the UUID storage by providing a custom IUUID adapter implementation. If you do this, you must also provide a mechanism for assigning UUIDs upon object creation, usually via an event handler. To obtain a UUID, use the IUUIDGenerator interface:

  from zope.component import getUtility
  from plone.uuid.interfaces import IUUIDGenerator
  
  generator = getUtility(IUUIDGenerator)
  uuid = generator()
  

  You should also make sure that instances with a UUID provide a sub-interface of plone.uuid.interfaces.IUUIDAware.

Changelog

2.0.1 (2024-01-22)

Internal:

• Update configuration files. [plone devs] (237ff4c8, 6e36bcc4)

2.0.0 (2023-04-26)

Breaking changes:

• Drop python 2.7 support. [gforcada] (#1)

Internal:

• Update configuration files. [plone devs] (2ed8f544)

1.0.6 (2020-04-22)

Bug fixes:

• Minor packaging updates. (#1)

1.0.5 (2018-01-18)

Bug fixes:

• Fix package dependencies. [gforcada]
• Fix documentation and uuid generator class name to reflect the fact that we use the uuid4 implementation instead of uuid1. [thet]

1.0.4 (2016-06-02)

Bug fixes:

• Update setup.py url to point to github. [esteele]
• Fixed issues preventing tests passing on Python 3 [datakurre]

1.0.3 (2012-05-31)

• Use zope.browserpage. [hannosch]
• Defensive UUID assignment in addAttributeUUID() handler: keep existing UUID value if handler called more than once, except in case of object copy event, where original and destination should have distinct UUID. [seanupton]

1.0.2 - 2011-10-18

• Generate UUID without dashes. [elro]

1.0.1 - 2011-05-20

• Relicense under modified BSD license. See

  [davisagli]

1.0 - 2011-05-13

• Release 1.0 Final [esteele]
• Add MANIFEST.in. [WouterVH]

1.0b2 - 2011-01-03

• Add MutableUUID component [toutpt]

1.0b1 - 2010-11-27

• Initial release