Jump to >

This documentation covers the in-development release of Djblets. You can see the latest stable docs or all previous versions.

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]

The error class indicating an already registered item.

alias of djblets.registries.errors.AlreadyRegisteredError

lookup_error_class[source]

The lookup error exception class.

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]

Register an item.

Parameters

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

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

Register an item.

Parameters

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

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