registries.registry

Definitions of registries.

Registries are collections that keep track of unique objects. There are three types provided by default:

1. Registry: The main class for defining a registry.

2. EntryPointRegistry: A registry backed by Python Entrypoints.

3. OrderedRegistry: A registry that tracks the order of items.

All registries are thread-safe, extensible via hooks, and provide type hints.

New in version 1.0.

Classes

EntryPointRegistry()	A registry that auto-populates from an entry-point.
OrderedRegistry()	A registry that keeps track of registration order.
Registry()	An item registry.
RegistryState(value[, names, module, ...])	The operations state of a registry.

class registries.registry.RegistryState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The operations state of a registry.

New in version 1.0.

PENDING = 0

The registry is pending setup.

POPULATING = 1

The registry is in the process of populating default items.

READY = 2

The registry is populated and ready to be used.

class registries.registry.Registry

Bases: Generic[RegistryItemType]

An item registry.

Item registries hold a set of objects that can be looked up by attributes. Each item is guaranteed to be unique and not share these attributes with any other item in the registry.

Registries default to holding arbitrary objects. To limit objects to a specific type, specify a type when subclassing. For example:

class MyRegistry(Registry[MyItemType]):
    ...

New in version 1.0.

lookup_attrs: Sequence[str] = []

A list of attributes that items can be looked up by.

already_registered_error_cls

Error used when trying to register an already-registered item.

Consumers can reference this attribute when catching exceptions.

Subclasses can override this with a subclass of AlreadyRegisteredError to provide custom error messages.

alias of AlreadyRegisteredError[RegistryItemType]

attr_not_found_unregistration_error_cls

Error used when failing to unregister by attribute.

Consumers can reference this attribute when catching exceptions.

Subclasses can override this with a subclass of UnregistrationAttrNotFoundError to provide custom error messages.

alias of AttrNotFoundUnregistrationError

invalid_item_registration_error_cls

Error used when failing to register an invalid item.

Consumers can reference this attribute when catching exceptions.

Subclasses can override this with a subclass of InvalidItemRegistrationError to provide custom error messages.

alias of InvalidItemRegistrationError[RegistryItemType]

item_not_found_lookup_error_cls

Error used when failing to look up an unregistered item.

Consumers can reference this attribute when catching exceptions.

Subclasses can override this with a subclass of ItemNotFoundLookupError to provide custom error messages.

alias of ItemNotFoundLookupError

item_not_found_unregistration_error_cls

Error used when failing to unregister by item.

Consumers can reference this attribute when catching exceptions.

Subclasses can override this with a subclass of UnregistrationItemNotFoundError to provide #: custom error messages.

alias of ItemNotFoundUnregistrationError[RegistryItemType]

registration_conflict_error_cls

Error used when failing to register a conflicting item.

Consumers can reference this attribute when catching exceptions.

Subclasses can override this with a subclass of RegistrationConflictError to provide custom error messages.

alias of RegistrationConflictError[RegistryItemType]

unsupported_registry_attr_error_cls

Error used when referencing invalid attribute names.

Consumers can reference this attribute when catching exceptions.

Subclasses can override this with a subclass of UnsupportedRegistryAttributeError to provide custom error messages.

alias of UnsupportedRegistryAttributeError

__init__() → None

Initialize the registry.

state: RegistryState

The current state of the registry.

get(*attr_args, **attr_kwargs) → RegistryItemType

Return an item by its attribute value.

Parameters:

• *attr_args (tuple) –

  A single positional value for the query.

  This may be provided instead of attr_kwargs if the registry supports only a single lookup attribute. In this case, exactly one argument may be supplied.

• **query_kwarga (dict) –

  An attribute/value query for an item. The query used to look up the provided item.

  This must contain exactly one key/value pair.

  This may be provided instead of attr_args to look up an object using an attribute/value match. In this case, exactly one argument may be supplied.

Returns:

The registered item.

Return type:

object

Raises:

