django-dbchoices

⚡ Simple Runtime Choices for Django Models & Forms

django-dbchoices provides a clean, lightweight way to manage dynamic choices in Django; backed by the database. It’s built for cases where valid choices depend on context—such as tenancy, environment, or configuration—and where hard-coded enums or frequent migrations become a bottleneck.

Key Features

• Plug-and-play integration: Works seamlessly with Django Models, Forms, Admin, DRF, and more.
• Runtime Evaluation: Choices are resolved dynamically when models and forms are loaded.
• Code-defined defaults: Declare default choices in code and easily sync them to the database.
• Built-in caching: Reduces database hits and keeps performance snappy.
• Swappable by design: Bring your own model to support multi-tenancy or attach extra metadata.

---

📦 Installation & Setup

pip install django-dbchoices

Add to your settings.py:

# settings.py
INSTALLED_APPS = [
    # ...
    'dbchoices',
]

Workflow

1. Migrate: Apply the package's initial migrations.

   python manage.py migrate

2. Define Defaults: Register your required choices in your application's AppConfig.ready() method:

   class MyAppConfig(AppConfig):
       name = 'myapp'
   
       def ready(self) -> None:
           from dbchoices.registry import ChoiceRegistry
   
           # Register choices using tuples
           ChoiceRegistry.register_defaults("Status", [
               ("PENDING", "Booking Pending"),
               ("COMPLETE", "Booking Complete"),
               ("FAILED", "Booking Failed"),
           ])
   
           # Or using TextChoices and/or Enums
           ChoiceRegistry.register_enum(StatusEnum)

3. Synchronize: Run the management command to push your code definitions into the database.

   python manage.py dbchoices --sync

And you're all set! Your choices are now ready for use in models and forms.

---

Usage

Defining Models

Use the custom DynamicChoiceField to define the choice field(s) in the models. This field handles the necessary hooks for validation and display.

# myapp/models.py
from dbchoices.fields import DynamicChoiceField

class Ticket(models.Model):
    status = DynamicChoiceField(group_key='Status', default='PENDING')

Alternatively, if you wish to keep using standard Django fields, you can use DynamicChoiceValidator.

Note: This approach does not support automatic label/choice rendering in Django Admin/Forms.

# myapp/models.py
from django.db import models
from dbchoices.registry import ChoiceRegistry

class Ticket(models.Model):
    status = models.CharField(
        default='PENDING',
        validators=[DynamicChoiceValidator(group_key='Status')],
    )

API Access

The registry also provides helper methods for obtaining human-readable labels and models.TextChoices in your code logic.

Note: It is discouraged to use get_enum in typing-critical paths due to the ephemeral nature of runtime choices.

from dbchoices.registry import ChoiceRegistry

# Get the readable label
readable_status = ChoiceRegistry.get_label('ticket_status', 'in_progress')

# Get the Enum class for code logic
Status = ChoiceRegistry.get_enum('ticket_status')
if ticket.status == Status.CLOSED:
    # ...

---

Settings

You can customize the behavior of django-dbchoices using the following settings in your settings.py:

# settings.py
# Cache timeout for dynamic choices (default: 1 hour)
DBCHOICES_CACHE_TIMEOUT = 3600

# Cache alias to use for caching dynamic choices (default: 'default')
DBCHOICES_CACHE_ALIAS = 'default'

# Whether to auto-invalidate cache on choice updates (default: True)
DBCHOICES_AUTO_INVALIDATE_CACHE = True

# Custom choice model path (default: 'dbchoices.Choice')
DBCHOICE_MODEL = 'myapp.CustomChoiceModel'

---

License

This project is licensed under the MIT License. See the LICENSE file for details.