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.
- DEFAULT_ERRORS = {'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.'}[source]¶
Default error messages for registries.
- RegistryItemType[source]¶
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’)
- class Registry[source]¶
Bases:
Generic
[djblets.registries.registry.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 3.1: Added support for specifying a registry item type when subclassing this registry.
- errors: Dict[str, str] = {}¶
Error formatting strings for exceptions.
Entries here override the global
DEFAULT_ERRORS
dictionary for error messages.- Type
- default_errors: Dict[str, str] = {'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
- already_registered_error_class¶
The error class indicating an already registered item.
This must be a subclass of
AlreadyRegisteredError
.- Type
- lookup_error_class¶
The lookup error exception class.
This must be a subclass of
ItemLookupError
.- Type
- property populated: bool[source]¶
Whether or not the registry is populated.
- Returns
Whether or not the registry is populated.
- Return type
- format_error(error_name: str, **error_kwargs) str [source]¶
Format an error message.
- Parameters
- Returns
The formatted error message.
- Return type
- Raises
ValueError – A registered error message for
error_name
could not be found.
- get(attr_name: str, attr_value: object) djblets.registries.registry.RegistryItemType [source]¶
Return an item by its attribute value.
- Parameters
- Returns
The registered item.
- Return type
- 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[djblets.registries.registry.RegistryItemType] [source]¶
Return the requested registered item, or None if not found.
New in version 3.1.
- register(item: djblets.registries.registry.RegistryItemType) None [source]¶
Register an item.
- 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 [source]¶
Unregister an item from the registry by an attribute.
- Parameters
- Raises
djblets.registries.errors.ItemLookupError – Raised if the attribute value is not found in the registry.
- unregister(item: djblets.registries.registry.RegistryItemType) None [source]¶
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 [source]¶
Ensure the registry is populated.
Calling this method when the registry is populated will have no effect.
- get_defaults() Iterable[djblets.registries.registry.RegistryItemType] [source]¶
Return the default items for the registry.
This method should be overridden by a subclass.
- Returns
The default items for the registry.
- Return type
- reset() None [source]¶
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.
- __iter__() Iterator[djblets.registries.registry.RegistryItemType] [source]¶
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 [source]¶
Return the number of items in the registry.
- Returns
The number of items in the registry.
- Return type
- __contains__(item: djblets.registries.registry.RegistryItemType) bool [source]¶
Return whether or not the item is contained in the registry.
- __annotations__ = {'_items': 'Set[RegistryItemType]', '_populated': 'bool', '_registry': 'Dict[str, Dict[object, RegistryItemType]]', 'already_registered_error_class': typing.Type[djblets.registries.errors.AlreadyRegisteredError], 'default_errors': typing.Dict[str, str], 'errors': typing.Dict[str, str], 'item_name': typing.Optional[str], 'lookup_attrs': typing.Sequence[str], 'lookup_error_class': typing.Type[djblets.registries.errors.ItemLookupError]}¶
- __orig_bases__ = (typing.Generic[~RegistryItemType],)¶
- __parameters__ = (~RegistryItemType,)¶
- class EntryPointRegistry[source]¶
Bases:
djblets.registries.registry.Registry
[djblets.registries.registry.RegistryItemType
]A registry that auto-populates from an entry-point.
- get_defaults() Iterable[djblets.registries.registry.RegistryItemType] [source]¶
Yield the values from the entry point.
- Yields
object
– The object from the entry point.
- process_value_from_entry_point(entry_point: pkg_resources.EntryPoint) djblets.registries.registry.RegistryItemType [source]¶
Return the item to register from the entry point.
By default, this returns the loaded entry point.
- Parameters
entry_point (
pkg_resources.EntryPoint
) – The entry point.- Returns
The processed entry point value.
- Return type
- __annotations__ = {'_items': 'Set[RegistryItemType]', '_populated': 'bool', '_registry': 'Dict[str, Dict[object, RegistryItemType]]', 'already_registered_error_class': 'Type[AlreadyRegisteredError]', 'default_errors': 'Dict[str, str]', 'entry_point': typing.Optional[str], 'errors': 'Dict[str, str]', 'item_name': 'Optional[str]', 'lookup_attrs': 'Sequence[str]', 'lookup_error_class': 'Type[ItemLookupError]'}¶
- __orig_bases__ = (djblets.registries.registry.Registry[~RegistryItemType],)¶
- __parameters__ = (~RegistryItemType,)¶
- class OrderedRegistry[source]¶
Bases:
djblets.registries.registry.Registry
[djblets.registries.registry.RegistryItemType
]A registry that keeps track of registration order.
- register(item: djblets.registries.registry.RegistryItemType) None [source]¶
Register an item.
- 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(item: djblets.registries.registry.RegistryItemType) None [source]¶
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.
- __iter__() Iterator[djblets.registries.registry.RegistryItemType] [source]¶
Yield the items in the order they were registered.
- Yields
object
– The registered items.
- __getitem__(index: int) djblets.registries.registry.RegistryItemType [source]¶
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
- 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.
- __annotations__ = {}¶
- __orig_bases__ = (djblets.registries.registry.Registry[~RegistryItemType],)¶
- __parameters__ = (~RegistryItemType,)¶