Welcome to the django-registries documentation!#

django-registries is a django app that provides a framework for creating registries of implementations for a given interface.

Let’s say you have a project that needs to be able to send emails. You want to be able to use different email backends, depending on the situation. You could create a registry for that and register different implementations of the EmailBackendInterface. Then, you could use the registry to get the implementation you want to use.

By default django-registries finds registries in the registry module of each app in INSTALLED_APPS. So, for example, if you have an app called myapp, you could create a registry.py file in that app and define your registry there.

# myapp/registry.py
from django_registries import Interface
from django_registries import Registry

class EmailBackendRegistry(Registry):
    implementations_module = 'email_backend'


class EmailBackendInterface(Interface):
    registry = EmailBackendRegistry

    def send_email(self, subject, body, from_email, to_emails):
        raise NotImplementedError()

If we then want to implement this interface, we create a module called email_backend.py in the an app, lets call it great_email_service.

# great_email_service/email_backend.py
from myapp.registry import EmailBackendInterface

class GreatEmailBackend(EmailBackendInterface):
    slug = 'great_email_backend'

    def send_email(self, *, subject, body, from_email, to_emails):
        # do something great email sending here
        pass

We now have a registry with one implementation, which is neat. But we want to be able to use it in our model. We can do that by using the choices_field method.

# myapp/models.py
from django.db.models import Model

from myapp.registry import EmailBackendRegistry


class User(Model):
    # ...
    email_backend = EmailBackendRegistry.choices_field(max_length=100)

Now we can use the implementation seamlessly:

user = User.objects.get(pk=1)
user.email_backend.send_email(
    subject="Hello",
    body="Hello world",
    from_email="user1@example.com",
    to_emails=["user2@example.com"],
)

Welcome to the django-registries documentation!#

Indices and tables#