• TypeError – The query arguments were invalid. A wrong combination of positional and keyword arguments were provided, or a wrong number of arguments. This class is the standard class used for invalid or missing function arguments.

• registries.errors.ItemNotFoundLookupError – An item matching the lookup attribute and value was not found.

• registries.errors.UnsupportedRegistryAttributeError – The provided lookup attribute is not supported on this type of registry.

get_or_none(*attr_args, **attr_kwargs) → RegistryItemType | None

Return the requested registered item, or None if not found.

Parameters:

• *attr_args (tuple) –

  A single positional value for the query.

  This may be provided instead of attr_kwargs if the registry supports only a single lookup attribute. In this case, exactly one argument may be supplied.

• **query_kwarga (dict) –

  An attribute/value query for an item. The query used to look up the provided item.

  This must contain exactly one key/value pair.

  This may be provided instead of attr_args to look up an object using an attribute/value match. In this case, exactly one argument may be supplied.

Returns:

The matching registered item, if found. Otherwise, None is returned.

Return type:

object

Raises:

• TypeError – The query arguments were invalid. A wrong combination of positional and keyword arguments were provided, or a wrong number of arguments. This class is the standard class used for invalid or missing function arguments.

• registries.errors.UnsupportedRegistryAttributeError – The provided lookup attribute is not supported on this type of registry.

register(item: RegistryItemType) → None

Register an item.

Parameters:

item (object) – The item to register with the class.

Raises:

• registries.errors.AlreadyRegisteredError – This item was already registered.

• registries.errors.BaseRegistrationError – General exception used for any registration errors.

• registries.errors.InvalidItemRegistrationError – The item is missing a required lookup attribute.

• registries.errors.RegistrationConflictError – Another item with the same lookup attributes was already registered.

unregister_by_attr(*attr_args, **attr_kwargs) → None

Unregister an item from the registry by an attribute.

Parameters:

• **attr_args (tuple) –

  A single positional value for the query.

  This may be provided instead of attr_kwargs if the registry supports only a single lookup attribute. In this case, exactly one argument may be supplied.

• **query_kwarga (dict) –

  An attribute/value query for an item. The query used to look up the provided item.

  This must contain exactly one key/value pair.

  This may be provided instead of attr_args to look up an object using an attribute/value match. In this case, exactly one argument may be supplied.

Raises:

• registries.errors.AttrNotFoundUnregistrationError – An item matching the lookup attribute was not found.

• registries.errors.BaseUnregistrationError – General exception used for any unregistration errors.

• registries.errors.UnsupportedRegistryAttributeError – The provided lookup attribute is not supported on this type of registry.

unregister(item: RegistryItemType) → None

Unregister an item from the registry.

Parameters:

item (object) –

The item to unregister.

This must be present in the registry.

Raises:

• registries.errors.BaseUnregistrationError – General exception used for any unregistration errors.

• registries.errors.ItemNotFoundUnregistrationError – The item was not registered.

populate() → None

Ensure the registry is populated.

Calling this method when the registry is populated will have no effect.

get_defaults() → Iterable[RegistryItemType]

Return the default items for the registry.

This method should be overridden by a subclass.

It may be return an explicit list or yield items one-by-one.

Returns:

The default items for the registry.

Return type:

list

reset() → None

Unregister all items and mark the registry unpopulated.

This will result in the registry containing no entries. Any call to a method that would populate the registry will repopulate it.

on_item_registering(item: RegistryItemType, /) → None

Handle extra steps before registering an item.

This can be used by subclasses to perform preparation steps before registering an item. It’s run before the item is validated and then registered.

Validation can be performed in this method.

The method is thread-safe.

Parameters:

item (object) – The item to register.

Raises:

registries.errors.BaseRegistrationError – There’s an error registering this item.

on_item_registered(item: RegistryItemType, /) → None

Handle extra steps after registering an item.

This can be used by subclasses to perform additional steps when an item is registered. It’s run after the main registration occurs.

The method is thread-safe.

Parameters:

