registries 1.0

Registration management and lookup of objects, for extensible Python applications.

Registries for Python

Registries is a module for managing collections of objects, allowing for easy registration, lookups, and access.

This is ideal for applications that need to manage abstract interfaces with backend implementations, such as plugins, extensions, and other cases where you'd employ a Registry Pattern.

Registries was built to help develop Review Board, our premier code review product from Beanbag, and we're making it available for use in other projects.

What is the Registry Pattern?

The Registry Pattern is a design pattern that provides a central repository for storing and accessing instances of various classes or objects. Objects can be registered dynamically or as part of the registry definition, each with a unique identifier, and then retrieved later by iterating through or querying the registry.

This can help provide a more decoupled design, reducing the need for dependencies between parts of your codebase, and helping make your codebase more extensible, maintainable, and testable.

Registries for Python makes this simple.

Features

Registries offers:

• Dynamic registration and unregistration of items.
• Flexible lookups based on registered lookup attributes.
• Thread-safety to avoid conflicts with modifying a registry.
• Extensibility through pre/post hooks for registration, unregistration, initial population, and resetting of registries.
• Python type hints to ease development.
• Built-in registries for order-dependent items and wrapping around Python Entry Points.

Installation

To install Registries, run:

$ pip install registries

Registries follows semantic versioning, meaning no surprises when you upgrade.

Example Usage

Here's a quick example to get you started with Registries:

from typing import Type

from registries import Registry
from registries.errors import RegistrationConflictError


# Let's create a base class for our objects and some default items.
class BaseItem:
    my_item_id: str


class FooItem(BaseItem):
    my_item_id = 'fooitem'


class BarItem(BaseItem):
    my_item_id = 'baritem'


# Now we'll create our registry with those items as defaults.
class MyRegistry(Registry[Type[BaseItem]]):
    lookup_attrs = ('my_item_id',)

    def get_defaults(self):
        return [FooItem, BarItem]


# Set up our registry.
registry = MyRegistry()

# This will print FooItem and BarItem.
for item in registry:
    print(item)


# Let's register a new item.
class BazItem(BaseItem):
    my_item_id = 'bazitem'


registry.register(BazItem)


# BazItem will now be in the registry.
assert BazItem in registry

for item in registry:
    print(item)


# Let's look up some objects.
assert registry.get('fooitem') is FooItem
assert registry.get('bazitem') is BazItem


# We can also look up by explicit attributes, in case the registry supports
# multiple lookup attributes.
assert registry.get(my_item_id='baritem') is BarItem


# Registering another item with the same ID will raise a
# RegistrationConflictError.
class ConflictItem(BaseItem):
    my_item_id = 'fooitem'

try:
    registry.register(ConflictItem)
except RegistrationConflictError:
    print('ConflictItem conflicts with FooItem!')


# Let's unregister FooItem.
registry.unregister(FooItem)

assert FooItem not in registry

# And now we can register ConflictItem!
registry.register(ConflictItem)
assert registry.get(my_item_id='fooitem') is ConflictItem

This is just a quick overview of how you might work with a registry. There's a lot more that can be done, including:

• Custom registry-defined error messages and exception classes.
• Multi-attribute registration and lookup.
• Hooks for customization the registration and lookup process, to tie into other pieces of your architecture.

All thread-safe, all in your control.

License

Registries is available under the MIT license.

Contributing

Contributions to Registries can be made on our Review Board server at https://reviews.reviewboard.org/.

To post a change for review:

1. Download RBTools:

   $ pip install rbtools
   

2. Create a branch in your Git clone and make your changes.

3. Post the change for review:

   $ rbt post
   

   To update your change:

   $ rbt post -u
   

Our Other Projects

• Review Board - Our open source, extensible code review, document review, and image review tool.

• Djblets - Our pack of Django utilities for datagrids, API, extensions, and more. Used by Review Board.

• Housekeeping - Deprecation management for Python modules, classes, functions, and attributes.

• kgb - A powerful function spy implementation to help write Python unit tests.

• Typelets - Type hints and utility objects for Python and Django projects.

You can see more on github.com/beanbaginc and github.com/reviewboard.