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 comuted 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 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[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

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

class zope.interface.interfaces.Registered(object)[source]

Bases: RegistrationEvent

interface zope.interface.interfaces.IUnregistered[source]

Extends: zope.interface.interfaces.IRegistrationEvent

A component or factory was unregistered

class zope.interface.interfaces.Unregistered(object)[source]

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

  • Utilties

    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

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

    Bases: object

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

class zope.interface.interfaces.Invalid[source]

Bases: Exception

A component doesn’t satisfy a promise.