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.

They also run inside the request or command that made the change, before the response goes out, so a publisher that calls a network service adds its latency to every write. Keep publish local, and put anything slower on a queue. tunables.publishers.QueuedPublisher is a base class for that: implement enqueue and it receives the version, which the worker reads back with tunables_publish VERSION or straight from the snapshot table.

from tunables.publishers import QueuedPublisher


class WebhookPublisher(QueuedPublisher):
    def enqueue(self, version: int) -> None:
        send_snapshot_webhook.delay(version)

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 values in Django code

Code inside the project reads its tunables through one object, which caches the whole value set in the process:

from tunables import values

rate = values.get("pricing.vat_rate")
pricing = values.group("pricing")

A read serves from memory. At most once per READ_CACHE_TTL seconds it checks the stored version with one small query and reloads when the version moved, and a write in the same process drops the cache at once. See docs/reading.md.

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.

Tags are metadata and sit outside the change history. Creating a tag, renaming it, or attaching it to a tunable writes no change set, takes no reason, and does not move the version. They are still traceable: an assignment row stores who attached the tag and when, and every tag change writes a line to the tunables.tags logger. Values are the versioned part of the package; labels on them are recorded but not versioned.

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
• Reading values in Django code
• REST API
• Django admin
• Snapshot format and reader contract
• Deploying a new catalogue

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.