djblets.registries.registry¶

Djblets registries.

Registries are collections that keep track of unique objects.

For information on writing registries, see the guide on writing registries.

RegistryErrorsDict¶

A mapping of error types to error messages.

The error messages should be localized.

New in version 3.3.

alias of Dict[str, Union[str, StrPromise]]

RegistryItemType¶

A generic type for items stored in a registry.

This can be used for subclasses of Registry, mixins, or other utility code that need to stay generic. In normal usage, an explicit type will be provided when subclassing instead.

New in version 3.1.

alias of TypeVar(‘RegistryItemType’)

ALREADY_REGISTERED: Final[str] = 'already_registered'¶: Error code indicating an item is already registered.

ATTRIBUTE_REGISTERED: Final[str] = 'attribute_registered'¶: Error code indicating a lookup attribute value is already registered.

INVALID_ATTRIBUTE: Final[str] = 'invalid_attribute'¶: Error code indicating a lookup attribute isn’t supported by the registry.

MISSING_ATTRIBUTE: Final[str] = 'missing_attribute'¶: Error code indicating an item is missing a lookup attribute.

UNREGISTER: Final[str] = 'unregister'¶: Error code indicating an item is not registered when trying to unregister.

NOT_REGISTERED: Final[str] = 'not_registered'¶: Error code indicating an item is not registered when looking it up.

LOAD_ENTRY_POINT: Final[str] = 'load_entry_point'¶: Error indicating an error looking up an item via a Python Entry Point.

DEFAULT_ERRORS: Final[Dict[str, Union[str, StrPromise]]] = {'already_registered': 'Could not register %(item)s: it is already registered.', 'attribute_registered': 'Could not register %(item)s: another item (%(duplicate)s) is already registered with %(attr_name)s = %(attr_value)s.', 'invalid_attribute': '"%(attr_name)s" is not a registered lookup attribute.', 'load_entry_point': 'Could not load entry point %(entry_point)s: %(error)s.', 'missing_attribute': 'Could not register %(item)s: it does not have a "%(attr_name)s" attribute.', 'not_registered': 'No item registered with %(attr_name)s = %(attr_value)s.', 'unregister': 'Could not unregister %(item)s: it is not registered.'}¶: Default error messages for registries.

class RegistryState(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

The operations state of a registry.

New in version 5.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 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]):
    ...

Changed in version 5.0:

Registries now use a reentrant lock when populating, resetting, registering items, or unregistering items.
Added state for determining the current registry state.
Deprecated populated.
Added new hooks for customizing registry behavior with thread-safe guarantees: * on_item_registering(), * on_item_registered(), * on_item_unregistering() * on_item_unregistered(), * on_populating() * on_populated(), * on_resetting() * on_reset().

Changed in version 3.1: Added support for specifying a registry item type when subclassing this registry.

item_name: Optional[str] = None¶

The name of the items being registered.

Type:: str

lookup_attrs: Sequence[str] = []¶

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

Type:: list of str

errors: Dict[str, Union[str, StrPromise]] = {}¶

Error formatting strings for exceptions.

Entries here override the global DEFAULT_ERRORS dictionary for error messages.

Type:: dict

default_errors: Dict[str, Union[str, StrPromise]] = {'already_registered': 'Could not register %(item)s: it is already registered.', 'attribute_registered': 'Could not register %(item)s: another item (%(duplicate)s) is already registered with %(attr_name)s = %(attr_value)s.', 'invalid_attribute': '"%(attr_name)s" is not a registered lookup attribute.', 'load_entry_point': 'Could not load entry point %(entry_point)s: %(error)s.', 'missing_attribute': 'Could not register %(item)s: it does not have a "%(attr_name)s" attribute.', 'not_registered': 'No item registered with %(attr_name)s = %(attr_value)s.', 'unregister': 'Could not unregister %(item)s: it is not registered.'}¶

The default error formatting strings.

If subclasses need to provide additional errors that can be overridden, they should copy DEFAULT_ERRORS and set their copy on the subclass as this attribute.

Type:: dict

already_registered_error_class¶

The error class indicating an already registered item.

This must be a subclass of AlreadyRegisteredError.

Type:: type

alias of AlreadyRegisteredError

lookup_error_class¶

The lookup error exception class.

This must be a subclass of ItemLookupError.

Type:: type

alias of ItemLookupError

__init__() → None¶: Initialize the registry.

