Adapter Registry

Usage of the adapter registry is documented in Adapter Registry.

The adapter registry’s API is defined by zope.interface.interfaces.IAdapterRegistry:

interface zope.interface.interfaces.IAdapterRegistry

Provide an interface-based registry for adapters

This registry registers objects that are in some sense “from” a sequence of specification to an interface and a name.

No specific semantics are assumed for the registered objects, however, the most common application will be to register factories that adapt objects providing required specifications to a provided interface.

register(required, provided, name, value)

Register a value

A value is registered for a sequence of required specifications, a provided interface, and a name, which must be text.

registered(required, provided, name='')

Return the component registered for the given interfaces and name

name must be text.

Unlike the lookup method, this methods won’t retrieve components registered for more specific required interfaces or less specific provided interfaces.

If no component was registered exactly for the given interfaces and name, then None is returned.

lookup(required, provided, name='', default=None)

Lookup a value

A value is looked up based on a sequence of required specifications, a provided interface, and a name, which must be text.

queryMultiAdapter(objects, provided, name='', default=None)

Adapt a sequence of objects to a named, provided, interface

lookup1(required, provided, name='', default=None)

Lookup a value using a single required interface

A value is looked up based on a single required specifications, a provided interface, and a name, which must be text.

queryAdapter(object, provided, name='', default=None)

Adapt an object using a registered adapter factory.

adapter_hook(provided, object, name='', default=None)

Adapt an object using a registered adapter factory.

name must be text.

lookupAll(required, provided)

Find all adapters from the required to the provided interfaces

An iterable object is returned that provides name-value two-tuples.

names(required, provided)

Return the names for which there are registered objects

subscribe(required, provided, subscriber)

Register a subscriber

A subscriber is registered for a sequence of required specifications, a provided interface, and a name.

Multiple subscribers may be registered for the same (or equivalent) interfaces.

Changed in version 5.1.1: Correct the method signature to remove the name parameter. Subscribers have no names.

subscribed(required, provided, subscriber)

Check whether the object subscriber is registered directly with this object via a previous call to subscribe(required, provided, subscriber).

If the subscriber, or one equal to it, has been subscribed, for the given required sequence and provided interface, return that object. (This does not guarantee whether the subscriber itself is returned, or an object equal to it.)

If it has not, return None.

Unlike subscriptions(), this method won’t retrieve components registered for more specific required interfaces or less specific provided interfaces.

New in version 5.3.0.

subscriptions(required, provided)

Get a sequence of subscribers.

Subscribers for a sequence of required interfaces, and a provided interface are returned. This takes into account subscribers registered with this object, as well as those registered with base adapter registries in the resolution order, and interfaces that extend provided.

Changed in version 5.1.1: Correct the method signature to remove the name parameter. Subscribers have no names.

subscribers(objects, provided)

Get a sequence of subscription adapters.

This is like subscriptions(), but calls the returned subscribers with objects (and optionally returns the results of those calls), instead of returning the subscribers directly.

Parameters:

• objects – A sequence of objects; they will be used to determine the required argument to subscriptions().

• provided – A single interface, or None, to pass as the provided parameter to subscriptions(). If an interface is given, the results of calling each returned subscriber with the the objects are collected and returned from this method; each result should be an object implementing the provided interface. If None, the resulting subscribers are still called, but the results are ignored.

Returns:

A sequence of the results of calling the subscribers if provided is not None. If there are no registered subscribers, or provided is None, this will be an empty sequence.

Changed in version 5.1.1: Correct the method signature to remove the name parameter. Subscribers have no names.

The concrete implementations of IAdapterRegistry provided by this package allows for some customization opportunities.

class zope.interface.adapter.BaseAdapterRegistry(bases=())

Bases: object

A basic implementation of the data storage and algorithms required for a zope.interface.interfaces.IAdapterRegistry.

Subclasses can set the following attributes to control how the data is stored; in particular, these hooks can be helpful for ZODB persistence. They can be class attributes that are the named (or similar) type, or they can be methods that act as a constructor for an object that behaves like the types defined here; this object will not assume that they are type objects, but subclasses are free to do so:

_sequenceType = list

