Component Registries¶
The component registry’s API is defined by
zope.interface.interfaces.IComponents
:
- interface zope.interface.interfaces.IComponentLookup[source]¶
Component Manager for a Site
This object manages the components registered at a particular site. The definition of a site is intentionally vague.
- adapters¶
Adapter Registry to manage all registered adapters.
- utilities¶
Adapter Registry to manage all registered utilities.
- queryAdapter(object, interface, name='', default=None)¶
Look for a named adapter to an interface for an object
If a matching adapter cannot be found, returns the default.
- getAdapter(object, interface, name='')¶
Look for a named adapter to an interface for an object
If a matching adapter cannot be found, a
ComponentLookupError
is raised.
- queryMultiAdapter(objects, interface, name='', default=None)¶
Look for a multi-adapter to an interface for multiple objects
If a matching adapter cannot be found, returns the default.
- getMultiAdapter(objects, interface, name='')¶
Look for a multi-adapter to an interface for multiple objects
If a matching adapter cannot be found, a
ComponentLookupError
is raised.
- getAdapters(objects, provided)¶
Look for all matching adapters to a provided interface for objects
Return an iterable of name-adapter pairs for adapters that provide the given interface.
- subscribers(objects, provided)¶
Get subscribers
Subscribers are returned that provide the provided interface and that depend on and are computed from the sequence of required objects.
- handle(*objects)¶
Call handlers for the given objects
Handlers registered for the given objects are called.
- queryUtility(interface, name='', default=None)¶
Look up a utility that provides an interface.
If one is not found, returns default.
- getUtilitiesFor(interface)¶
Look up the registered utilities that provide an interface.
Returns an iterable of name-utility pairs.
- getAllUtilitiesRegisteredFor(interface)¶
Return all registered utilities for an interface
This includes overridden utilities.
An iterable of utility instances is returned. No names are returned.
- interface zope.interface.interfaces.IComponentRegistry[source]¶
Register components
- registerUtility(component=None, provided=None, name='', info='', factory=None)¶
Register a utility
- Parameters:
factory – Factory for the component to be registered.
component – The registered component
provided – This is the interface provided by the utility. If the component provides a single interface, then this argument is optional and the component-implemented interface will be used.
name – The utility name.
info – An object that can be converted to a string to provide information about the registration.
Only one of component and factory can be used.
A
IRegistered
event is generated with anIUtilityRegistration
.
- unregisterUtility(component=None, provided=None, name='', factory=None)¶
Unregister a utility
- Returns:
A boolean is returned indicating whether the registry was changed. If the given component is None and there is no component registered, or if the given component is not None and is not registered, then the function returns False, otherwise it returns True.
- Parameters:
factory – Factory for the component to be unregistered.
component – The registered component The given component can be None, in which case any component registered to provide the given provided interface with the given name is unregistered.
provided – This is the interface provided by the utility. If the component is not None and provides a single interface, then this argument is optional and the component-implemented interface will be used.
name – The utility name.
Only one of component and factory can be used. An
IUnregistered
event is generated with anIUtilityRegistration
.
- registeredUtilities()¶
Return an iterable of
IUtilityRegistration
instances.These registrations describe the current utility registrations in the object.
- registerAdapter(factory, required=None, provided=None, name='', info='')¶
Register an adapter factory
- Parameters:
factory – The object used to compute the adapter
required – This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s
__component_adapts__
attribute will be used. The__component_adapts__
attribute is normally set in class definitions using theadapter
decorator. If the factory doesn’t have a__component_adapts__
adapts attribute, then this argument is required.provided – This is the interface provided by the adapter and implemented by the factory. If the factory implements a single interface, then this argument is optional and the factory-implemented interface will be used.
name – The adapter name.
info – An object that can be converted to a string to provide information about the registration.
A
IRegistered
event is generated with anIAdapterRegistration
.
- unregisterAdapter(factory=None, required=None, provided=None, name='')¶
Unregister an adapter factory
- Returns:
A boolean is returned indicating whether the registry was changed. If the given component is None and there is no component registered, or if the given component is not None and is not registered, then the function returns False, otherwise it returns True.
- Parameters:
factory – This is the object used to compute the adapter. The factory can be None, in which case any factory registered to implement the given provided interface for the given required specifications with the given name is unregistered.
required – This is a sequence of specifications for objects to be adapted. If the factory is not None and the required arguments is omitted, then the value of the factory’s __component_adapts__ attribute will be used. The __component_adapts__ attribute attribute is normally set in class definitions using adapts function, or for callables using the adapter decorator. If the factory is None or doesn’t have a __component_adapts__ adapts attribute, then this argument is required.
provided – This is the interface provided by the adapter and implemented by the factory. If the factory is not None and implements a single interface, then this argument is optional and the factory-implemented interface will be used.
name – The adapter name.
An
IUnregistered
event is generated with anIAdapterRegistration
.
- registeredAdapters()¶
Return an iterable of
IAdapterRegistration
instances.These registrations describe the current adapter registrations in the object.
- registerSubscriptionAdapter(factory, required=None, provides=None, name='', info='')¶
Register a subscriber factory
- Parameters:
factory – The object used to compute the adapter
required – This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s
__component_adapts__
attribute will be used. The__component_adapts__
attribute is normally set using the adapter decorator. If the factory doesn’t have a__component_adapts__
adapts attribute, then this argument is required.provided – This is the interface provided by the adapter and implemented by the factory. If the factory implements a single interface, then this argument is optional and the factory-implemented interface will be used.
name –
The adapter name.
Currently, only the empty string is accepted. Other strings will be accepted in the future when support for named subscribers is added.
info – An object that can be converted to a string to provide information about the registration.
A
IRegistered
event is generated with anISubscriptionAdapterRegistration
.
- unregisterSubscriptionAdapter(factory=None, required=None, provides=None, name='')¶
Unregister a subscriber factory.
- Returns:
A boolean is returned indicating whether the registry was changed. If the given component is None and there is no component registered, or if the given component is not None and is not registered, then the function returns False, otherwise it returns True.
- Parameters:
factory – This is the object used to compute the adapter. The factory can be None, in which case any factories registered to implement the given provided interface for the given required specifications with the given name are unregistered.
required – This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s
__component_adapts__
attribute will be used. The__component_adapts__
attribute is normally set using the adapter decorator. If the factory doesn’t have a__component_adapts__
adapts attribute, then this argument is required.provided – This is the interface provided by the adapter and implemented by the factory. If the factory is not None implements a single interface, then this argument is optional and the factory-implemented interface will be used.
name –
The adapter name.
Currently, only the empty string is accepted. Other strings will be accepted in the future when support for named subscribers is added.
An
IUnregistered
event is generated with anISubscriptionAdapterRegistration
.
- registeredSubscriptionAdapters()¶
Return an iterable of
ISubscriptionAdapterRegistration
instances.These registrations describe the current subscription adapter registrations in the object.
- registerHandler(handler, required=None, name='', info='')¶
Register a handler.
A handler is a subscriber that doesn’t compute an adapter but performs some function when called.
- Parameters:
handler – The object used to handle some event represented by the objects passed to it.
required – This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s
__component_adapts__
attribute will be used. The__component_adapts__
attribute is normally set using the adapter decorator. If the factory doesn’t have a__component_adapts__
adapts attribute, then this argument is required.name –
The handler name.
Currently, only the empty string is accepted. Other strings will be accepted in the future when support for named handlers is added.
info – An object that can be converted to a string to provide information about the registration.
A
IRegistered
event is generated with anIHandlerRegistration
.
- unregisterHandler(handler=None, required=None, name='')¶
Unregister a handler.
A handler is a subscriber that doesn’t compute an adapter but performs some function when called.
- Returns:
A boolean is returned indicating whether the registry was changed.
- Parameters:
handler – This is the object used to handle some event represented by the objects passed to it. The handler can be None, in which case any handlers registered for the given required specifications with the given are unregistered.
required – This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s
__component_adapts__
attribute will be used. The__component_adapts__
attribute is normally set using the adapter decorator. If the factory doesn’t have a__component_adapts__
adapts attribute, then this argument is required.name –
The handler name.
Currently, only the empty string is accepted. Other strings will be accepted in the future when support for named handlers is added.
An
IUnregistered
event is generated with anIHandlerRegistration
.
- registeredHandlers()¶
Return an iterable of
IHandlerRegistration
instances.These registrations describe the current handler registrations in the object.
- interface zope.interface.interfaces.IComponents[source]¶
Extends:
zope.interface.interfaces.IComponentLookup
,zope.interface.interfaces.IComponentRegistry
Component registration and access
One default implementation of IComponents
is provided.
- class zope.interface.registry.Components(name='', bases=())[source]¶
Bases:
object
- rebuildUtilityRegistryFromLocalCache(rebuild=False)[source]¶
Emergency maintenance method to rebuild the
.utilities
registry from the local copy maintained in this object, or detect the need to do so.Most users will never need to call this, but it can be helpful in the event of suspected corruption.
By default, this method only checks for corruption. To make it actually rebuild the registry, pass
True
for rebuild.- Parameters:
rebuild (bool) – If set to
True
(not the default), this method will actually register and subscribe utilities in the registry as needed to synchronize with the local cache.- Returns:
A dictionary that’s meant as diagnostic data. The keys and values may change over time. When called with a false rebuild, the keys
"needed_registered"
and"needed_subscribed"
will be non-zero if any corruption was detected, but that will not be corrected.
Added in version 5.3.0.
Events¶
Adding and removing components from the component registry create registration and unregistration events. Like most things, they are defined by an interface and a default implementation is provided.
Registration¶
- interface zope.interface.interfaces.IObjectEvent[source]¶
An event related to an object.
The object that generated this event is not necessarily the object referred to by location.
- object¶
The subject of the event.
- interface zope.interface.interfaces.IRegistrationEvent[source]¶
Extends:
zope.interface.interfaces.IObjectEvent
An event that involves a registration
- interface zope.interface.interfaces.IRegistered[source]¶
Extends:
zope.interface.interfaces.IRegistrationEvent
A component or factory was registered
- interface zope.interface.interfaces.IUnregistered[source]¶
Extends:
zope.interface.interfaces.IRegistrationEvent
A component or factory was unregistered
Details¶
These are all types of IObjectEvent
, meaning they have an object
that provides specific details about the event. Component registries
create detail objects for four types of components they manage.
All four share a common base interface.
- interface zope.interface.interfaces.IRegistration[source]¶
A registration-information object
- registry¶
The registry having the registration
- name¶
The registration name
- info¶
Information about the registration
This is information deemed useful to people browsing the configuration of a system. It could, for example, include commentary or information about the source of the configuration.
Utilities
- interface zope.interface.interfaces.IUtilityRegistration[source]¶
Extends:
zope.interface.interfaces.IRegistration
Information about the registration of a utility
- factory¶
The factory used to create the utility. Optional.
- component¶
The object registered
- provided¶
The interface provided by the component
Handlers
- interface zope.interface.interfaces.IHandlerRegistration[source]¶
Extends:
zope.interface.interfaces.IRegistration
- handler¶
An object called used to handle an event
- required¶
The handled interfaces
This is a sequence of interfaces handled by the registered handler. The handler will be caled with a sequence of objects, as positional arguments, that provide these interfaces.
- class zope.interface.registry.HandlerRegistration(registry, required, name, handler, doc)[source]¶
Bases:
AdapterRegistration
Adapters
For ease of implementation, a shared base class is used for these events. It should not be referenced by clients, but it is documented to show the common attributes.
- interface zope.interface.interfaces._IBaseAdapterRegistration[source]¶
Extends:
zope.interface.interfaces.IRegistration
Information about the registration of an adapter
- factory¶
The factory used to create adapters
- required¶
The adapted interfaces
This is a sequence of interfaces adapters by the registered factory. The factory will be caled with a sequence of objects, as positional arguments, that provide these interfaces.
- provided¶
The interface provided by the adapters.
This interface is implemented by the factory
- interface zope.interface.interfaces.IAdapterRegistration[source]¶
Extends:
zope.interface.interfaces._IBaseAdapterRegistration
Information about the registration of an adapter
- class zope.interface.registry.AdapterRegistration(registry, required, provided, name, component, doc)[source]¶
Bases:
object
- interface zope.interface.interfaces.ISubscriptionAdapterRegistration[source]¶
Extends:
zope.interface.interfaces._IBaseAdapterRegistration
Information about the registration of a subscription adapter
- class zope.interface.registry.SubscriptionRegistration(registry, required, provided, name, component, doc)[source]¶
Bases:
AdapterRegistration
Exceptions¶
- class zope.interface.interfaces.ComponentLookupError[source]¶
Bases:
LookupError
A component could not be found.