What is zc.intid?¶

zc.intid provides an reduced conflict integer ID utility.

Reference¶

Interfaces¶

Interfaces for the unique id utility.

Note that most of these interfaces present identical method signatures to those of their zope.intid counterparts. This includes everything that comprises the IIntIds interface.

Note that the contracts for these APIs differs, primarily in not requiring zope.keyreference.interfaces.IKeyReference support.

The IIntIdsSubclass and event interfaces are new.

interface zc.intid.IIntIdsManage[source]¶

Some methods used by the view.

__len__()¶: Return the number of objects indexed.

items()¶: Return a list of (id, object) pairs.

interface zc.intid.IIntIds[source]¶

Extends: zc.intid.IIntIdsSet, zc.intid.IIntIdsQuery, zc.intid.IIntIdsManage

A utility that assigns unique ids to objects.

Allows to query object by id and id by object.

interface zc.intid.IIntIdsSubclass[source]¶

Additional interface that subclasses can usefully use.

family¶

BTree family used for this id utility.

This will be either BTree.family32 or BTree.family64.

This may not be modified, but may be used to create additional structures of the same integer family as the refs structure.

refs¶

BTree mapping from id to object.

Subclasses can use this to determine whether an id has already been assigned.

This should not be directly modified by subclasses.

generateId(ob)¶

Return a new iid that isn’t already used.

ob is the object the id is being generated for.

The default behavior is to generate arbitrary integers without reference to the objects they’re generated for.

This method may be overriden.

interface zc.intid.IIdEvent[source]¶

Generic base interface for IntId-related events

object¶: The object related to this event

idmanager¶: The int id utility generating the event.

id¶: The id that is being assigned or unassigned.

interface zc.intid.IIdRemovedEvent[source]¶

Extends: zc.intid.IIdEvent

A unique id will be removed.

The event is published before the unique id is removed from the utility so that the indexing objects can unindex the object.

interface zc.intid.IIdAddedEvent[source]¶

Extends: zc.intid.IIdEvent

A unique id has been added.

The event gets sent when an object is registered in a unique id utility.

interface zc.intid.ISubscriberEvent[source]¶

An event fired by the subscribers in relation to another event.

object¶: The object related to this event

original_event¶: The ObjectEvent related to this event

interface zc.intid.IAfterIdAddedEvent[source]¶

Extends: zc.intid.ISubscriberEvent

Fired after all utilities have registered unique ids.

This event is guaranteed to be the last event fired by the subscribers that register ids. It will be fired exactly once, no matter how many utilities registered ids.

idmap¶: The dictionary that holds an (utility -> id) mapping of created ids

interface zc.intid.IBeforeIdRemovedEvent[source]¶

Extends: zc.intid.ISubscriberEvent

Fired before any utility removes an object’s unique ID.

This event is guaranteed to be the first event fired by the subscriber that removes IDs. It will only be fired if at least one utility will remove an ID.

class zc.intid.BeforeIdRemovedEvent(o, event)[source]¶

Bases: object

The event which is published before the unique id is removed from the utility so that the catalogs can unindex the object.

class zc.intid.AfterIdAddedEvent(o, event, idmap=None)[source]¶

Bases: object

The event which gets sent when an object is registered in a unique id utility.

Implementation¶

Unique id utility.

This utility assigns unique integer ids to objects and allows lookups by object and by id.

This functionality can be used in cataloging.

class zc.intid.utility.IntIds(attribute, family=None)[source]¶

Bases: persistent.Persistent

This utility provides a two way mapping between objects and integer ids.

The objects are stored directly in the internal structures.

generateId(ob)[source]¶

Generate an id which is not yet taken.

This tries to allocate sequential ids so they fall into the same BTree bucket, and randomizes if it stumbles upon a used one.

Lifecycle Event Subscribers¶

A set of subscribers for the object zope.lifecycle events.

There are two key differences from the subscribers that come with the zope.intid package.

This does not register/unregister a zope.keyreference.IKeyReference with the intid utilities. Instead, it registers the actual object, and the events that are broadcast are broadcast holding the actual object.

IKeyReferenceces, especially KeyReferenceToPersistent, are used for a few reasons. First, they provide a stable, object-identity-based pointer to objects. To be identity based, this pointer is independent of the equality and hashing algorithms of the underlying object. Identity-based comparisons are necessary for the classic zope.intid utility implementation which uses a second OIBTree to maintain the backreferece from object to assigned intid (clearly you don’t want two non-identical objects which happen to compare equally now to get the same intid as that condition may change). Likewise, these references are all defined to be mutually comparable, no matter how they are implemented, a condition necessary for them to all work together in a OIBTree. Lastly, these references are meant to be comparable during ZODB conflict resolution (the original persistent objects probably won’t be), which, again, is a condition of the implementation using a OIBTree.