This is the type used for our two mutable top-level “byorder” sequences. Must support mutation operations like append() and del seq[index]. These are usually small (< 10). Although at least one of them is accessed when performing lookups or queries on this object, the other is untouched. In many common scenarios, both are only required when mutating registrations and subscriptions (like what zope.interface.interfaces.IComponents.registerUtility() does). This use pattern makes it an ideal candidate to be a PersistentList.

_leafSequenceType = tuple

This is the type used for the leaf sequences of subscribers. It could be set to a PersistentList to avoid many unnecessary data loads when subscribers aren’t being used. Mutation operations are directed through _addValueToLeaf() and _removeValueFromLeaf(); if you use a mutable type, you’ll need to override those.

_mappingType = dict

This is the mutable mapping type used for the keyed mappings. A PersistentMapping could be used to help reduce the number of data loads when the registry is large and parts of it are rarely used. Further reductions in data loads can come from using a OOBTree, but care is required to be sure that all required/provided values are fully ordered (e.g., no required or provided values that are classes can be used).

_providedType = dict

This is the mutable mapping type used for the _provided mapping. This is separate from the generic mapping type because the values are always integers, so one might choose to use a more optimized data structure such as a OIBTree. The same caveats regarding key types apply as for _mappingType.

It is possible to also set these on an instance, but because of the need to potentially also override _addValueToLeaf() and _removeValueFromLeaf(), this may be less useful in a persistent scenario; using a subclass is recommended.

Changed in version 5.3.0: Add support for customizing the way internal data structures are created.

Changed in version 5.3.0: Add methods rebuild(), allRegistrations() and allSubscriptions().

_setBases(bases)

If subclasses need to track when __bases__ changes, they can override this method.

Subclasses must still call this method.

_sequenceType

alias of list

_leafSequenceType

alias of tuple

_mappingType

alias of dict

_providedType

alias of dict

_addValueToLeaf(existing_leaf_sequence, new_item)

Add the value new_item to the existing_leaf_sequence, which may be None.

Subclasses that redefine _leafSequenceType should override this method.

Parameters:

existing_leaf_sequence – If existing_leaf_sequence is not None, it will be an instance of _leafSequenceType. (Unless the object has been unpickled from an old pickle and the class definition has changed, in which case it may be an instance of a previous definition, commonly a tuple.)

Returns:

This method returns the new value to be stored. It may mutate the sequence in place if it was not None and the type is mutable, but it must also return it.

New in version 5.3.0.

_removeValueFromLeaf(existing_leaf_sequence, to_remove)

Remove the item to_remove from the (non-None, non-empty) existing_leaf_sequence and return the mutated sequence.

If there is more than one item that is equal to to_remove they must all be removed.

Subclasses that redefine _leafSequenceType should override this method. Note that they can call this method to help in their implementation; this implementation will always return a new tuple constructed by iterating across the existing_leaf_sequence and omitting items equal to to_remove.

Parameters:

existing_leaf_sequence – As for _addValueToLeaf, probably an instance of _leafSequenceType but possibly an older type; never None.

Returns:

A version of existing_leaf_sequence with all items equal to to_remove removed. Must not return None. However, returning an empty object, even of another type such as the empty tuple, () is explicitly allowed; such an object will never be stored.

New in version 5.3.0.

allRegistrations()

Yields tuples (required, provided, name, value) for all the registrations that this object holds.

These tuples could be passed as the arguments to the register() method on another adapter registry to duplicate the registrations this object holds.

New in version 5.3.0.

allSubscriptions()

Yields tuples (required, provided, value) for all the subscribers that this object holds.

These tuples could be passed as the arguments to the subscribe() method on another adapter registry to duplicate the registrations this object holds.

New in version 5.3.0.

rebuild()

Rebuild (and replace) all the internal data structures of this object.

This is useful, especially for persistent implementations, if you suspect an issue with reference counts keeping interfaces alive even though they are no longer used.

It is also useful if you or a subclass change the data types (_mappingType and friends) that are to be used.

This method replaces all internal data structures with new objects; it specifically does not re-use any storage.

New in version 5.3.0.

class zope.interface.adapter.AdapterRegistry(bases=())

Bases: BaseAdapterRegistry

A full implementation of IAdapterRegistry that adds support for sub-registries.

class zope.interface.adapter.VerifyingAdapterRegistry(bases=())

Bases: BaseAdapterRegistry

The most commonly-used adapter registry.