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[source]
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.Added 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 tosubscriptions()
. 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. IfNone
, 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 isNone
, 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=())[source]
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()
anddel 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 whatzope.interface.interfaces.IComponents.registerUtility()
does). This use pattern makes it an ideal candidate to be aPersistentList
.- _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 aOOBTree
, 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 aOIBTree
. 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()
andallSubscriptions()
.- _setBases(bases)[source]
If subclasses need to track when
__bases__
changes, they can override this method.Subclasses must still call this method.
- _addValueToLeaf(existing_leaf_sequence, new_item)[source]
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 atuple
.)- 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.
Added in version 5.3.0.
- _removeValueFromLeaf(existing_leaf_sequence, to_remove)[source]
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; neverNone
.- 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.
Added in version 5.3.0.
- allRegistrations()[source]
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.Added in version 5.3.0.
- allSubscriptions()[source]
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.Added in version 5.3.0.
- rebuild()[source]
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.
Added in version 5.3.0.
- class zope.interface.adapter.AdapterRegistry(bases=())[source]
Bases:
BaseAdapterRegistry
A full implementation of
IAdapterRegistry
that adds support for sub-registries.
- class zope.interface.adapter.VerifyingAdapterRegistry(bases=())[source]
Bases:
BaseAdapterRegistry
The most commonly-used adapter registry.