Component Registries

The component registry’s API is defined by zope.interface.interfaces.IComponents:

interface zope.interface.interfaces.IComponentLookup

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

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 an IUtilityRegistration.

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 an IUtilityRegistration.

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 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.

• info – An object that can be converted to a string to provide information about the registration.

A IRegistered event is generated with an IAdapterRegistration.

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 an IAdapterRegistration.

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 an ISubscriptionAdapterRegistration.

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 an ISubscriptionAdapterRegistration.

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 an IHandlerRegistration.

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 an IHandlerRegistration.

registeredHandlers()

Return an iterable of IHandlerRegistration instances.

These registrations describe the current handler registrations in the object.

interface zope.interface.interfaces.IComponents

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=())

Bases: object

rebuildUtilityRegistryFromLocalCache(rebuild=False)

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

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

Extends: zope.interface.interfaces.IObjectEvent

An event that involves a registration

interface zope.interface.interfaces.IRegistered

Extends: zope.interface.interfaces.IRegistrationEvent

A component or factory was registered

class zope.interface.interfaces.Registered(object)

Bases: RegistrationEvent

interface zope.interface.interfaces.IUnregistered

Extends: zope.interface.interfaces.IRegistrationEvent

A component or factory was unregistered

class zope.interface.interfaces.Unregistered(object)

Bases: RegistrationEvent

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

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

  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

  class zope.interface.registry.UtilityRegistration(registry, provided, name, component, doc, factory=None)

  Bases: object

• Handlers

  interface zope.interface.interfaces.IHandlerRegistration

  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)

  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

  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

  Extends: zope.interface.interfaces._IBaseAdapterRegistration

  Information about the registration of an adapter

  class zope.interface.registry.AdapterRegistration(registry, required, provided, name, component, doc)

  Bases: object

  interface zope.interface.interfaces.ISubscriptionAdapterRegistration

  Extends: zope.interface.interfaces._IBaseAdapterRegistration

  Information about the registration of a subscription adapter

  class zope.interface.registry.SubscriptionRegistration(registry, required, provided, name, component, doc)

  Bases: AdapterRegistration

Exceptions

class zope.interface.interfaces.ComponentLookupError

Bases: LookupError

A component could not be found.

class zope.interface.interfaces.Invalid

Bases: Exception

A component doesn’t satisfy a promise.