django-dynamic-preferences

1.17.0 verified Mon Apr 27 auth: no python maintenance

Dynamic global and instance settings for your Django project. Version 1.17.0. Release cadence: infrequent, last updated in 2023.

pip install django-dynamic-preferences

Common errors

error No module named 'dynamic_preferences' ↓

cause Package not installed or not added to INSTALLED_APPS correctly.

fix

Run 'pip install django-dynamic-preferences' and add 'dynamic_preferences' to INSTALLED_APPS in settings.py.

error AttributeError: 'User' object has no attribute 'preferences' ↓

cause User model does not inherit from DynamicPreferencesMixin.

fix

Modify your User model to inherit from DynamicPreferencesMixin as described in the quickstart.

error KeyError: 'general__site_name' ↓

cause The preference has not been registered or the section/name separator is wrong.

fix

Ensure you are using double underscore (e.g., 'general__site_name') and that the preference is registered.

error django.db.utils.OperationalError: no such table: dynamic_preferences_globalpreferencemodel ↓

cause Database migrations not applied after adding dynamic_preferences to INSTALLED_APPS.

fix

Run 'python manage.py makemigrations dynamic_preferences' and 'python manage.py migrate'.

Warnings

breaking In version 1.10+, the user preference registry is no longer automatically attached to the User model via a signal. You must explicitly add DynamicPreferencesMixin to your User model. ↓

fix Ensure your User model inherits from DynamicPreferencesMixin. from dynamic_preferences.users.mixins import DynamicPreferencesMixin class User(DynamicPreferencesMixin, AbstractUser): pass

gotcha The preference name separator is double underscore (e.g., 'general__site_name'). A single underscore may be silently ignored. ↓

fix Always use double underscore between section and name when accessing preferences (e.g., get('general__site_name')).

deprecated The old-style registration using preference decorators with explicit section and name is deprecated. Use the registry's register method or the @register_preference decorator with a class. ↓

fix Migrate to class-based preference definitions. from dynamic_preferences.preferences import GlobalPreferenceModel from dynamic_preferences.registries import global_preferences_registry @global_preferences_registry.register class SiteName(GlobalPreferenceModel): section = 'general' name = 'site_name' verbose_name = 'Site Name' default = 'My Site'

gotcha When using the PreferenceForm, the form field names are prefixed with the section and separated by double underscore (e.g., 'general__site_name'). If you manually render fields, ensure you use these names. ↓

fix Use the provided template tags or manually reference the prefixed field names.

breaking Support for Python 2 was dropped in version 1.10. ↓

fix Upgrade to Python 3.6+.

Imports

DynamicPreferencesMixin

wrong

from dynamic_preferences.mixins import DynamicPreferencesMixin

correct

from dynamic_preferences.users.mixins import DynamicPreferencesMixin

Common mistake: the mixin is in users.mixins, not directly in dynamic_preferences.

global_preferences_registry

wrong

from dynamic_preferences.registry import global_preferences_registry

correct

from dynamic_preferences.registries import global_preferences_registry

Misspelling registry as registry.

user_preferences_registry

wrong

from dynamic_preferences.registries import user_preferences_registry

correct

from dynamic_preferences.users.registries import user_preferences_registry

User registry is in users.registries, not the main registries module.

Quickstart

Basic setup with global and per-user preferences. Requires Django User model to inherit from DynamicPreferencesMixin.

# settings.py
INSTALLED_APPS = [
    'dynamic_preferences',
    'dynamic_preferences.users',
]

# urls.py
from django.urls import path, include
urlpatterns = [
    path('preferences/', include('dynamic_preferences.urls')),
]

# models.py
from dynamic_preferences.users.mixins import DynamicPreferencesMixin
from django.contrib.auth.models import AbstractUser

class User(DynamicPreferencesMixin, AbstractUser):
    pass

# views.py
from dynamic_preferences.registries import global_preferences_registry
from dynamic_preferences.users.registries import user_preferences_registry

def my_view(request):
    global_prefs = global_preferences_registry.manager()
    user_prefs = user_preferences_registry.manager(request.user)
    # Access a preference
    value = global_prefs.get('general__site_name')
    return render(request, 'template.html', {'site_name': value})