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

__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:	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.

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