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.

class Registry[source]¶

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.

item_name = None[source]¶: The name of the items being registered.

lookup_attrs = [][source]¶: A list of attributes that items can be looked up by.

errors = {}[source]¶

Error formatting strings for exceptions.

Entries here override the global DEFAULT_ERRORS dictionary for error messages.

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]¶

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.

already_registered_error_class[source]¶: alias of djblets.registries.errors.AlreadyRegisteredError

lookup_error_class[source]¶: alias of djblets.registries.errors.ItemLookupError

property populated[source]¶

Whether or not the registry is populated.

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

format_error(error_name, **error_kwargs)[source]¶

Format an error message.

Parameters

error_name (unicode) – 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

unicode

get(attr_name, attr_value)[source]¶

Return an item by its attribute value.

Parameters

attr_name (unicode) – 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.

register(item)[source]¶

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, attr_value)[source]¶

Unregister an item from the registry by an attribute.

Parameters

attr_name (unicode) – 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)[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()[source]¶

Ensure the registry is populated.

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

get_defaults()[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: list

reset()[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.

class EntryPointRegistry[source]¶

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

entry_point = None[source]¶: The entry point name.

get_defaults()[source]¶

Yield the values from the entry point.

Yields: object – The object from the entry point.

process_value_from_entry_point(entry_point)[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: object

class OrderedRegistry[source]¶

A registry that keeps track of registration order.

register(item)[source]¶

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