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 = {u'already_registered': u'Could not register %(item)s: it is already registered.', u'attribute_registered': u'Could not register %(item)s: another item (%(duplicate)s) is already registered with %(attr_name)s = %(attr_value)s.', u'invalid_attribute': u'"%(attr_name)s" is not a registered lookup attribute.', u'load_entry_point': u'Could not load entry point %(entry_point)s: %(error)s.', u'missing_attribute': u'Could not register %(item)s: it does not have a "%(attr_name)s" attribute.', u'not_registered': u'No item registered with %(attr_name)s = %(attr_value)s.', u'unregister': u'Could not unregister %(item)s: it is not registered.'}[source]

Default error messages for registries.

class Registry[source]

Bases: object

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 = {u'already_registered': u'Could not register %(item)s: it is already registered.', u'attribute_registered': u'Could not register %(item)s: another item (%(duplicate)s) is already registered with %(attr_name)s = %(attr_value)s.', u'invalid_attribute': u'"%(attr_name)s" is not a registered lookup attribute.', u'load_entry_point': u'Could not load entry point %(entry_point)s: %(error)s.', u'missing_attribute': u'Could not register %(item)s: it does not have a "%(attr_name)s" attribute.', u'not_registered': u'No item registered with %(attr_name)s = %(attr_value)s.', u'unregister': u'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

populated[source]

Whether or not the registry is populated.

Returns:Whether or not the registry is populated.
Return type:bool
__init__()[source]

Initialize the registry.

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.

__iter__()[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__()[source]

Return the number of items in the registry.

Returns:The number of items in the registry.
Return type:int
__contains__(item)[source]

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
class EntryPointRegistry[source]

Bases: djblets.registries.registry.Registry

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]

Bases: djblets.registries.registry.Registry

A registry that keeps track of registration order.

__init__()[source]

Initialize the OrderedRegistry

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.
__iter__()[source]

Yield the items in the order they were registered.

Yields:object – The registered items.
__getitem__(index)[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:

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.