state: RegistryState¶: The current state of the registry.

New in version 5.0.

property populated: bool¶

Whether or not the registry is populated.

This can be used to determine if the registry is populated (or in the process of being populated).

Consumers should check state instead, for more precise tracking. This method is deprecated.

Deprecated since version 5.0: This has been replaced by state and will be removed in Djblets 7.

Returns:: Whether or not the registry is populated.
Return type:: bool

format_error(error_name: str, **error_kwargs) → str¶

Format an error message.

Parameters:

error_name (str) – A symbolic name for the error, such as ALREADY_REGISTERED.
**error_kwargs (dict) – The keyword arguments to provide to the error-specific formatting string.

Returns:

The formatted error message.

Return type:

str

Raises:

ValueError – A registered error message for error_name could not be found.

get(attr_name: str, attr_value: object) → RegistryItemType¶

Return an item by its attribute value.

Parameters:

attr_name (str) – The attribute name to look up an item by.
attr_value (object) – The corresponding attribute value.

Returns:

The registered item.

Return type:

object

Raises:

djblets.registries.errors.ItemLookupError – When a lookup is attempted with an unsupported attribute, or the item cannot be found, this exception is raised.

get_or_none(attr_name: str, attr_value: object) → Optional[RegistryItemType]¶

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

New in version 3.1.

Parameters:

attr_name (str) – The attribute name.
attr_value (object) – The attribute value.

Returns:

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

Return type:

object

register(item: RegistryItemType) → None¶

Parameters:

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

Raises:

djblets.registries.errors.RegistrationError – Raised if the item is missing one of the required attributes.
djblets.registries.errors.AlreadyRegisteredError – Raised if the item is already registered or if the item shares an attribute name, attribute value pair with another item in the registry.

unregister_by_attr(attr_name: str, attr_value: object) → None¶

Unregister an item from the registry by an attribute.

Parameters:

attr_name (str) – The name of the attribute.
attr_value (object) – The attribute value.

Raises:

djblets.registries.errors.ItemLookupError – Raised if the attribute value is not found in the 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:: djblets.registries.errors.ItemLookupError – Raised if the item is not found in the registry.

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.

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.

New in version 5.0.

Parameters:: item (object) – The item to register.
Raises:: djblets.registries.errors.RegistrationError – 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.

New in version 5.0.

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.

New in version 5.0.

Parameters:: item (object) – The item to unregister.

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.

New in version 5.0.

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.

New in version 5.0.

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.

New in version 5.0.

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.

New in version 5.0.

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.

New in version 5.0.

__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

__annotations__ = {'_items': 'set[RegistryItemType]', '_lock': 'RLock', '_registry': 'dict[str, dict[object, RegistryItemType]]', 'already_registered_error_class': 'Type[AlreadyRegisteredError]', 'default_errors': 'RegistryErrorsDict', 'errors': 'RegistryErrorsDict', 'item_name': 'Optional[str]', 'lookup_attrs': 'Sequence[str]', 'lookup_error_class': 'Type[ItemLookupError]', 'state': 'RegistryState'}¶

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

__parameters__ = (~RegistryItemType,)¶

class EntryPointRegistry¶

Bases: Registry[RegistryItemType]

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

entry_point: Optional[str] = None¶

The entry point name.

Type:: str

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.

Parameters:: entry_point (importlib.metadata.EntryPoint) – The entry point.
Returns:: The processed entry point value.
Return type:: object

__annotations__ = {'_items': 'set[RegistryItemType]', '_lock': 'RLock', '_registry': 'dict[str, dict[object, RegistryItemType]]', 'already_registered_error_class': 'Type[AlreadyRegisteredError]', 'default_errors': 'RegistryErrorsDict', 'entry_point': 'Optional[str]', 'errors': 'RegistryErrorsDict', 'item_name': 'Optional[str]', 'lookup_attrs': 'Sequence[str]', 'lookup_error_class': 'Type[ItemLookupError]', 'state': 'RegistryState'}¶

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

__parameters__ = (~RegistryItemType,)¶

class OrderedRegistry¶

Bases: Registry[RegistryItemType]

A registry that keeps track of registration order.

__init__() → None¶: Initialize the OrderedRegistry

__annotations__ = {}¶

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

__parameters__ = (~RegistryItemType,)¶

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.

New in version 5.0.

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.

New in version 5.0.

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.