A consequence of avoiding these references is that generally persistent objects that are expected to have intids assigned should not be used as keys in an OxBTree or stored in an OOSet. Instead, all such data structures should use the integer variations (e.g., IISet), with the intid as the key.

As a corollary to the previous point, this module must be used with the intid utility from zc.intid.utility, (one implementing zc.intid.interfaces.IIntIds), which does not depend on being able to use objects as keys in a BTree.

Therefore, this module looks for utilities registered for that interface, not the zope.intid.interfaces.IIntIds.

We do, however, keep a few things in common:

We do ensure that the object can be adapted to zope.keyreference.interface.IKeyReference

In the common case of persistent objects, this will ensure that the object is in the database and has a jar and oid, common needs.
We do broadcast the events from zope.intid.interfaces, even though

the zc.intid package will broadcast its own events. There seems to be no reason not to and things like zope.catalog need them.

Configuring¶

To configure, you need to include subscribers.zcml:

<!-- configure.zcml -->
<!--
If we load zope.intid, we get subscribers for the Object events
that ensure all ILocation objects are registered/unregistered when
they are added/removed, plus another set of events when they
get/lose intids. This second set of events is meant to update
zope.catalog. A consequence of this is that ILocation objects must
be adaptable to KeyReferences when they are ObjectAdded (for
purposes of zope.intid, which we don't care about, but this also
ensures that they have ZODB Connections, which is good).

We cannot use these subscribers as-is due to the way the use IKeyReference
and try to register that. However, our subscribers *do* make sure that
the given objects can be adapted to IKeyReference because that's useful and
may be required by catalogs or other subscribers.
-->
<exclude package="zope.intid" file="subscribers.zcml" />
<include package="zope.intid" />

<include package="zope.keyreference" />

<!--
zc.intid fires a different set of events when objects gain/lose
intids.
-->
<include package="zc.intid" />

<!--
Make zc.intid utilities compatible with zope.intid utilities.
-->
<include package="zc.intid" file="zope-intid.zcml" />

<!-- To hook them up to the Object events, we need to include the file -->
<include package="zc.intid" file="subscribers.zcml" />

zc.intid.subscribers.addIntIdSubscriber(ob, event)[source]¶: Registers the object in all unique id utilities and fires an event for the catalogs. Notice that each utility will fire zc.intid.interfaces.IIntIdAddedEvent; this subscriber will then fire one single zope.intid.interfaces.IIntIdAddedEvent, followed by one single zc.intid.interfaces.IAfterIdAddedEvent; this gives a guaranteed order such that zope.catalog and other Zope event listeners will have fired.

zc.intid.subscribers.removeIntIdSubscriber(ob, event)[source]¶

Removes the unique ids registered for the object in all the unique id utilities.

Just before this happens (for the first time), an zc.intid.interfaces.IBeforeIdRemovedEvent is fired, followed by an zope.intid.interfaces.IIntIdRemovedEvent. Notice that this is fired before the id is actually removed from any utility, giving other subscribers time to do their cleanup.

Before each utility removes its registration, it will fire zc.intid.interfaces.IIntIdRemovedEvent. This gives a guaranteed order such that zope.catalog and other Zope event listeners will have fired.

zc.intid.subscribers.intIdEventNotify(event)[source]¶

Event subscriber to dispatch IntIdEvent to interested adapters.

See subscribers.zcml for its registrations (it handles two types of events).

Changes¶

2.0.0 (unreleased)¶

Add zope.lifecycleevent subscribers. You must include subscribers.zcml to use these. See https://github.com/zopefoundation/zc.intid/issues/5
Documentation is now hosted at http://zcintid.readthedocs.io
Add continuous integration testing for supported Python versions.
Add PyPy support.
Add Python 3 support.
Drop support for Python less than 2.7.
Remove ZODB3 dependency in favor of explicit dependencies on BTrees.
The zope-intid.zcml file included in this package now works to make the IntId utility from this package implement the zope.intids interface, if that package is installed.

1.0.1 (2011-06-27)¶

Make the behavior of the utility’s getId method consistent with zope.intid in regard to its handling of proxied objects.

1.0.0 (2011-02-21)¶

Initial release.

Development¶

zc.intid is hosted at GitHub:

https://github.com/zopefoundation/zc.intid/

Project URLs¶

http://pypi.python.org/pypi/zc.intid (PyPI entry and downloads)