django-tunables

Runtime-tunable parameters for Django with a full audit trail. The host project declares a catalogue of parameters in Python: keys, types, defaults, constraints, grouping. Operators change values through the Django admin or a REST API. Every change is an atomic, versioned change set, and every version produces a snapshot: one JSON document holding the complete effective parameter set, ready for other processes to read from the database or a file. Each group can also be described as JSON Schema plus a UI schema, so an external client can render its own editing forms.

It is not a replacement for Django settings, and it does not patch django.conf.settings. It has no per-user, per-tenant or per-environment scopes; one database holds one catalogue with one effective value per key. Scheduled changes, nullable values, and notifications beyond the publisher hook are out of scope.

How it differs from django-constance and django-dynamic-preferences

Both of those store dynamic settings in the database and edit them in the admin. django-tunables adds change sets with actor and reason, an append-only history, a snapshot per version that other processes can read without importing the package, and a schema endpoint that describes each group to external clients. Two ideas were borrowed: the type to form field mapping comes from constance, and giving each type its own form field, serializer and validator comes from dynamic-preferences.

Requirements

Python 3.12 or newer, Django 5.2 or newer, Django REST Framework 3.15 or newer. PostgreSQL 14 or newer for the optional database-level history protection. SQLite works for everything else.

pip install django-tunables

Quickstart

Add the apps and point the setting at your catalogue. In settings.py:

INSTALLED_APPS = [
    # ...
    "rest_framework",
    "tunables",
]

TUNABLES = {"CATALOGUE": "myproject.tunables_catalogue.catalogue"}

Declare the catalogue. In myproject/tunables_catalogue.py:

from tunables import Boolean, Catalogue, Enum, Float, Group, List, Tunable

pricing = Group(
    "pricing",
    title="Pricing",
    order=1,
    tunables=[
        Tunable("vat_rate", Float(min=0.0, max=1.0), 0.24, title="VAT rate"),
        Tunable("free_shipping_over", Float(min=0.0), 50.0, title="Free shipping over", unit="EUR"),
        Tunable("currencies", List(Enum(["EUR", "USD", "GBP"]), min_items=1, unique=True), ["EUR"]),
        Tunable("allow_backorders", Boolean(), False),
    ],
)

thermostat = Group(
    "thermostat",
    title="Thermostat",
    order=2,
    tunables=[
        Tunable("target_c", Float(min=5.0, max=30.0), 21.0, title="Target temperature", unit="°C"),
        Tunable("mode", Enum(["auto", "heat", "cool", "off"]), "auto"),
    ],
)

catalogue = Catalogue([pricing, thermostat])

Mount the API next to the admin. In myproject/urls.py:

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/tunables/", include("tunables.api.urls")),
]

Create the tables and the first snapshot:

python manage.py migrate
python manage.py tunables_sync

Read the effective values:

curl -s http://localhost:8000/api/tunables/values/

Change one:

curl -s -X POST http://localhost:8000/api/tunables/changesets/ \
  -H "Content-Type: application/json" \
  -H "X-Tunables-Actor: alice" \
  -d '{"changes": [{"key": "pricing.vat_rate", "value": 0.2}], "reason": "autumn rate"}'

The response is the new change set with version 1. tunables_show prints the effective values with an override marker, and the admin's Tunables page offers the same edit as a form. Run tunables_sync after every deployment, after migrate, so the database mirror follows the catalogue in code.

Settings

All settings live in one dictionary, TUNABLES. Only CATALOGUE is required.

Management commands

tunables_sync --check compares the catalogue hash, the mirrored categories and the seeded tags. A change to a title or description makes the mirror stale without failing the check; the next tunables_sync updates the mirror without writing a new version. The API and the admin answer 503 on the hash alone, so stale categories or tags never take the API down.

Publishers and the signal

The snapshot row in the database is always written. In addition, every committed snapshot is sent to the tunables.signals.snapshot_published signal, with the Snapshot instance as snapshot, and then to each publisher named in PUBLISHERS. A publisher is any object with a publish(snapshot) method. An exception inside publish is logged under the tunables.publishers logger and does not affect the write. Both the signal and the publishers run after the transaction commits.

Each publisher's outcome is recorded: the version it last received, when, and the last error if any. GET status/ shows this per publisher, so a gap between the current version and a publisher's last version is visible. manage.py tunables_publish [VERSION] [--publisher PATH] sends a stored snapshot, the latest by default, to all or one publisher again, and fails with the publisher's error when it does not succeed.

tunables.publishers.FilePublisher writes the document to FILE_PUBLISHER_PATH, using a temporary file in the same directory and a rename, so readers never see a partial file:

TUNABLES = {
    "CATALOGUE": "myproject.tunables_catalogue.catalogue",
    "PUBLISHERS": ["tunables.publishers.FilePublisher"],
    "FILE_PUBLISHER_PATH": "/var/lib/myproject/tunables.json",
}

Reading snapshots from other processes

A reader polls tunables_state.current_version, and when it changes fetches tunables_snapshot.document for that version. The document format, the JSON Schema shipped with the package, and the table contract are in docs/snapshot-format.md.

API

Writes accept If-Match for optimistic concurrency and every response carries X-Tunables-Version. Errors are RFC 9457 problem documents. The full reference, including the problem types and error codes, is in docs/api.md.

Admin

The Tunables page in the admin lists the groups by category and edits one group per form with a reason field and a reset box per override. A definitions page browses every tunable by category, group, tag and text, and tags can be edited per definition. The change set history is read only and has a rollback action. See docs/admin.md.

A screenshot of the group edit form will be added here.

Documentation

• Declaring the catalogue
• REST API
• Django admin
• Snapshot format and reader contract

Development

uv sync --all-extras
uv run pytest
uv run pytest --postgres    # the whole suite on a PostgreSQL testcontainer, needs Docker
uv run ruff check . && uv run mypy src
scripts/quickstart_check.sh    # installs the built wheel into a fresh project and runs the quickstart

License

MIT. See LICENSE.