item (object) – The item that was registered.

on_item_unregistering(item: RegistryItemType, /) → None

Handle extra steps before unregistering an item.

This can be used by subclasses to perform additional steps before validating and unregistering an item.

The method is thread-safe.

Parameters:

item (object) – The item to unregister.

Raises:

registries.errors.BaseUnregistrationError – There’s an error unregistering this item.

on_item_unregistered(item: RegistryItemType, /) → None

Handle extra steps after unregistering an item.

This can be used by subclasses to perform additional steps when an item is unregistered. It’s run after the main unregistration occurs.

The method is thread-safe.

Parameters:

item (object) – The item that was unregistered.

on_populating() → None

Handle extra steps before a registry is populated.

This can be used by subclasses to perform additional steps before the registry is populated.

The method is thread-safe.

on_populated() → None

Handle extra steps after a registry is populated.

This can be used by subclasses to perform additional steps after the registry is populated. It’s run after the main population occurs.

The method is thread-safe.

on_resetting() → None

Handle extra steps before resetting the registry.

This can be used by subclasses to perform additional steps before the registry is reset. It’s run before the main reset operations occur.

The method is thread-safe.

on_reset() → None

Handle extra steps after a registry is reset.

This can be used by subclasses to perform additional steps after the registry is reset. It’s run after the main reset operations occur.

The method is thread-safe.

__iter__() → Iterator[RegistryItemType]

Iterate through all items in the registry.

This method does not provide a stable ordering.

Yields:

object – The items registered in this registry.

__len__() → int

Return the number of items in the registry.

Returns:

The number of items in the registry.

Return type:

int

__contains__(item: RegistryItemType) → bool

Return whether or not the item is contained in the registry.

Parameters:

item (object) – The item to look for.

Returns:

Whether or not the item is contained in the registry.

Return type:

bool

__orig_bases__ = (typing.Generic[~RegistryItemType],)

__parameters__ = (~RegistryItemType,)

class registries.registry.EntryPointRegistry

Bases: Registry[RegistryItemType]

A registry that auto-populates from an entry-point.

entry_point_group: ClassVar[str]

The entry point group name.

__init__() → None

Initialize the registry.

get_defaults() → Iterable[RegistryItemType]

Yield the values from the entry point.

Yields:

object – The object from the entry point.

process_value_from_entry_point(entry_point: EntryPoint) → RegistryItemType

Return the item to register from the entry point.

By default, this returns the loaded entry point. Subclasses can override this to return a more explicit result.

Parameters:

entry_point (importlib.metadata.EntryPoint) – The entry point.

Returns:

The processed entry point value.

Return type:

object

__orig_bases__ = (registries.registry.Registry[~RegistryItemType],)

__parameters__ = (~RegistryItemType,)

class registries.registry.OrderedRegistry

Bases: Registry[RegistryItemType]

A registry that keeps track of registration order.

__orig_bases__ = (registries.registry.Registry[~RegistryItemType],)

__parameters__ = (~RegistryItemType,)

__init__() → None

Initialize the registry.

on_item_registered(item: RegistryItemType, /) → None

Handle extra steps before registering an item.

This will place the item in sequential order.

Subclasses that override this to perform additional post-registration operations must first call this method.

Parameters:

item (object) – The item that was registered.

on_item_unregistered(item: RegistryItemType, /) → None

Handle extra steps after unregistering an item.

Subclasses that override this to perform additional post-unregistration operations must first call this method.

Parameters:

item (object) – The item that was unregistered.

__iter__() → Iterator[RegistryItemType]

Yield the items in the order they were registered.

Yields:

object – The registered items.

__getitem__(index: int) → RegistryItemType

Return an item by its registered index.

Parameters:

index (int) – The position at which the item was registered. This is 0-based and negative indices are supported.

Returns:

The requested item.

Return type:

object

Raises:

• IndexError – This exception is raised if the requested index is out of range.

• TypeError – This exception is raised if the requested index is not an integer.