SnapAdmin

📦 Installation

SnapAdmin can be installed via PyPI or directly from source.

From PyPI

pip install django-snapadmin

From GitHub

pip install git+https://github.com/drofji/django-snapadmin.git

Compatibility

SnapAdmin requires Python ≥ 3.10 and Django ≥ 5.2 (no upper bound pinned). SnapAdmin is currently a pre-1.0 beta (Development Status :: 4 - Beta); semantic versioning begins once a future 1.0 ships — see SECURITY.md for the current API-stability policy. Pin an exact version in production regardless.

Async support

SnapModel.asave() / .adelete() / .arefresh_from_db() are Django's own native async model methods (available since Django 5.2) — SnapAdmin adds no code for them and needs none: each is a thin wrapper around the matching sync method (self.save() / self.delete() / self.refresh_from_db()), and Python resolves that through the instance's actual class, so they already reach SnapModel's own overrides — the Elasticsearch mirror and a wysiwyg field's sanitize-on-write run identically whether you call save() or await obj.asave(). EsManager / EsQuerySet (the Elasticsearch query layer for ES_ONLY models) gain aget() / afirst() / alast() to match — a DB-backed model already got these for free from Django's own QuerySet.

Out of scope, deliberately: async DRF ViewSets (DRF's own async support is still partial), an async Elasticsearch client (the bundled client is sync-only and would need its own wrapper), and bulk async operations (abulk_create / abulk_update). GraphQL resolvers need nothing extra — Graphene already handles async resolvers transparently.

The smallest install that works

A bare pip install django-snapadmin is already enough for the generated admin, because the REST API and GraphQL are off by default (SNAPADMIN_REST_API_ENABLED / SNAPADMIN_GRAPHQL_ENABLED, both False unless you set them):

INSTALLED_APPS = [
    "django.contrib.admin",          # SnapAdmin generates ModelAdmins into this site
    "django.contrib.auth",           # permissions gate both the admin and the API
    "django.contrib.contenttypes",   # required by auth; the audit trail keys off it
    "django.contrib.sessions",       # admin login
    "django.contrib.messages",       # admin "saved successfully" banners
    "django.contrib.staticfiles",    # serves SnapAdmin's CSS/JS
    "snapadmin",
    "myapp",                         # …your own apps
]

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

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", include("snapadmin.urls")),   # the surfaces you turn on (REST adds /api/health/)
]

That is a working admin-only install. With the REST API off, snapadmin.urls mounts nothing — so an admin-only container probes /admin/login/, as the snapadmin-new --admin-only Dockerfile does, not /api/health/. For the REST API and GraphQL, install their extras (pip install "django-snapadmin[api,graphql]"), add rest_framework, drf_spectacular, django_filters and graphene_django to INSTALLED_APPS, and switch the surfaces on — individually, or both at once with SNAPADMIN_PROFILE = "api" (Swagger follows the REST setting unless set explicitly). Installing the extras without the settings serves nothing; the settings without the extras are caught at manage.py check (snapadmin.E010) rather than at the first request.

Configuring INSTALLED_APPS

The Unfold theme is optional (pip install django-snapadmin[theme]) — with it you get the themed UI, without it SnapAdmin renders on Django's built-in admin. If you use Unfold, its contrib apps must come before django.contrib.admin. manage.py check surfaces the stock-admin fallback as one informational message (snapadmin.I001, never an error) so it is never silently mistaken for a bug. If 'unfold' is listed but cannot be imported — usually an import cycle, a custom user model that imports SnapAdmin while apps load — the fallback is logged (snapadmin.unfold_import_failed) and reported as the warning snapadmin.W032 with the error; every SnapAdmin admin module shares that one decision, so the admin is never half-themed.

INSTALLED_APPS = [
    # Optional theme — only with the [theme] extra; must precede django.contrib.admin
    "unfold",
    "unfold.contrib.filters",
    "unfold.contrib.forms",
    "unfold.contrib.inlines",

    # WYSIWYG — only with the [wysiwyg] extra (SnapRichTextField / wysiwyg=True)
    # "django_ckeditor_5",

    # Django core
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",

    # REST API — [api] extra; needed only with SNAPADMIN_REST_API_ENABLED/
    # SNAPADMIN_SWAGGER_ENABLED set to True (both default False)
    "rest_framework",
    "drf_spectacular",
    "django_filters",

    # GraphQL — [graphql] extra; needed only with SNAPADMIN_GRAPHQL_ENABLED = True
    # (default False). Independent of [api].
    "graphene_django",

    "snapadmin",

    # Optional — only with the [celery] extra
    # "django_celery_beat",            # edit the schedule from the admin
    # "django_celery_results",         # store task results in the database

    # Optional — only with the [extra-settings] extra. SnapAdmin does not use it;
    # add it for a runtime key/value Setting model in the admin (the demo shows it).
    # "extra_settings",

    # Optional — only with the [autocomplete-filter] extra (LGPL), for your own
    # AutocompleteFilter admin filters; SnapAdmin core never imports it.
    # "admin_auto_filters",

    # Your apps …
]

Elasticsearch needs no app entry — install the [elasticsearch] extra and set ELASTICSEARCH_ENABLED = True. The supported server is Elasticsearch 8.x, and the extra pins the client to match (>=8,<9). The same goes for [backup], [s3], [age], [xlsx] and [encryption]: a dependency, not an app.

A bare pip install django-snapadmin pulls only Django, structlog and nh3. djangorestframework, drf-spectacular and django-filter come via the [api] extra, and graphene-django via [graphql] — both features default to off (SNAPADMIN_REST_API_ENABLED / SNAPADMIN_GRAPHQL_ENABLED), so install pip install django-snapadmin[api,graphql] (or [all]) once you turn either on. Turning a feature on with its extra missing fails loudly, both at manage.py check (snapadmin.E010) and, if that step is skipped, the moment snapadmin.urls is imported. django-unfold is not installed by the base package — add the [theme] extra for the Unfold-themed admin; without it the admin renders on stock Django. django-ckeditor-5 is likewise not installed by default (it bundles CKEditor 5, a GPL/commercial editor) — add it via the [wysiwyg] extra only if you use rich-text fields.

snapadmin/
├── api/             # REST & GraphQL API core: views, serializers, auth
├── management/      # Custom management commands
├── migrations/      # Core package migrations (e.g. APIToken)
├── static/          # UI assets (CSS, JS, SVG logos)
├── templates/       # Custom admin templates & dashboard
├── fields.py        # SnapField definitions with admin introspection
├── models.py        # SnapModel base, EsManager, and core logic
└── urls.py          # Auto-configurable API and documentation routes

🏁 New Project — snapadmin-new

snapadmin-new (also python -m snapadmin.scaffold) generates a project you keep — not a throwaway (snapadmin-demo) and not a read-only report (snapadmin-init): manage.py, a settings package, one app carrying a worked SnapModel example, SQLite and a .env/dist.env. migrate then runserver work immediately — no Docker, no manual edits.

pip install django-snapadmin
snapadmin-new myshop
cd myshop
pip install -r requirements.txt   # the extras this project imports — [api,graphql] by default
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Open http://127.0.0.1:8000/admin/ — the admin, the REST API (/api/docs/) and the GraphQL endpoint (/api/graphql/) are already wired to the worked Product model in catalog/models.py. Templates ship inside the wheel under snapadmin/scaffold/templates/ and render with the standard library's string.Template — no Jinja, no extra dependency.

Pass --full for the containerised stack — same project, plus a Dockerfile, docker-compose.yml and the PostgreSQL / Redis / Elasticsearch wiring (Postgres when POSTGRES_HOST is set, SQLite otherwise, so manage.py check/migrate still work with no services running):

snapadmin-new myshop --full
cd myshop
docker compose up --build

Flags

🩺 Integrate an existing project — snapadmin-init

Adding SnapAdmin to a project you already have means editing INSTALLED_APPS (with a specific ordering), urls.py, a settings block and your requirements. The snapadmin-init command (also python -m snapadmin.integrate) makes that trivial — and safe.

pip install django-snapadmin
snapadmin-init                    # a per-item present/missing checklist with snippets
snapadmin-init --api --graphql    # also check the REST / GraphQL configuration
snapadmin-init --json             # machine-readable, for your own tooling

For each item it reports ✓ already present or ✗ add this — followed by the block to paste:

• INSTALLED_APPS — the full list with snapadmin in place, and a note that the unfold theme is optional ([theme] extra) — if you use it, its apps must precede django.contrib.admin.
• URL routes — the include("snapadmin.urls") line, honouring --url-prefix.
• SnapAdmin settings — the SNAPADMIN_* feature-toggle block.
• REST / GraphQL config — with --api / --graphql.
• Install line — pip install django-snapadmin[extras] (--extras), and a warning if your requirements pin an incompatible Django.
• Model conversion (advisory) — lists files still subclassing models.Model and shows how to convert one to SnapModel.

Flags

✅ Integration Checklist

Installed doesn't mean correctly integrated. Every row below names the command that proves it — run it, don't take the row's word for it. Stop at whichever group matches where your project actually is; you don't need "Optional / scale" to ship a first version.

Must work

Should be configured before production

Data safety

Optional / scale

🧭 Production Playbook

The checklist above proves an install is wired correctly. This one is about the decisions around it — what to settle with whoever owns the project before writing integration code, the order to build in, what the project's own test suite should cover, and which defaults stop being the right ones under load. It is written for a developer starting a real deployment, and it is the same material an AI assistant reads from llms.txt, so the two never give different advice.

1. Decisions to settle before writing integration code

Each row has a default that is safe but not necessarily right, and each one fails quietly rather than loudly if nobody chooses. Ordered by how expensive they are to change later — the first three are paid for once and then forever, the rest are settings.

2. Build order for a new project

The answers above become this order. Each step is verifiable before the next one starts — skipping ahead is what produces a project that works under DEBUG and fails on its first real day. snapadmin-new scaffolds steps 1–4 for a greenfield project; snapadmin-init prints the same steps as ready-to-paste snippets for an existing one, and never edits your source.

1. Identity and the settings skeleton, before the first migrate. A custom user model — even an empty AbstractUser subclass, because adding one later is the expensive migration — USERNAME_FIELD, password validators, and one settings module per environment with every secret read from the environment.
2. Install the surfaces the project actually wants. The extras the answers require, Unfold's apps before django.contrib.admin, snapadmin.urls in the root URLconf, and one SNAPADMIN_PROFILE line.
3. Model the domain as ordinary Django first, then add the Snap kwargs. Relations, constraints, indexes and Meta are Django decisions SnapAdmin does not change; searchable/filterable/show_in_list are presentation layered on top and add no migration. A model that is wrong as a Django model is not rescued by a generated admin.
4. Register, then look at it. register_all_admins(), then manage.py check, snapadmin_info --section inventory — every model, the door it came in by, the capabilities inactive on it — and an actual visit to /admin/.
5. Permissions before data. Groups and permissions per role, write surfaces on every model the API exposes, field-level guards where a field must not be visible at all, and SNAPADMIN_API_ACTION_PERMISSIONS for every custom action — an unmapped action is refused for everyone, superusers included. Do this while the tables are empty and a mistake costs nothing.
6. Declare the data-protection layer. subject_path everywhere, masking for personal data, encrypted columns for anything that must be unreadable in a dump, retention windows where a legal one exists.
7. Wire the operational layer. Backups to at least two destinations with AGE recipients, a Celery worker and a Beat schedule, the error-monitor middleware and one alert channel that reaches a human, JSON logs, and /api/health/ as the container probe — never /admin/, which answers 302 with the database down.
8. Only now turn on what the load profile demands. Elasticsearch mirroring, a read replica or sharding, caching, remote storage. Each is an operational commitment; adding one because it might be needed is how a two-service project becomes a six-service one.
9. Harden the deployment. DEBUG = False, ALLOWED_HOSTS, a clean manage.py check --deploy, collectstatic in the image build, a least-privilege database role, and SNAPADMIN_URL_PREFIX if the admin should not sit at a guessable path.
10. Prove it with tests — the next subsection — and make manage.py check, makemigrations --check --dry-run and the suite a CI gate rather than a habit.
11. Rehearse the recovery before you need it: snapadmin_restore --database <alias> into a throwaway database, row counts compared, the result written down with a date, repeated on a schedule.
12. Pin the version and read the release notes on every upgrade. The package is pre-1.0; pin an exact version in production, then re-run manage.py check and makemigrations --check immediately after each bump.

3. Testing the project you build

SnapAdmin's own suite covers the library and nothing about your models, your permissions or your data. Your project needs its own, in the same discipline: every assertion states a concrete contract — a status code, a value, an exception type, a side effect, a query count, never assert x is not None where a value is checkable — every test is order-independent with no shared mutable state and no reliance on the wall clock, and no test is ever weakened, skipped, xfailed, mocked into silence or given a longer timeout to make it pass. A failing test is a diagnosis job first.

The base. pytest + pytest-django with a dedicated test settings module; run the suite against the real database engine, because PostgreSQL differs from SQLite on constraints, ordering and transactions; random order (pytest-randomly) so ordering coupling fails loudly; factories rather than fixtures full of literals; frozen time instead of datetime.now(); no outbound network in unit tests. Measure coverage with --cov-branch and treat a high number as a floor for the domain layer, never as the goal — it proves lines ran, not that a mutation would be caught.

Per app. Models: constraints, clean(), custom managers, computed properties, __str__. Migrations: makemigrations --check --dry-run in CI, plus a forward run on both an empty database and a production-shaped copy. Admin: that the changelist renders for each role, that the columns and filters you declared are the ones that appear, and that a save produces the audit row. API: one test per role per action, the 401/403/404 distinction, validation errors as 400 rather than 500, pagination, filtering and every custom @snap_action. Background tasks: the task function called directly with real arguments, .delay() mocked only at the boundary.

The SnapAdmin-specific traps, one test each. Every one of these fails silently in production if it regresses:

Production points that need a test rather than a hope. Pin the query count of every list surface that matters (django_assert_num_queries) — an N+1 introduced by a new __str__ or a template that walks a relation is invisible at 50 rows and fatal at 50,000. Assert that the pagination cap actually caps, that a client asking for a bigger page gets the maximum and not the whole table, and that throttling answers 429. Keep manage.py check and check --deploy (against production settings) in CI. Test the permission matrix as a matrix, not one happy path. Assert the fail-closed defaults stay fail-closed after every dependency upgrade. And make a restore drill part of the schedule, asserted by row count rather than by the absence of an error message.

What SnapAdmin's own suite cannot do for you: it drives its generated admin in a real browser (browser E2E), but over the demo's models. A production project should keep browser E2E over its own critical admin flows — the same harness shape works, a live server plus Playwright with a check for JavaScript errors and missing assets on every page — and load tests against the API's real page sizes and filters, which a library has no traffic to run.

4. Production readiness and high load

Where the library helps, and where it deliberately stops. Every number below is the shipped default, and every one of them is a setting — the right value is the measured one.

5. Development norms in a SnapAdmin project

• Read model configuration through the registry, never with a hand-rolled getattr: is_registered(model) is the gate every surface asks, and get_model_meta(model, name, default) resolves decorator argument > class attribute > SNAPADMIN_<NAME> setting > default.
• Prefer the change that needs no migration. Snap-only kwargs, settings and admin-layer overrides cost nothing to deploy; a column change costs a maintenance window on every install.
• Write through the ORM save path when a field carries behaviour. Sanitization and encryption live in pre_save(), so save(), the admin, serializers and bulk_create() are covered — and QuerySet.update(), raw SQL and direct database access are not.
• Extend, don't fork, the generated surfaces. admin_overrides wins over anything the generator produces and get_admin_media() extends the base asset lists instead of snapshotting them; a copied-and-edited generated class silently stops inheriting fixes.
• Keep new surfaces fail-closed. The library's own defaults refuse rather than allow — an unmapped action, an unbound tenant, a masking rule that cannot resolve. Project code that adds a bypass should make it explicit, audited and tested, the way use_all_tenants() is.
• Type the public functions, log through structlog, read secrets from the environment. Every new setting gets a commented entry in the settings module and a line in the environment template, so nobody has to read the code to find it.
• Upgrades are a task, not a bump. Pin the exact version, read the release notes, run manage.py check and makemigrations --check, then the suite. The audit trail's {field: {"old", "new"}} shape and every snapadmin.* import path are stable across releases; behaviour behind a default can still change, which is what the notes are for.

🔀 Two Ways to Declare a Model

New, greenfield model? Subclass SnapModel below — that's the full route. Existing models you can't or won't rewrite? @snap_model + snap_field() opt them in from the outside, with no migration.

Both routes end in the same registry — snapadmin.registry.is_registered(model) is the gate every surface asks — so switching later changes nothing else: apply @snap_model to a SnapModel subclass and it overrides exactly the keywords you pass, leaving the rest of the class-level configuration alone.

The same model, both ways

from snapadmin import models as snap_models, fields as snap

class Product(snap_models.SnapModel):
    name = snap.SnapCharField(max_length=200, searchable=True)
    price = snap.SnapDecimalField(max_digits=10, decimal_places=2, filterable=True)
    cost_price = snap.SnapDecimalField(max_digits=10, decimal_places=2)

    api_write_fields = ["name", "price"]
    api_exclude_fields = ["cost_price"]
    subject_path = None   # snapadmin.E011 asks every registered model

from django.db import models
from snapadmin import snap_model
from snapadmin.fields import snap_field

@snap_model(
    api_write_fields=["name", "price"],
    api_exclude_fields=["cost_price"],
    search_fields=["name"],      # a plain model's ?search= reads this, not field flags
    subject_path=None,
)
class Product(models.Model):
    name = snap_field(models.CharField(max_length=200), searchable=True)
    price = snap_field(models.DecimalField(max_digits=10, decimal_places=2), filterable=True)
    cost_price = models.DecimalField(max_digits=10, decimal_places=2)

Both register the same model, with the same API write allowlist and the same REST search. On the decorated side that search comes from search_fields: a plain model has no generated admin, so its searchable/filterable flags reach no surface by themselves (REST query filters are generated for every column either way). Neither needs a migration: the decorator adds no field or attribute, and snap_field() sets its metadata after Django's Field.__init__ has already recorded its constructor arguments.

The honest comparison

The two routes are not identical — a decorated plain model does not attach SnapModel's runtime machinery, and the surfaces that need it skip a decorated model rather than half-work. This table states plainly which capability lives where; every ❌ links to the task tracking it, or is marked permanent with the reason.

Links onward: Snap Fields (the flags themselves) · snap_field() (the field-level wrapper) · Mixing Snap & plain fields (you never have to convert a whole model at once) · the decorator's full keyword table and precedence rule.

🏗 SnapModel

Subclass SnapModel and you get admin, search, GDPR retention and Elasticsearch mirroring for free — no extra code. Reach for it on a new model, when you want everything SnapAdmin can do.

from snapadmin import models as snap_models, fields as snap

class Product(snap_models.SnapModel):
    name = snap.SnapCharField(max_length=200, searchable=True)
    price = snap.SnapDecimalField(max_digits=10, decimal_places=2, filterable=True)
    available = snap.SnapBooleanField(default=True)

class OrderManager(OwnerScopedManager, EsManager):
    pass

class Order(SnapModel, OwnerScopedMixin):
    objects = OrderManager()

🔌 @snap_model — Plain Django Models

There are two ways to declare a SnapAdmin model. Subclassing SnapModel (above) is the full one. The @snap_model decorator is the other: it opts a plain django.db.models.Model in from the outside, without touching its field layer. Use it for a brownfield schema you cannot rewrite, a model whose base class belongs to a third-party package, or fields that come from packages like django-money, phonenumber_field or model-utils.

from django.db import models
from snapadmin import snap_model

@snap_model(
    api_write_fields=["name", "price"],   # mass-assignment allowlist
    api_exclude_fields=["cost_price"],    # never leaves the server
    search_fields=["name"],               # what ?search= matches on
)
class Product(models.Model):
    name = models.CharField(max_length=200)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    cost_price = models.DecimalField(max_digits=10, decimal_places=2)

The decorator adds no field and no attribute to the class, so it needs no migration. From then on the model is a SnapAdmin model everywhere the question is asked: the REST API mounts CRUD routes for it, the GraphQL schema gains a type, the offline endpoints and the snapadmin.W00x system checks see it, and snapadmin_info inventories it.

What a decorated model does not get — registration and metadata only, none of SnapModel's runtime machinery. See the full capability × door table, covering both the model and field halves, on Two Ways to Declare a Model.

The registry itself is public: snapadmin.registry.is_registered(model) is the gate every surface asks. Applying @snap_model to a SnapModel subclass overrides exactly the keywords you pass and leaves the rest of the class-level configuration alone.

📋 Snap Fields

Every Snap field is a drop-in replacement for the corresponding Django field, with extra admin control attributes. That includes Django's positional verbose_name: SnapCharField("Label", max_length=200) works exactly like models.CharField("Label", max_length=200), so existing model code survives the switch unchanged. Relation fields take to first, as in Django.

^* show_in_form's False default is project-wide, not per-field: SNAPADMIN_SHOW_IN_FORM_DEFAULT raises it for every field that never sets it explicitly — useful when adopting SnapAdmin onto models that predate it, where nothing setting it anywhere used to mean every generated change form rendered empty (snapadmin.W015 now catches that whatever the cause — but only for a model whose admin SnapAdmin actually generated: register one yourself with @admin.register and your own ModelAdmin, and the warning stays quiet, because the form you wrote owes nothing to show_in_form). An explicit per-field show_in_form= always wins over the project-wide setting.

Wysiwyg HTML is sanitized on write and on render. Rich-text fields (wysiwyg=True / SnapRichTextField) hold HTML written by whoever can write the field — an API token, a low-privileged staff account, a bulk import — so their value goes through an HTML sanitizer (nh3) that strips <script>, inline event handlers and unsafe URL schemes. Sanitizing happens in the field's pre_save(), so it covers every ORM write path — admin form, REST/GraphQL serializer, Model.save(), bulk_create() — and what lands in the database is already clean. The changelist sanitizes again on render, which keeps rows written before this behaviour existed safe to display.

Two opt-outs, and one gap worth knowing:

• safe_html=True — you vouch for this field's HTML; it is stored and rendered verbatim.
• auto_sanitize=False — store exactly what was submitted (rendering is still sanitized). Useful when another layer owns the cleaning, or when you must preserve the original bytes.
• QuerySet.update() is not covered: Django never calls pre_save() for a bulk update, so a value written that way reaches the column untouched. Sanitize it yourself, or write through the instance.

Point SNAPADMIN_HTML_SANITIZER at a dotted path to your own Callable[[str], str] to replace the allowlist; it is used by both the write and the render path.

Available field types

Every field type below maps 1:1 to a Django field (except the computed ones) and accepts all the flags above.

Computed columns on the change form. SnapFunctionField, @snap_property and SnapStatusBadgeField are changelist columns by default (show_in_list=True). show_in_form=True also shows the value read-only on the change form — escaped unless safe_html=True, in its tab= and row=, in declaration order among the model's fields. The add form never shows it: there is no saved row to compute from yet (and "Save as new" takes the add path). show_in_form defaults to False on these columns and SNAPADMIN_SHOW_IN_FORM_DEFAULT does not apply to them. The read-only row is the admin method snap_form_<name>; write that name in a hand-written fieldsets (admin_overrides). An argument the column cannot use — a typo, or a flag only editable fields have, such as searchable= — is ignored and reported as snapadmin.W033.

class OrderItem(SnapModel):
    quantity = SnapPositiveIntegerField(show_in_form=True)
    price = SnapDecimalField(max_digits=10, decimal_places=2, show_in_form=True)

    @snap_property(verbose_name="Line total", show_in_form=True)
    def line_total(self):
        return f"{self.quantity * self.price:.2f}"

A boolean with a default is a checkbox. Snap fields derive null=True from required=False, so SnapBooleanField(default=False) has a nullable column — but its form is a checkbox (Unfold's switch on the themed admin), because a default means the field is never "unknown". It stays a three-way Unknown / Yes / No select only when it asked for that: null=True passed explicitly, or no default at all. The column itself is unchanged, so no migration follows. The importer reads the usual spreadsheet spellings — true/false, yes/no, on/off, 1/0, any case — for every boolean column.

🔌 The flags on any field — snap_field()

A Snap*Field is sugar over two things: an ordinary Django field, plus the flags above set as plain attributes. snap_field(field, **kwargs) sets those same attributes on a field instance you already have, so a third-party field — django-money's MoneyField, model-utils's StatusField, phonenumber_field's PhoneNumberField, or anything else SnapAdmin has never imported — gets the same admin/API behaviour without a Snap*Field subclass to rewrite it into:

from django.db import models
from snapadmin.fields import snap_field

class Product(models.Model):
    name = snap_field(models.CharField(max_length=255), searchable=True, filterable=True)

Every reader treats the result exactly like a Snap*Field — the searchable filter, the admin's list/search/filter config, the wysiwyg widget, the tab/row layout — because there is nothing new to read: snap_field() writes the identical attribute names a Snap*Field stores on itself, not a second place to look. It returns the field, so the call composes inline with the field declaration, and it adds no migration for every flag above: the attributes are set after Django's Field.__init__, and SnapAdmin invented every name they use, so deconstruct() has no reason to look at them. editable is the exception that proves it — the one name shared with Django, whose deconstruct() reports live attribute state rather than the arguments the constructor was given, so a wrapper-set value would land in a migration. It is stripped, while an editable= you passed to the Django field's own constructor stays exactly where you put it. An unrecognised kwarg raises ValueError naming it, rather than doing nothing.

snap_field() reaches full parity with every Snap*Field constructor kwarg, including three that used to be refused:

• wysiwyg=True sanitizes on write, identically to SnapRichTextField. The stored value is cleaned on every ORM write path (Model.save(), the REST API, bulk_create) — the wrapper reuses the exact same sanitizer, not a second one, so a wrapped field and a Snap*Field given the same input store byte-identical output. safe_html=True and auto_sanitize=False opt out the same way on both routes; QuerySet.update() stays uncovered on both (Django never calls pre_save() for it).
• required=True is accepted — the one flag that can produce a migration. It mutates null/blank directly to False, False, exactly what a hand-built Snap*Field(required=True) produces; that is schema-affecting by design, unlike every other flag on this page. required=False (the default) is a deliberate no-op on null/blank — it never loosens a field you explicitly built as non-nullable.
• allowed_extensions / allowed_encodings / max_size_bytes attach the same upload validator SnapFileField/SnapImageField build, on a FileField or ImageField (a non-file field raises ValueError naming the two field types, rather than failing later with a confusing error). No migration: the validator is stripped from deconstruct() by identity, the same technique those two field classes already use for their own auto-built validator.

# wysiwyg sanitize-on-write, required, and file validators — all reachable
description = snap_field(models.TextField(), wysiwyg=True)
sku         = snap_field(models.CharField(max_length=32), required=True)
invoice     = snap_field(models.FileField(), allowed_extensions=["pdf"], max_size_bytes=5_000_000)

🧵 You Don't Have to Snap-ify Everything

A SnapModel is a normal Django model; every Django field works on it, and Snap behaviour is opt-in per field — not an all-or-nothing choice for the whole model.

The demo's SearchLog model mixes all three shapes in one class body:

class SearchLog(snap_models.SnapModel):
    # 1. Snap*Field — the sugar. Gets searchable/filterable/etc. built in.
    query = snap_fields.SnapCharField(max_length=255, searchable=True)
    results_count = snap_fields.SnapIntegerField()

    # 2. snap_field() — a plain Django field plus only the Snap behaviour it needs.
    timestamp = snap_fields.snap_field(
        django_models.DateTimeField(auto_now_add=True),
        filterable=True,
    )

    # 3. Plain on purpose — it needs no Snap behaviour at all.
    user_agent = django_models.CharField(max_length=255, blank=True, default="")

A test proves the contrast rather than just asserting it in prose — see TestGetAdminFields.test_searchlog_bare_field_absent_from_search_and_filter_surface: user_agent stays out of both search_fields and list_filter, while timestamp (wrapped with filterable=True) is in list_filter right alongside fields declared with a Snap*Field.

The same freedom applies one level up, to a whole model: @snap_model opts a plain models.Model in without touching its field layer at all. See Two Ways to Declare a Model for the full picture.

📐 Advanced Layout

Control the visual arrangement of your admin forms using row and tab attributes.

class Customer(snap_models.SnapModel):
    # These two will appear on the same line
    first_name = snap.SnapCharField(max_length=100, row="name")
    last_name = snap.SnapCharField(max_length=100, row="name")

    # This field will appear in the "Contact" tab
    email = snap.SnapEmailField(tab="Contact")

🏷 Status Badges

Render coloured pill badges for any choice/status field directly in the admin list view.

from snapadmin import fields as snap

status_badge = snap.SnapStatusBadgeField(
    "is_active",
    [
        snap.SnapStatusBadgeFieldChoice(True, "#065F46", "#D1FAE5", "#10B981"),
        snap.SnapStatusBadgeFieldChoice(False, "#991B1B", "#FEE2E2", "#EF4444"),
    ],
)

# identical, and still supported
status_badge = snap.SnapStatusBadgeField(
    field_name="is_active",
    choices=[...],
)

🔧 Admin Registration

Call register_all_admins() once in your admin.py to register every SnapModel subclass with Django's admin site.

# admin.py
from snapadmin.models import SnapModel
SnapModel.register_all_admins()

To restrict registration to a specific app, pass the app_label argument:

SnapModel.register_all_admins(app_label="myapp")

No SnapModel of your own? The error log, the audit log and the API-token admin come from register_builtin_admins(), which register_all_admins() calls. A project that uses the error monitor, the audit trail or token auth without declaring a SnapModel calls it itself — otherwise SnapErrorMonitorMiddleware records errors no admin page shows, and snapadmin.W031 says so. It is idempotent and keeps a project's own admin for any of those models; pass site= for a custom AdminSite.

# admin.py
from snapadmin.admin import register_builtin_admins
register_builtin_admins()

The primary-key column. The changelist shows the primary key first — referenced by its real name, so a key not called id works — for integer keys only; a UUID key is noise in a list and is left out. Set admin_list_display_pk = True or False on the model to override that either way. Search still covers the key.

A model the admin only shows. Rows the application writes — a log, an import record — set admin_read_only = True: the generated admin offers no add, change or delete, to anyone (a superuser included; a mixin in admin_mixins may grant one back, e.g. has_delete_permission for a clean-up), and the view page shows every field read-only when none carries show_in_form — no flags on fields nobody may edit. snapadmin.W015 skips such a model. It is admin-only: the REST API's equivalent is api_read_only; set both for a table nobody writes through either.

admin_sections is deprecated. It was declared on SnapModel but never read by anything; a model that sets it gets snapadmin.W026. Group form fields with the per-field tab and row flags, or pass fieldsets through admin_overrides.

Extending the generated admin

register_admin() builds and registers a ModelAdmin from a model's Snap field flags; two of its building blocks are public so a project can extend rather than replace them:

• get_admin_fields() returns an AdminFieldSets named tuple — (form_fields, list_display, search_fields, list_filter, autocomplete_fields), in that order. It is a plain 5-tuple by construction (positional unpacking, indexing and len() all keep working), with named access added on top. A sixth member would still be a breaking change — the point of pinning the shape is that such a change is announced, not discovered as a silent ValueError at admin autodiscover.
• get_admin_media() returns the base (js, css) asset lists — theme-sheet selection, the connectivity.js/offline.js gating and de-duplication with js_admin_files/css_admin_files all included. A project overriding register_admin() can call it to extend the real lists instead of copying a snapshot that rots at the next release.

admin_overrides always wins. It is merged onto the generated ModelAdmin last, so a project's own get_readonly_fields or safe_html_<field> display method always takes precedence over the one SnapAdmin generates — regardless of write order, because the generated versions never touch admin_overrides in the first place.

🌐 REST API

CRUD endpoints are generated automatically for all managed models.

Request Examples

All requests authenticate with an API token (see Token Management):

TOKEN="your-40-char-token-key"
BASE="http://localhost:8000/api"

# Discover every available endpoint and its fields
curl -H "Authorization: Token $TOKEN" "$BASE/models/schema/"

# Plain listing — paginated, served by the database
curl -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?page=2"

# Auto-generated field filters (full per-model list visible in Swagger).
# Text fields: bare "?field=value" is an exact, index-usable match; substring
# search is explicit via "__icontains" (also: "__startswith", "__in").
curl -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?available=true&price__gte=100"
curl -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?name__icontains=laptop"

# JSON key-path filters (only for key-paths declared in api_json_filters)
curl -H "Authorization: Token $TOKEN" "$BASE/models/demo/Showcase/?json_field__a__b=value"

# Create, update, delete
curl -X POST -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"name": "Laptop Pro", "price": "1499.00", "available": true}' \
     "$BASE/models/demo/Product/"
curl -X PATCH -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"available": false}' "$BASE/models/demo/Product/42/"
curl -X DELETE -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/42/"

# Product is DUAL → this search runs on Elasticsearch (typo still matches)
curl -i -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?search=laptp"
# HTTP/1.1 200 OK
# X-Snap-Query-Backend: elasticsearch     ← the search ran on ES
# {"count": 3, "results": [{"id": 42, "name": "Laptop Pro", …}, …]}

# ES search combined with DB filters and pagination — still one request
curl -H "Authorization: Token $TOKEN" \
     "$BASE/models/demo/Product/?search=laptop&available=true&page=1"

# The same URL shape on a DB_ONLY model transparently uses SQL icontains
curl -i -H "Authorization: Token $TOKEN" "$BASE/models/demo/Customer/?search=7"
# X-Snap-Query-Backend: database          ← no ES mirror, the DB handled it

# settings.py
SNAPADMIN_ES_QUERY_ROUTING     = True    # global switch (default True)
SNAPADMIN_ES_SEARCH_LIMIT      = 1000    # max hits fetched from ES per routed search
SNAPADMIN_QUERY_BACKEND_HEADER = True    # set False to hide the header in production

# models.py — per-model opt-out (e.g. when one model's ES mirror lags)
class Product(SnapModel):
    es_storage_mode  = EsStorageMode.DUAL
    es_auto_mapping  = True    # without a mapping the mirror indexes ids only (snapadmin.E026)
    es_query_routing = False   # this model's API searches always run on the DB

# Scalar → a `term` clause, list/tuple/set → a `terms` clause
Product.es_filter(available=True, price=[999, 1299])

# Compose with fuzzy full-text: query_string is added as a scored `must`
Product.es_filter(query_string="laptop", available=True)

# A `text` field auto-targets its keyword sub-field; a `__` path reaches into a
# JSON/object mapping the DB can't index — filtered here by nested key path:
Order.es_filter(payload__status="paid")    # → ES field payload.status

# One facet → {field: [{"key": …, "count": …}, …]}
Product.es_aggregate("available")
# {"available": [{"key": True, "count": 42}, {"key": False, "count": 3}]}

# Multiple facets, narrowed by a filter context, capped at N buckets each
Product.es_aggregate("category", "available", size=20, available=True)

# query_string= adds a scored full-text constraint before counting
Product.es_aggregate("category", query_string="laptop")

# Exact number of matches, regardless of the search limit
Product.es_count(available=True)               # → 4217
Product.es_count(price=[999, 1299])            # list → terms clause
Product.es_count(query_string="laptop")        # scored full-text, still exact
Order.es_count(payload__status="paid")         # → ES field payload.status

# Stream every matching document — no 10k ceiling, memory-bounded
for product in Product.es_scan(available=True):
    ...

# Same filter context as es_filter(); tune the batch size per round-trip
for log in SearchLog.es_scan(query_string="error 404", page_size=5000):
    ...

# Stream just the pks — no _source, no in_bulk() hydration
for pk in Product.es_scan(available=True, source=False):
    enqueue(pk)

# Bound the walk to the first 10k pks
first = list(Product.es_scan(available=True, source=False, limit=10_000))

from snapadmin.models import SnapEsUnavailable

# Default: graceful — falls back to the DB when ES is off
Product.es_count(available=True)                       # → DB count() if ES down

# Fail-fast: raise rather than run a query the DB can't scale
try:
    total = Product.es_count(available=True, db_fallback=False)
except SnapEsUnavailable:
    ...  # surface it, retry, alert — never a silent full-table scan

# Same flag on es_filter / es_aggregate / es_scan
for pk in Product.es_scan(available=True, db_fallback=False):  # raises if ES down
    ...

Counting objects — with & without filters

Every list response is paginated and already reports the total matching count in count — no need to page through everything. Request the smallest page to read just the number:

# Total rows (page_size=1 → tiny payload, full count in "count")
curl -s -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?page_size=1"
# {"count": 5231, "next": "...", "results": [ ...1 row... ]}

# Count of a filtered set — "count" reflects the filtered queryset
curl -s -H "Authorization: Token $TOKEN" \
     "$BASE/models/demo/Product/?available=true&price__gte=100&page_size=1"

# Count of a full-text match set (DUAL → ES answers; count = ES hits)
curl -s -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?search=laptop&page_size=1"

• DB_ONLY / DUAL without search — count is an exact SELECT COUNT(*) over the filtered SQL queryset.
• DUAL with ?search= / ES_ONLY — count is the number of ES hits, capped by SNAPADMIN_ES_SEARCH_LIMIT (default 1000). For an exact large-set count, count on the DB (drop ?search=) or raise the limit.

Exporting / bulk-reading optimally

Read large result sets page by page (bounded query + bounded response) rather than with one huge page_size. Follow the next link the API returns:

URL="$BASE/models/demo/Product/?page_size=200&ordering=id"
while [ "$URL" != "null" ]; do
  PAGE=$(curl -s -H "Authorization: Token $TOKEN" "$URL")
  echo "$PAGE" | python -c "import sys,json;[print(r['id']) for r in json.load(sys.stdin)['results']]"
  URL=$(echo "$PAGE" | python -c "import sys,json;print(json.load(sys.stdin)['next'] or 'null')")
done

The same three modes addressed directly from Python:

# DB_ONLY / DUAL — exact, index-backed count
Product.objects.filter(available=True, price__gte=100).count()

# DUAL / ES_ONLY — fuzzy full-text via Elasticsearch
Product.snap_search("laptp", limit=50)     # DUAL: DB queryset in ES-relevance order
SearchLog.snap_search("checkout")          # ES_ONLY: straight from the index

# Memory-flat export of any DB-backed model
for row in Product.objects.all().iterator(chunk_size=2000):
    ...

No-Celery bulk helpers — count + streaming export

Every dynamic model endpoint exposes two synchronous helpers that reuse the same filter, search and permission backends as the list view — no Celery required:

count/ returns just the size of the filtered set — cheap paginator sizing without pulling rows. export/ streams the entire filtered queryset as newline-delimited JSON (application/x-ndjson), one serialized object per line, pulled lazily in chunks (SNAPADMIN_EXPORT_CHUNK_SIZE, default 1000) so huge tables never materialise in memory. Both require the model's view permission. This is the synchronous counterpart to the Celery-backed /api/exports/ jobs above.

fetch-by — an explicit key set, in one call

export streams a filtered result set; fetch-by answers a different question — "give me exactly these records", for a key set large enough that a query string can't hold it. It is a POST that reads, justified by that one constraint alone: there is no other way to express a large explicit value list. field must be unique=True or db_index=True on the target model — anything else answers 400 naming the constraint, closing the unindexed-full-table-scan foot-gun a free-form field name would open. A hard cap, SNAPADMIN_FETCH_BY_MAX_VALUES (default 10000), rejects an oversized values list with 400 rather than silently truncating it — an unbounded list is a denial-of-service vector, and the cap exists before this route does. Same NDJSON streaming, permissions and masking as export (a masked field also can't be used as the lookup key); not supported for ES_ONLY models, which have no DB column to index. Because it never writes, it remains reachable via POST even on an api_read_only model — the read/write policy that gates create on the same URL segment does not apply to it.

Hiding fields from the API — api_exclude_fields

Columns listed in api_exclude_fields are removed from the REST serializer (responses and writes), the GraphQL object type and /api/models/schema/ — while the admin keeps showing them. Use it for PII and internal columns:

class AuditLog(SnapModel):
    action     = snap_fields.SnapCharField(max_length=100, searchable=True)
    user_email = snap_fields.SnapEmailField()     # PII

    api_exclude_fields = ["user_email"]           # never leaves the server via API

Restricting writes — api_write_fields

Field exposure and field writability are separate controls. By default every field not listed in api_exclude_fields also accepts a client-supplied value on REST create/update — set api_write_fields to an explicit list to change that: any field not named there is forced read-only through the API (still returned in responses unless also excluded above). Use it for status flags, ownership FKs and other columns that must only ever change server-side:

class Account(SnapModel):
    owner     = snap_fields.SnapForeignKey(User, on_delete=models.CASCADE)
    is_locked = snap_fields.SnapBooleanField(default=False)   # server-only status flag
    balance   = snap_fields.SnapDecimalField(max_digits=12, decimal_places=2)  # computed

    api_write_fields = ["owner"]   # is_locked / balance never accept a client value

Leaving it unset (the default) keeps every non-excluded field writable, matching prior behaviour — the snapadmin.W004 system check warns on any model that hasn't made the choice explicitly, so the exposure is deliberate rather than an oversight. The warning is grouped: one message names every unguarded model rather than repeating an identical block per model, and a model served read-only (api_read_only, or an api_http_method_names allowlist with no write verb) is skipped entirely — it has no mass-assignment surface to guard.

Read-only models & verb allowlists — api_read_only / api_http_method_names

api_write_fields controls which fields a write may touch; api_read_only removes the write verbs entirely. Set it on an import-only or reference table — one fed by an ETL job or another service, never by API clients — and the dynamic REST API serves it read-only: list/retrieve/count/export work, while POST/PUT/PATCH/DELETE answer 405 Method Not Allowed (no blank-row insert, no silent no-op update):

class ExchangeRate(SnapModel):
    code = snap_fields.SnapCharField(max_length=3, unique=True)
    rate = snap_fields.SnapDecimalField(max_digits=18, decimal_places=6)

    api_read_only = True                       # rates come from the feed, not API clients

# or an explicit verb allowlist (HEAD/OPTIONS are always added):
class AuditEvent(SnapModel):
    api_http_method_names = ["get", "post"]    # append-only: read + create, no update/delete

The verb is rejected in dispatch before any handler runs, so a read-only model can never insert a blank row, and the disallowed verbs are dropped from the OPTIONS Allow header too. api_http_method_names takes precedence over api_read_only when both are set; both default to full CRUD. A model that is field-read-only (api_write_fields = []) yet still write-exposed is flagged by the snapadmin.W007 check, nudging it toward api_read_only.

🎬 User-defined REST actions — @snap_action

CRUD covers create/read/update/delete; a real model usually also needs a handful of operations — approve, refund, recalculate, archive. @snap_action turns a model method into a callable REST endpoint, without hand-wiring a view. Declared on an abstract base or a plain mixin, it reaches every model built on it — like a SnapFunctionField or @snap_property column does; a concrete parent's actions (multi-table inheritance) stay with the parent:

class Order(SnapModel):
    total = snap_fields.SnapDecimalField(max_digits=10, decimal_places=2)

    @snap_action()
    def recalculate_total(self, request):
        self.total = sum(item.quantity * item.price for item in self.items.all())
        self.save(update_fields=["total"])
        return {"total": str(self.total)}

reachable at POST /api/models/demo/Order/<pk>/recalculate_total/. Works identically on a SnapModel subclass or a @snap_model-decorated plain model — the decorator reads the method straight off the class, no field or registry machinery involved.

An action can never widen a model's own policy. Every action URL is wired to every HTTP verb, but Django REST Framework rejects a verb outside the view's http_method_names — the same descriptor api_read_only/ api_http_method_names already drive — with 405 before a handler is even selected. A POST-only action therefore structurally cannot reach a model configured api_read_only = True; there is nothing to bypass. New check snapadmin.E008 catches the same conflict at boot — an action whose declared methods the model's own policy would always reject — before it ships as dead configuration.

Return a plain dict (wrapped as a 200 response) or a rest_framework.response.Response you build yourself, for a custom status or headers. Raise snapadmin.api.views.SnapActionError("message", status=409) to answer with an error — turned into the same {"detail": "message"} envelope every other error path in the API already uses. Every model's registered actions (name, scope, methods, URL) are listed at GET /api/models/schema/ — the concrete, per-model action set drf-spectacular's static schema cannot enumerate for the one generic dispatcher operation it documents instead.

GraphQL has no mutation counterpart, and none is planned. The GraphQL schema is read-only by design (see GraphQL API) — @snap_action is a REST-only surface, stated here explicitly rather than left to be discovered.

Strict query parameters — an unknown parameter is a 400, never ignored

Every query parameter on a model route is one of three things: a declared filter, a parameter the API reads itself (?search=, ?ordering=, ?page=, ?page_size=, ?format=, and ?limit= on export/), or a 400 that names it. A dropped filter would run unfiltered and answer 200 with every row — the worst possible answer for a client about to export or delete "the matching rows" — so ?url__iendswith=.pdf on a field that does not offer that lookup is refused with the lookups it does offer:

GET /api/models/demo/Customer/?email__iendswith=.com
HTTP 400
{"filters": ["Unknown or disallowed filter parameter(s): 'email__iendswith'. Allowed for 'email': email, email__icontains, email__in, email__startswith."]}

The same rule covers an unknown ?ordering= term (400 listing the valid ones), ?search= on a model with no searchable field left for the caller, and any filter on an ES_ONLY model (use ?search= there). It applies to list, count/, export/, fetch-by/ and the detail routes; a @snap_action owns its own query string and is not checked.

No oracle. A parameter on a field the caller may not see — masked PII, or an api_field_permissions read guard they fail — is refused with exactly the message a field that does not exist gets, whatever its value, and no hint ever lists that field's lookups. A masked foreign key is hidden under its column name too (customer and customer_id).

# settings.py
SNAPADMIN_API_STRICT_QUERY_PARAMS = True          # default; False restores the pre-0.1.0b11 silence
SNAPADMIN_API_EXTRA_QUERY_PARAMS = ["_"]          # accept a client's cache-buster on purpose

URL fields filter by their ending. A URLField adds ?field__endswith= and ?field__iendswith= to the library default lookup set (a URL is asked about by its ending as often as by its start). Like icontains they cannot use an index; a model- or project-wide lookup set (below) replaces the default as usual.

class Product(SnapModel):
    sku  = snap_fields.SnapCharField(max_length=32, unique=True)  # exact only — no substring lookup at all
    name = snap_fields.SnapCharField(max_length=200)              # library default: exact + __icontains/__startswith/__in

    # narrow "sku" to exact-only; every other text field on this model still
    # gets the library default lookup set
    api_filter_lookups = {"sku": ["exact"]}

# Per model — every text field on this model, index-friendly by default
class Product(SnapModel):
    api_default_text_lookups = ["exact", "startswith", "in"]   # no __icontains
    api_filter_lookups = {"name": ["exact", "icontains"]}      # …except name, which keeps it

# Project-wide (settings.py) — the safe posture for every model at once
SNAPADMIN_API_TEXT_LOOKUPS = ["exact", "startswith", "in"]     # unset → library default

# find products that were never categorised, or priced in a specific set
GET /api/models/demo/Product/?category_id__isnull=true
GET /api/models/demo/Product/?price__in=9.99,19.99&price__isnull=false

# opt a text field into a null check
class Product(SnapModel):
    api_filter_lookups = {"sku": ["exact", "isnull"]}   # exposes ?sku__isnull=true

class Order(SnapModel):
    payload = snap_fields.SnapJSONField(default=dict)

    api_json_filters = {"payload": ["a.b", "a.c"]}
    # exposes ?payload__a__b=value and ?payload__a__c=value

# settings.py — replaces the whole chain, exactly like DRF's DEFAULT_FILTER_BACKENDS,
# so list every backend you still want alongside your custom one:
SNAPADMIN_API_FILTER_BACKEND = [
    "myapp.filters.MyFilterBackend",
    "rest_framework.filters.OrderingFilter",
]

# a single dotted path (or the class object) is accepted too:
SNAPADMIN_API_FILTER_BACKEND = "myapp.filters.MyFilterBackend"

Vetoing deletes — api_can_delete + SNAPADMIN_API_DELETE_GUARD

Forbid deleting specific objects through the dynamic model API without re-mounting routes. Two extension points are consulted before every DELETE and both must allow it — returning False responds 403:

# 1) Per-model hook (default allows):
class Account(SnapModel):
    is_system = snap_fields.SnapBooleanField(default=False)

    def api_can_delete(self, request) -> bool:
        return not self.is_system          # system rows are undeletable

# 2) Project-wide guard — dotted path to Callable[[request, obj], bool]:
SNAPADMIN_API_DELETE_GUARD = "myproject.guards.protect_superusers"

Model validation errors answer 400, not 500

A django.core.exceptions.ValidationError is not part of DRF's exception hierarchy, so anything raising Django's flavour on a write path — Model.clean(), Model.full_clean(), a guard inside save(), a custom pre_save receiver — used to escape the view and come back as an HTML 500 an API client cannot act on. Every SnapAdmin endpoint now translates it into a 400 that keeps the field names:

class Order(SnapModel):
    status = snap_fields.SnapCharField(max_length=20)
    invoice = snap_fields.SnapFileField(blank=True, null=True)

    def clean(self):
        if self.status == "completed" and not self.invoice:
            raise ValidationError({"invoice": "A completed order needs an invoice."})

# POST /api/models/shop/Order/  →  400
# {"invoice": ["A completed order needs an invoice."]}

A message raised without a field lands under DRF's non_field_errors key, exactly as a serializer-level error does. This needs no configuration and no EXCEPTION_HANDLER of your own — but if you want the same translation on views SnapAdmin never generated, SnapAdmin ships the handler as a drop-in:

# settings.py — optional, only for your own DRF views
REST_FRAMEWORK = {
    "EXCEPTION_HANDLER": "snapadmin.api.exceptions.snap_exception_handler",
}

A project that already configures its own EXCEPTION_HANDLER keeps first refusal: SnapAdmin offers the untouched exception to it first and only steps in where the alternative is the 500 DRF was about to raise, so an existing handler behaves exactly as it did before.

Model rules on the API write path — api_full_clean

A Model.clean() rule is enforced wherever a ModelForm runs — the admin — and nowhere else. The generated serializer validates each field, so the API looks validated, but the cross-field rules are the ones a field validator cannot state ("a completed record needs a file"), and those were silently skipped. The admin and the API then disagreed about what a valid row is.

api_full_clean runs the model's own full_clean() — clean_fields(), clean(), then the model's constraints — inside the serializer's validate(), so the rule answers 400 naming the field:

class Order(SnapModel):
    status  = snap_fields.SnapCharField(max_length=20)
    invoice = snap_fields.SnapFileField(blank=True, null=True)

    api_full_clean = True          # per model…

    def clean(self):
        if self.status == "completed" and not self.invoice:
            raise ValidationError({"invoice": "A completed order needs an invoice."})

# settings.py — …or project-wide, for every registered model at once
SNAPADMIN_API_FULL_CLEAN = True    # a model's own api_full_clean still wins

Off by default, on purpose. Switching it on starts rejecting writes the API previously accepted. That is the correct answer — the admin was already refusing them — but it is a behaviour change, and one that should be a deliberate line in your settings rather than a surprise on upgrade. snapadmin-info reports it under model_validation so an operator can see whether it is actually in use.

Two deliberate limits. Validation is scoped to the fields the serializer can write: an auto_now_add column is empty on an unsaved row and validating it would reject every create with an error no client could act on — the same exclusion a ModelForm makes. And uniqueness is left to DRF's own UniqueValidator/UniqueTogetherValidator, which are already on the generated serializer; a second pass would report the same clash twice. On a PATCH the rule sees the merged row — the stored values with the submitted fields applied — not just the handful of fields the request carried.

⚛️ GraphQL API

SnapAdmin provides a dynamic GraphQL interface powered by Graphene-Django.

• Auto-Schema: All SnapModel subclasses are automatically added to the schema. A database-generated column (models.GeneratedField) appears as its output_field's type, read-only; a field graphene cannot convert costs only that field — it is left out and logged as graphql_field_skipped — never the whole model.
• Secured by default: every resolver requires authentication (admin session or API token) and the model's Django view permission — the same contract as REST — enforced on every relation the query traverses, not just top-level fields. Reading A { relatedB { … } } needs view on both models; a related object you may not view resolves as a Permission denied. error rather than leaking its data. Token allowed_models scopes apply on top.
• PII masking: fields in SNAPADMIN_MASKED_FIELDS are masked in GraphQL output exactly as in the REST API — raw only for superusers, snapadmin.view_raw_pii holders (or whoever SNAPADMIN_PII_ACCESS_CHECK allows), and (per field) holders of a permission named in SNAPADMIN_MASKING_RULES, whose rules apply here too.
• Search: search on a list field follows the REST API's ?search= — the same fields, never one masked or read-guarded for the caller (a match would reveal it), Elasticsearch only where REST routes there, and an error when no field is left to search.
• Unified Fetching: the search argument routes to Elasticsearch for DUAL/ES_ONLY models; first/offset paginate.
• Endpoint: /api/graphql/; GraphiQL follows DEBUG (override with SNAPADMIN_GRAPHIQL_ENABLED).

Field naming

The schema is generated, so field names follow a fixed scheme. For a model Product in an app labelled demo, graphene lower-camel-cases the generated names into demoProduct(id: ID!) (one object by primary key) and allDemoProducts(search, first, offset) (a list). The general form is <applabel><Model> and all<Applabel><Model>s; pluralisation is naïve (a trailing s), so Category → allDemoCategorys. The object type is <Applabel><Model>Type. List results are a plain list, not a Relay connection — select fields directly, with no edges/node wrapper. Fields in a model's api_exclude_fields are dropped from its GraphQL type as well.

Request Examples

# Same API tokens as REST — anonymous callers get "Authentication required."
curl -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"query": "{ allDemoProducts(search: \"laptop\", first: 10) { id name price } }"}' \
     "http://localhost:8000/api/graphql/"

# Single object by id
curl -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"query": "{ demoProduct(id: 42) { name price available } }"}' \
     "http://localhost:8000/api/graphql/"

# settings.py
SNAPADMIN_GRAPHQL_REQUIRE_AUTH = True   # default — never disable in production
SNAPADMIN_GRAPHIQL_ENABLED     = DEBUG  # playground only during development

🔑 Token Management

SnapAdmin uses named API tokens for REST API authentication. Tokens are created and managed in the Django admin under API Tokens, or programmatically:

from snapadmin.models import APIToken

# Create a token for a user, valid for 30 days
token = APIToken.create_for_user(
    user=user,
    token_name="CI Pipeline",
    allowed_models=["myapp.Product", "myapp.Order"],
    expires_in_days=30,
)

Include the token in every API request as an HTTP header:

Authorization: Token <token_key>

Token REST Endpoints

A regular user manages their own tokens — list, create, retrieve, rotate, deactivate, delete — without needing to be a superuser; each lookup is scoped to token.user == request.user (a superuser sees and manages every token).

Token Fields

Rotating a leaked key from Python:

token = APIToken.objects.get(token_prefix="ab12cd34")
new_raw_key = token.rotate()   # old key stops authenticating immediately
# new_raw_key is shown once — store it now, it is not recoverable afterwards

🧮 Quotas & Rate Limits

SnapAnonRateThrottle / SnapUserRateThrottle (SNAPADMIN_THROTTLE_ANON / SNAPADMIN_THROTTLE_USER, above) give one global rate for every anonymous or authenticated caller. The rate is resolved in this order: the setting (None switches the throttle off; a blank value — what an unset environment variable becomes — is no value and falls through, with snapadmin.W029), then REST_FRAMEWORK["DEFAULT_THROTTLE_RATES"] under the scopes snapadmin_anon / snapadmin_user, then the default. The DRF scopes anon/user belong to your own views; when they differ from what SnapAdmin's endpoints enforce, snapadmin.W028 says so. A rate DRF cannot parse — or any numeric SNAPADMIN_* setting int() cannot read — fails manage.py check with snapadmin.E029 instead of answering 500 at the first request, and a project still setting DEFAULT_FILE_STORAGE/STATICFILES_STORAGE (removed in Django 5.1, ignored silently) gets snapadmin.W030, because SnapAdmin's file features use STORAGES.

snapadmin.limits.reserve() is the narrower primitive projects keep rebuilding on top of that: a per-tenant or per-token quota across several time windows at once, a concurrency cap, and a cooldown after an upstream service answers 429 — including for calls your project makes outbound to a third party, which a request-scoped DRF throttle has no way to express at all. It has no opinion about what the key means, so it serves inbound and outbound alike:

from snapadmin.limits import reserve

with reserve(f"tenant:{tenant_id}", windows={60: 100, 3600: 1000}, concurrency=5) as slot:
    if not slot.allowed:
        return too_many_requests(retry_after=slot.retry_after)  # slot.reason: "rate_limited" | "concurrency" | "cooldown"
    call_the_upstream_api()

windows is {period_seconds: max_count} — every window must clear for the reservation to succeed. concurrency, if given, additionally caps how many reservations for the same key may be held at once; releasing the returned object (or using it as a context manager, as above) frees the slot, and an unreleased slot expires on its own after concurrency_timeout seconds (default 300) so a crashed holder can never leak it forever. snapadmin.limits.cooldown(key, seconds) is a separate, explicit signal for the one thing reserve() cannot see on its own: call it after an upstream actually answers 429, and every reserve() for that key fails fast (before touching a window or the concurrency counter) until the cooldown expires.

Two honest limitations, worth reading before trusting this in production:

• Counters are per-process unless CACHES points at a shared backend. The default LocMemCache is private to one process — four Gunicorn workers each enforce the configured limit independently, so the effective ceiling is four times what windows says. Point SNAPADMIN_LIMITS_CACHE_ALIAS at a shared cache (Redis, Memcached, a database cache) before relying on this across more than one worker.
• A cache that evicts a counter under memory pressure fails open, not closed. An evicted counter looks identical to one that never existed, so the next call sees a fresh window and is allowed — the same trade-off any cache-backed rate limiter makes, including DRF's own throttles.

See it wired into an actual outbound call in the demo project's sync_exchange_rates --rate-limit N management command (caps the "call to the external feed" to N runs per minute, plus a concurrency=1 guard against two syncs racing the same feed).

🔍 Elasticsearch Integration

SnapAdmin supports three Elasticsearch storage modes via EsStorageMode. Choose the mode per model based on your use case.

Enable Elasticsearch

Add to your settings.py (or set via env vars):

ELASTICSEARCH_ENABLED = True   # False by default — ES is completely skipped when False
ELASTICSEARCH_URL = "http://localhost:9200"  # local dev or external cluster

Running with Docker

The default docker compose -f demo/docker-compose.yml up does not start Elasticsearch (saves ~512 MB RAM). To enable it:

# Enable ES in your demo/.env
ELASTICSEARCH_ENABLED=True

# Then start the full stack including ES
docker compose -f demo/docker-compose.yml --profile es up --build

# Add Kibana for visualisation (dev only)
docker compose -f demo/docker-compose.yml --profile es --profile dev up --build

External Elasticsearch (production / staging)

Point to any external ES cluster via env vars — no code change needed:

# demo/.env (production)
ELASTICSEARCH_ENABLED=True
ELASTICSEARCH_URL=https://my-cluster.example.com:9200

Storage Modes

Setting the Mode on a Model

The fields you want searchable in Elasticsearch are declared in es_mapping — a dict of {field_name: ES mapping}. (There is no es_index_fields attribute.) For DUAL you may also set es_index_enabled = True.

from snapadmin.models import SnapModel, EsStorageMode
from snapadmin import fields as snap_fields

# DB_ONLY (default — no extra config needed)
class Article(SnapModel):
    title = snap_fields.SnapCharField(max_length=200, searchable=True)
    body  = snap_fields.SnapTextField()

# DUAL — save to PostgreSQL AND Elasticsearch, search via ES
class Product(SnapModel):
    name        = snap_fields.SnapCharField(max_length=200, searchable=True)
    description = snap_fields.SnapTextField()
    price       = snap_fields.SnapDecimalField(max_digits=10, decimal_places=2)

    es_index_enabled = True
    es_storage_mode  = EsStorageMode.DUAL
    es_mapping = {
        "name":        {"type": "text", "analyzer": "standard"},
        "description": {"type": "text"},
        "price":       {"type": "float"},
    }

# ES_ONLY — no DB table (managed=False), data lives only in Elasticsearch
class SearchLog(SnapModel):
    query         = snap_fields.SnapCharField(max_length=255, searchable=True)
    results_count = snap_fields.SnapIntegerField()
    timestamp     = models.DateTimeField(auto_now_add=True)

    es_storage_mode = EsStorageMode.ES_ONLY
    es_mapping = {
        "query":         {"type": "text"},
        "results_count": {"type": "integer"},
        "timestamp":     {"type": "date"},
    }

    class Meta:
        managed = False  # required for ES_ONLY — no DB table is created

Deletes keep the mirror in step

A mirrored model's document leaves the index when its row leaves the database — including through the deletes that never call Model.delete(): a bulk QuerySet.delete() (one SQL DELETE, no per-row Python) and any row swept up by an on_delete=CASCADE. SnapAdmin connects a post_delete receiver at startup for exactly the registered models that mirror to Elasticsearch, so no call site has to remember to clean up after itself:

Product.objects.filter(discontinued=True).delete()   # rows gone — and their documents with them

Two consequences are worth knowing about:

• One Elasticsearch round trip per deleted row. For a large delete, clear the mirror in bulk instead: collect the primary keys first, then hand them to delete_pks_from_es(), which issues a single delete_by_query. That is what the retention purge and stale_sync() do.
• A mirrored model opts out of Django's fast-delete path — the collector has to materialise the rows to send the signal at all. Only mirrored models are affected; a DB_ONLY model has no receiver attached and keeps the fast path untouched.

from snapadmin.models import suppress_es_delete_receiver

pks = list(qs.values_list("pk", flat=True))
with suppress_es_delete_receiver():      # per-thread; the receiver stands down here
    qs.delete()
Product.delete_pks_from_es(pks)          # one bulk delete_by_query, not one call per row

An Elasticsearch outage never breaks the database delete: the receiver logs es_delete_document_failed and the delete stands, the same fail-soft policy as every other ES write path. delete_pks_from_es() is the exception on purpose — it returns whether the mirror was cleared, which is how the retention purge can raise SnapPurgeError instead of reporting a partial purge as a clean one.

Custom analyzers & index settings — es_index_settings

Index-level settings (custom analyzers under analysis, number_of_shards, number_of_replicas, …) are declared in es_index_settings and applied when the index is first created. Existing indexes are never altered — to apply a change, delete the index and run es_reindex_all():

class Product(SnapModel):
    es_storage_mode = EsStorageMode.DUAL
    es_mapping = {
        "name":  {"type": "text", "analyzer": "de_analyzer"},
        "price": {"type": "float"},
    }
    es_index_settings = {
        "analysis": {"analyzer": {"de_analyzer": {"type": "german"}}},
        "number_of_shards": 1,
    }

Automatic mapping — es_auto_mapping

Don't want to write mappings by hand? Set es_auto_mapping = True and the mapping is derived from the model's fields: CharField/TextField → text with a .raw keyword subfield (exact match + aggregations), Email/Slug/URL/UUID/IP/File → keyword, integers & FK → long, Float → double, Decimal → scaled_float, dates → date, JSONField → object. Entries in es_mapping override the derived ones per field:

class SearchLog(SnapModel):
    query         = snap_fields.SnapCharField(max_length=255, searchable=True)
    results_count = snap_fields.SnapIntegerField()

    es_storage_mode = EsStorageMode.ES_ONLY
    es_auto_mapping = True   # derived: query → text + .raw, results_count → long
    # es_mapping = {"query": {"type": "search_as_you_type"}}   # optional override

Querying with es_search()

es_search(query_string=None, limit=20) is the single entry point for search. It runs a fuzzy multi_match over the index when ES is enabled, and gracefully falls back to an ORM query (using the model's searchable fields) when ES is off or unreachable — so the same call works in every environment. snap_search() is a public alias with identical behavior.

# Full-text search (fuzzy, typo-tolerant) — returns a queryset-like result
results = Product.es_search("wireles headphones")     # note the typo — still matches
for product in results:
    print(product.name, product.price)

# Cap the number of hits (default 20)
top5 = Product.es_search("laptop", limit=5)

# No query string → match-all (most-recent first), handy for "browse" views
everything = Product.es_search(limit=100)

# Public alias — identical behavior, nicer name for app code
hits = Product.snap_search("4k monitor")

# ES_ONLY models: es_search() is the ONLY way to read them (no DB table)
logs = SearchLog.es_search("error 404")
recent_logs = SearchLog.es_search(limit=50)

# DB_ONLY models still answer es_search() — it falls back to an ORM
# icontains query across the model's searchable fields:
articles = Article.es_search("django")   # works even with ELASTICSEARCH_ENABLED=False

Re-indexing (DUAL mode)

# Manually trigger a full re-index of every row into ES.
# Streams the table through the bulk API — one round-trip per 500 docs
# (tune with chunk_size=). DB-backed models page a pk__gt keyset cursor
# (not QuerySet.iterator, which buffers the whole result on mysqlclient),
# so memory stays flat even on million-row tables — on every backend:
Product.es_reindex_all()      # {"indexed": N} — or {"skipped": True} if ES is off

# Per-instance indexing happens automatically on save() in DUAL/ES_ONLY mode.
# To force a single object back into the index:
product.index_in_es()
product.delete_from_es()      # remove just this object's ES document

# Via Celery task (recommended for large datasets) — needs a running worker:
from demo.apps.shop.tasks import reindex_products_to_elasticsearch
reindex_products_to_elasticsearch.delay()

📴 Offline Mode

Flip one class attribute to make a model's admin list view survive a dropped connection. SnapAdmin injects snapadmin/js/offline.js into that model's admin pages only — models without the flag ship no extra JavaScript.

class Customer(SnapModel):
    first_name = SnapCharField(max_length=100, show_in_form=True)
    last_name  = SnapCharField(max_length=100, show_in_form=True)

    # Cache this model's list view client-side and enable offline support
    offline_mode = True
    # Prefetch only the 50 most-recent rows for offline view (default: 100)
    offline_cache_limit = 50

⚡ Large-Dataset Performance

SnapAdmin keeps the admin and API responsive as tables grow. Most tuning is automatic; the rest is a few per-model knobs.

Automatic — no admin N+1

When a model is registered, SnapAdmin inspects the columns shown in the list view and auto-derives list_select_related from the ForeignKey columns among them. A list view that renders a related column — or a __str__ that walks a relation — issues one joined query instead of one query per row. Only the FKs you actually display are joined; relations you don't show are never fetched.

The auto-generated REST API applies the same treatment to its querysets — select_related() for ForeignKeys and prefetch_related() for many-to-many fields — with the field lists cached per model to keep introspection out of the request hot path.

class AuditLog(snap_models.SnapModel):
    action = snap.SnapCharField(max_length=100, searchable=True)

    list_per_page = 50              # rows per page (default 100)
    list_max_show_all = 200         # cap on the "Show all" link
    show_full_result_count = False  # skip the unfiltered COUNT(*) on huge tables

# Bulk-seed 100k customers + orders (batched bulk_create, flat memory)
python manage.py seed_large --count 100000

# Time the Order changelist queryset with vs without list_select_related
python manage.py benchmark_list_view --model order

📊  Result
   WITHOUT :    5,001 queries       584.5 ms
   WITH    :        1 queries        37.8 ms

   Query reduction : 5,001 → 1  (5001× fewer)
   Speedup         : 15.5× faster wall time

🚀 Optimizations Guide

The Large-Dataset Performance section above is the reference for SnapAdmin's specific knobs. This guide is the broader picture: the data-access patterns every developer working with large tables should understand, whether or not they use SnapAdmin. Most of it is plain Django/SQL; the SnapAdmin-specific automation is called out where it applies.

# N+1: one query for orders, then one per order for the customer
for order in Order.objects.all():        # 1 query
    print(order.customer.first_name)     # +1 query EACH iteration

# Fixed: a single JOIN pulls customers alongside orders
for order in Order.objects.select_related("customer"):   # 1 query, total
    print(order.customer.first_name)

⚙️ Celery & Periodic Tasks

SnapAdmin ships built-in Celery tasks for background export, indexing, token cleanup, error digests, backups and GDPR retention.

Nothing here runs on its own. SnapAdmin has no daemon and installs no schedule. Each task stays idle until you either point a scheduler at it (Celery Beat or system cron) or — for the event-triggered ones — keep a Celery worker running to pick the job up. Where this site calls a feature "automatic", it means automatic once wired; the table below is what wiring it means.

Task outcomes & monitoring

Every scheduled task below except run_export (which tracks its own status on the SnapExportJob row) returns a summary dict carrying a status key with one of exactly four values, plus a failed list ([] when nothing failed) — every existing key on every task's summary keeps its name and shape, this is purely additive:

A total failure raises (BackupError / SnapPurgeError / AlertDeliveryError / ReindexError) instead of returning — a raised exception is the only thing Celery itself records as a task failure, which is what a task-status monitor watches. Retrying a partial failure would redo the units that already succeeded (e.g. re-uploading a backup that already shipped to two of three destinations), so partial never raises — it is loud instead: status="partial", a populated failed list, and one error-level log line with a stable marker.

This closes a reported incident: a disabled backup schedule ran "successfully" for weeks with no backup ever taken (the task returned {"ran": False, "reason": "disabled"} and Celery recorded a clean success every time), and a silently-failing offsite destination never surfaced anywhere but a log line while the task still reported overall success.

# myproject/celery.py
from celery import Celery

app = Celery("myproject")
app.config_from_object("django.conf:settings", namespace="CELERY")
app.autodiscover_tasks()

from celery.schedules import crontab

CELERY_BROKER_URL = "redis://localhost:6379/0"
CELERY_RESULT_BACKEND = "redis://localhost:6379/0"

CELERY_BEAT_SCHEDULE = {
    "purge-expired-data": {
        "task": "snapadmin.purge_expired_data",
        "schedule": crontab(hour=1, minute=0),   # daily 1am
        "description": "GDPR — data_retention_days, the audit log, and job/file cleanup",
    },
    "purge-expired-tokens": {
        "task": "snapadmin.purge_expired_tokens",
        "schedule": crontab(hour=3, minute=0),   # daily 3am
        "description": "Remove expired API tokens",
    },
    "send-error-digest": {
        "task": "snapadmin.send_error_digest",
        "schedule": crontab(hour=8, minute=0),   # daily 8am
        "description": "Grouped digest of captured error events",
    },
    "send-health-alert": {
        "task": "snapadmin.send_health_alert",
        "schedule": crontab(minute="*/5"),       # every 5 minutes
        "description": "Email an alert when a subsystem (DB/ES) is down",
    },
    "run-db-backups": {
        "task": "snapadmin.run_db_backups",
        "schedule": crontab(minute=30),          # hourly due-check
        "description": "3-2-1 database backups (each destination when due)",
    },
}

No Celery? Every scheduled task above can be driven from system cron instead — see the per-feature sections (GDPR retention, error monitoring, backups) for the equivalent cron lines.

Running Celery in Docker

# demo/docker-compose.yml services:
worker:
  command: celery -A demo.core worker -l INFO
beat:
  command: celery -A demo.core beat -l INFO --scheduler django_celery_beat.schedulers:DatabaseScheduler

💾 3-2-1 Database Backups

Built-in database backups following the classic 3-2-1 rule — 3 copies of your data, on 2 different machines, 1 of them offsite. Dumps are gzip-compressed (file copy for SQLite, pg_dump for PostgreSQL, mysqldump for MySQL) and shipped to up to five destinations, each on its own interval:

Backups are the integration checklist's "Data safety" group in full: two destinations, retention, and — strongly recommended — encryption, covered next.

Configuration

Backups are strictly opt-in, and forgetting the switch is reported. With SNAPADMIN_BACKUP_ENABLED off, a scheduled snapadmin.run_db_backups ends every run as disabled and stores nothing — while the rest of the configuration looks complete. snapadmin.W023 warns when backups are off and a Beat entry, a destination or AGE recipients are configured. Schedule the task only while backups are on, or silence the check on an environment that keeps them off on purpose.

SNAPADMIN_BACKUP_ENABLED = True               # strictly opt-in (default: False)
SNAPADMIN_BACKUP_KEEP = 7                     # dumps kept per destination (oldest pruned)

# Copy 1 — same server
SNAPADMIN_BACKUP_LOCAL_DIR = "/var/backups/snapadmin"
SNAPADMIN_BACKUP_LOCAL_EVERY_HOURS = 24       # daily

# Copy 2 — server on the same network (mounted share)
SNAPADMIN_BACKUP_NETWORK_DIR = "/mnt/backup-server/snapadmin"
SNAPADMIN_BACKUP_NETWORK_EVERY_HOURS = 24     # daily

# Copy 3 — offsite FTP/FTPS
SNAPADMIN_BACKUP_FTP_HOST = "backup.example.com"
SNAPADMIN_BACKUP_FTP_PORT = 21
SNAPADMIN_BACKUP_FTP_USER = "backup"
SNAPADMIN_BACKUP_FTP_PASSWORD = "secret"
SNAPADMIN_BACKUP_FTP_DIR = "/snapadmin"
SNAPADMIN_BACKUP_FTP_TLS = True               # FTPS — recommended offsite
SNAPADMIN_BACKUP_REMOTE_EVERY_HOURS = 168     # weekly

# Copy 3 (alternative) — offsite over SSH/SFTP; pip install django-snapadmin[backup]
SNAPADMIN_BACKUP_SFTP_HOST = "offsite.example.com"
SNAPADMIN_BACKUP_SFTP_PORT = 22
SNAPADMIN_BACKUP_SFTP_USER = "backup"
SNAPADMIN_BACKUP_SFTP_KEY_FILE = "/etc/snapadmin/id_ed25519"  # key auth; or set _PASSWORD
SNAPADMIN_BACKUP_SFTP_KNOWN_HOSTS = "/etc/snapadmin/known_hosts"  # unset = ~/.ssh/known_hosts
SNAPADMIN_BACKUP_SFTP_DIR = "snapadmin"       # relative to the SSH login directory
SNAPADMIN_BACKUP_SFTP_EVERY_HOURS = 168       # weekly

# Copy 3 (alternative) — any S3-compatible object store; pip install django-snapadmin[s3]
SNAPADMIN_BACKUP_S3_BUCKET = "my-backups-bucket"
SNAPADMIN_BACKUP_S3_PREFIX = "snapadmin/"           # optional key prefix inside the bucket
SNAPADMIN_BACKUP_S3_REGION = "eu-central-1"
# ENDPOINT_URL is the one setting that turns this into a transport for five
# providers — leave it unset for AWS, or point it at MinIO / Backblaze B2 /
# Hetzner Object Storage / Wasabi:
SNAPADMIN_BACKUP_S3_ENDPOINT_URL = "https://s3.eu-central-1.wasabisys.com"
# Leave both unset to use the ambient credential chain instead (env vars, a
# shared config file, or an IAM role / instance profile) — the right choice
# on AWS; a static key there would be a downgrade.
SNAPADMIN_BACKUP_S3_ACCESS_KEY_ID = "AKIA..."
SNAPADMIN_BACKUP_S3_SECRET_ACCESS_KEY = "..."
SNAPADMIN_BACKUP_S3_EVERY_HOURS = 168               # weekly

A configured-but-incomplete S3 destination is snapadmin.W011 at manage.py check — advisory, like the AGE recipient check above: an unparseable SNAPADMIN_BACKUP_S3_ENDPOINT_URL, or a bucket set with neither an explicit access key pair nor a detected ambient AWS credential source (env vars, a shared credentials file, an ECS/IRSA role — an EC2 instance profile can't be detected without a network call, so that case is silently accepted).

Hetzner Storage Box — a worked SFTP recipe

A Storage Box account works with the existing SFTP destination once four things are right:

SNAPADMIN_BACKUP_SFTP_HOST = "u123456.your-storagebox.de"
SNAPADMIN_BACKUP_SFTP_PORT = 23                              # not 22 — Storage Box's external SSH port
SNAPADMIN_BACKUP_SFTP_USER = "u123456-sub1"                  # a sub-account, not the main account
SNAPADMIN_BACKUP_SFTP_KEY_FILE = "/etc/snapadmin/id_ed25519"  # key-based auth

1. Port 23, not the SSH default 22 — Storage Box's external SFTP/SCP endpoint.
2. A sub-account (Hetzner Robot → Storage Box → Sub-accounts) scoped to its own subdirectory, so a leaked key can't reach the whole box.
3. Key-based auth — upload the sub-account's public key in the Robot panel; set SNAPADMIN_BACKUP_SFTP_KEY_FILE to the matching private key's path.
4. Pre-populate known_hosts — SnapAdmin's SFTP transport rejects an unknown host key on purpose (no trust-on-first-use), so the host key has to already be there before the first backup runs:

   ssh-keyscan -p 23 -H u123456.your-storagebox.de >> ~/.ssh/known_hosts

   Run this once as the same user the backup process runs as (e.g. during deployment), or make one manual sftp -P 23 u123456-sub1@u123456.your-storagebox.de connection and accept the prompt. In a container, write the file to a fixed path and name it — the ~ above is resolved at run time, and a docker exec without a USER line is root, not your service user:

   ssh-keyscan -p 23 -H u123456.your-storagebox.de > /etc/snapadmin/known_hosts
   SNAPADMIN_BACKUP_SFTP_KNOWN_HOSTS = "/etc/snapadmin/known_hosts"

A Storage Box sub-account is scoped to its own subdirectory, which makes it exactly the case snapadmin.W022 exists for: leave SNAPADMIN_BACKUP_SFTP_DIR at its default / (the sub-account's own root) or give it a relative path such as "db". An absolute /backups is a path the sub-account cannot see, and the upload — not the directory change — is what fails.

Running the backups

Backups run as a separate process from your web workers — via Celery Beat or cron. The hourly Beat task is only a due-check: each destination actually fires when its own *_EVERY_HOURS interval has elapsed (last-run times persist in a state file, surviving restarts):

# Celery Beat:
"run-db-backups": {
    "task": "snapadmin.run_db_backups",
    "schedule": crontab(minute=30),   # hourly due-check
}

# ...or plain cron, without Celery:
30 * * * *  python manage.py snapadmin_db_backup            # ships only what is due
python manage.py snapadmin_db_backup --force                # all configured destinations, now
python manage.py snapadmin_db_backup --destination remote   # one destination, now

Keeping the backup hour where you put it. By default a destination's window is measured from its last actual run, so each run books the next one a full interval after it finished. A daily backup that takes a few minutes therefore creeps forward a few minutes a day, and over a month walks out of the quiet hours it was scheduled for and into working ones. SNAPADMIN_BACKUP_ALIGN_TO_SCHEDULE = True measures the window from the planned slot instead, pinning the schedule to the clock time of the first run however long any individual run takes. Slots missed while the process was down collapse into a single catch-up run rather than one run per missed slot. It is opt-in and the drift-tolerant default is unchanged; turning it on needs no state-file surgery, and turning it back off is equally safe.

Encrypting backups (AGE)

Set SNAPADMIN_BACKUP_AGE_RECIPIENTS and every dump is encrypted with age in-stream, before a single byte reaches disk — pg_dump/mysqldump/SQLite → gzip → age → the .age-suffixed file. No plaintext or plain-gzip artefact is ever written, not even transiently, and a mid-pipeline failure leaves nothing behind rather than a partial or corrupt one. With the setting empty (the default), nothing changes — this is exactly today's behaviour.

age's headline property is what makes this useful for a team rather than one person: encrypt once to any number of recipients, and any one of their private keys decrypts the file independently — no shared secret, no re-encryption to add a reader.

# One setting turns it on — a list, because multi-recipient is the default shape:
SNAPADMIN_BACKUP_AGE_RECIPIENTS = [
    "age1scr8rpq5lxtaqqskkawrft82at865e4j3gvs30cjv79q5qq3gc7qwj8um3",  # ops laptop
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBaU... deploy@ci",           # an SSH public key works too
]

# Restore-only — a *path* to a private-key file, never the key material itself.
SNAPADMIN_BACKUP_AGE_IDENTITY_FILE = "/etc/snapadmin/age-identity.txt"

# "auto" (default) prefers the in-process pyrage library, falls back to the `age`
# CLI if pyrage isn't installed. Pin explicitly with "pyrage" or "binary".
SNAPADMIN_BACKUP_AGE_BACKEND = "auto"

An entry that doesn't look like a valid age (age1…) or SSH (ssh-ed25519 … / ssh-rsa …) public key is snapadmin.W008 at manage.py check — advisory, since the other recipients still work; the malformed one only fails when a backup actually runs.

Both backends produce and consume the identical, standardised age file format — a bundle encrypted with one restores fine with the other, or with the plain age command run by hand on a jump host with no Django involved at all.

Don't have a keypair yet? Generate one from the library, through either backend:

python manage.py snapadmin_age_keygen

The private key is written once, to a new .age/ directory at the project root, and is never printed or logged — only the public recipient is, ready to paste into SNAPADMIN_BACKUP_AGE_RECIPIENTS above. Before writing anything, the command checks the project's .gitignore for a rule that would already exclude .age/ — recognising more than a literal .age/.age/ line (a leading-slash anchor, a **/ prefix or /** suffix, and a blanket dotfile rule like .*) — and appends one, with a visible message, if none is found. Every run closes with a reminder: move the private key to a secure location (a password manager, a secrets vault, an encrypted volume) and delete the local .age/ directory — it is a convenience for generation, never long-term storage for a private key.

Key rotation, stated plainly because it surprises people: adding a recipient only affects backups made after the change — it does not retroactively unlock older bundles. Removing one is the same in reverse: an already-encrypted bundle stays decryptable by every key it was originally encrypted to. A private key never appears in a setting, in snapadmin_info output, or in a log line — only the recipient (public key) list and the identity file path are ever recorded; the identity is supplied only at restore time, from that file.

Media and .env in the bundle

SNAPADMIN_BACKUP_INCLUDE extends a run beyond the database — a subset of db, media, env. The default is ["db"], so this is entirely opt-in and today's behaviour is unchanged unless you add to it. Each part ships as its own file sharing one run's timestamp, alongside one always-unencrypted manifest.json sidecar — never a single combined archive, so --only db at restore time can fetch and decrypt just the part you actually need.

SNAPADMIN_BACKUP_INCLUDE = ["db", "media", "env"]   # default: ["db"]

# media: MEDIA_ROOT, tarred and streamed — never built in memory.
SNAPADMIN_BACKUP_MEDIA_EXCLUDE = ["cache/**", "*.tmp"]        # glob patterns, relative to MEDIA_ROOT
SNAPADMIN_BACKUP_MEDIA_SIZE_WARNING_BYTES = 10 * 1024 ** 3     # log a warning past this size (10 GiB) — never aborts

# env: your project's .env file (or any file holding secrets).
SNAPADMIN_BACKUP_ENV_FILE = "/etc/snapadmin/project.env"

Naming env with no file behind it is reported too: snapadmin.W024 warns when SNAPADMIN_BACKUP_ENV_FILE is unset or does not point at a file, because the run would otherwise skip that part and still report success.

An unreadable media file (permission error, a broken symlink, one that vanished mid-run) is skipped with a warning, not an aborted backup — a broken thumbnail must not cost you the database. The manifest lists snapadmin/Django versions, the DB engine, every part actually produced with its ciphertext checksum (so a truncated upload is caught before any decrypt attempt is made), the full recipient list, and a ready-to-paste snapadmin_restore command — see Restoring a backup.

Retention (SNAPADMIN_BACKUP_KEEP) applies per part: a run that includes media keeps its own newest N media bundles independently of the database dump's own N, so opting into media never starves the database backup's retention headroom.

Daily, weekly and monthly retention

"Keep the newest N" alone either keeps too little history or too much recent noise. Three tiers sit beside it — SNAPADMIN_BACKUP_KEEP_DAILY, _WEEKLY and _MONTHLY — each keeping the newest backup of the N most recent days, ISO weeks or months that have a backup (counted over the backups, never over the clock, the way borg and restic count). A backup survives when any rule keeps it, and the newest run is always kept — a KEEP of 0 used to delete every backup, the one just written included (snapadmin.W036 now names it). Every destination — local, network, FTP, SFTP, S3 — prunes through the one rule, per part, from the timestamp in the file name.

SNAPADMIN_BACKUP_KEEP = 3           # the last three runs, whatever their age
SNAPADMIN_BACKUP_KEEP_DAILY = 7     # + one a day for a week
SNAPADMIN_BACKUP_KEEP_WEEKLY = 4    # + one a week for a month
SNAPADMIN_BACKUP_KEEP_MONTHLY = 12  # + one a month for a year

A tier finer than a destination's own cadence keeps one backup per run there — a daily tier of 7 on a weekly offsite destination spans seven weeks — and snapadmin.W037 says so per destination. All three default to 0, which leaves KEEP alone, exactly as before.

↩️ Restoring a Backup

manage.py snapadmin_restore restores a bundle snapadmin_db_backup produced. Dry-run is the default — without --confirm it prints exactly what would happen (which parts, which database, whether the .env file would be overwritten) and changes nothing:

# See what backups are available (a local path, or from a configured destination):
python manage.py snapadmin_restore --list
python manage.py snapadmin_restore --list --destination sftp

# Plan only — prints what would happen, touches nothing:
python manage.py snapadmin_restore snapadmin-manifest-20260826-020000.json

# Pull straight from a destination and restore only the database:
python manage.py snapadmin_restore sftp:snapadmin-manifest-20260826-020000.json \
    --only db --identity /etc/snapadmin/age-identity.txt --confirm

Before touching anything, the manifest's per-part checksum is verified against the fetched ciphertext — a truncated or corrupted upload is refused rather than half-restored. An encrypted bundle restored with no --identity prints exactly how many recipients it needs and their fingerprints, instead of failing on an opaque parse error.

Restoring db is not live-safe: existing connections are terminated and, for PostgreSQL, the database is dropped and recreated before the dump loads. Run it in a maintenance window. SQLite is a straight file replace after closing the connection.

Restore drills — --database

A periodic restore into a throwaway database is what proves a backup works. Declare the drill database as an extra alias and restore into it; default is never touched:

# settings.py
DATABASES = {
    "default": {...},
    "restore_drill": {**DATABASES["default"], "NAME": "app_restore_drill", "USER": "drill"},
}

# The drill — plan first, then restore and verify:
python manage.py snapadmin_restore sftp:snapadmin-manifest-20260826-020000.json --database restore_drill
python manage.py snapadmin_restore sftp:snapadmin-manifest-20260826-020000.json --database restore_drill \
    --identity /etc/snapadmin/age-identity.txt --confirm

• Only db goes to another alias. Media and .env have no per-alias target and would land on the live system, so a bare selection restores db alone and --only media/env is refused.
• An alias that is default in disguise is refused — the same SQLite file, or the same host, port and database name — so a typo cannot turn a drill into an overwrite of production.
• No CREATEDB needed. On PostgreSQL the drill database is emptied by recreating its public schema instead of dropdb/createdb; the drill role only has to own that database.
• The result is verified. The command prints the row count of every table in the drill database, and a restore that produced no tables fails instead of reporting success. The pre-restore snapshot is skipped — it covers default, which a drill never touches.

The pre-restore safety net: snapadmin_rollback

Before a --confirmed restore touches anything, it automatically snapshots the current live state of every part it is about to overwrite — the same parts, encrypted the same way a real backup would be — into SNAPADMIN_RESTORE_SNAPSHOT_DIR (default: a rollback/ subdirectory of the local backup directory), and prints the snapshot id prominently before proceeding. If the snapshot itself fails, the restore is aborted — never on a best-effort basis.

# List available snapshots:
python manage.py snapadmin_rollback --list

# Roll back to the most recent one (dry-run by default, same --confirm):
python manage.py snapadmin_rollback --confirm

# Roll back to a specific one:
python manage.py snapadmin_rollback 20260826-020000 --identity /etc/snapadmin/age-identity.txt --confirm

Snapshots have their own retention, SNAPADMIN_RESTORE_SNAPSHOT_KEEP (default 3) — separate from SNAPADMIN_BACKUP_KEEP, since these are short-lived safety nets, not backups, and must not compete with the real retention policy for disk. --no-snapshot exists for the operator who knows better and prints a loud warning when used.

🚨 Error Monitoring & Alerts

Optional notifications about server errors, built on one middleware. Every unhandled exception and 5xx response is stored as an ErrorEvent — browsable in the admin under Error Events — and two alerts keep the team informed (by email, by chat webhook, or both — see Alert channels):

• Spike alert — when SNAPADMIN_ERROR_ALERT_THRESHOLD errors occur within SNAPADMIN_ERROR_ALERT_WINDOW_MINUTES (default 20 errors / 15 min), one email is sent immediately. A cooldown guarantees at most one alert per window.
• Daily digest — a grouped 24-hour report: identical errors are merged by exception class + endpoint, ordered by frequency, and capped at SNAPADMIN_ERROR_DIGEST_MAX_GROUPS groups so the email stays readable.

Setup

# settings.py
MIDDLEWARE = [
    # ... Django middleware ...
    "snapadmin.middleware.SnapErrorMonitorMiddleware",
]

# Spike alert (defaults shown)
SNAPADMIN_ERROR_ALERT_THRESHOLD = 20          # errors ...
SNAPADMIN_ERROR_ALERT_WINDOW_MINUTES = 15     # ... within this window → email
SNAPADMIN_ERROR_ALERT_EMAILS = ["ops@example.com"]

# Daily digest
SNAPADMIN_ERROR_DIGEST_EMAILS = ["team@example.com"]  # falls back to ALERT_EMAILS
SNAPADMIN_ERROR_DIGEST_MAX_GROUPS = 20
SNAPADMIN_ERROR_RETENTION_DAYS = 30           # ErrorEvents older than this are purged

Scheduling the digest

# Celery Beat — the send time is entirely yours:
"send-error-digest": {
    "task": "snapadmin.send_error_digest",
    "schedule": crontab(hour=8, minute=0),
}

# ...or plain cron, without Celery:
0 8 * * *  python manage.py snapadmin_send_error_digest
python manage.py snapadmin_send_error_digest --hours 12   # custom window

Settings reference

Health alerts — email when a subsystem is down

A third, independent channel watches infrastructure rather than application errors. It runs the same probes as snapadmin_info --health-check — database, Elasticsearch, the REST API and GraphQL — and emails when one reports a failure, so an outage reaches an operator instead of only the logs. Each probe honours its feature toggle (ELASTICSEARCH_ENABLED, SNAPADMIN_REST_API_ENABLED, SNAPADMIN_GRAPHQL_ENABLED), so a subsystem you turned off is never a false alarm. Run it on a schedule — the snapadmin.send_health_alert Celery task, or the snapadmin_health_alert management command from cron (it also exits non-zero while a probe is failing, so it doubles as a monitoring gate). A cache-based cooldown limits a persistent outage to one email; a recovery re-arms it so the next outage alerts immediately.

# settings.py — recipients fall back to SNAPADMIN_ERROR_ALERT_EMAILS
SNAPADMIN_HEALTH_ALERT_ENABLED = True
SNAPADMIN_HEALTH_ALERT_EMAILS = ["ops@example.com"]
SNAPADMIN_HEALTH_ALERT_COOLDOWN_MINUTES = 60

# Celery Beat — probe every few minutes:
"send-health-alert": {
    "task": "snapadmin.send_health_alert",
    "schedule": crontab(minute="*/5"),
}

# ...or plain cron, without Celery:
*/5 * * * *  python manage.py snapadmin_health_alert
python manage.py snapadmin_health_alert --force   # re-send within the cooldown

Alert channels — Slack, Discord, Teams, Telegram

Every alert above (spike, digest, health) is delivered by the same set of channels. Email is one of them; the others are chat webhooks, posted with the standard library — SnapAdmin adds no dependency for alerting. Thresholds, grouping and the cooldown are shared by all channels, so adding a webhook changes where an alert goes, never how often it fires.

# settings.py — read the URLs from the environment, never hard-code them
SNAPADMIN_ALERT_WEBHOOKS = [
    {"type": "slack",    "url": os.environ["SLACK_ALERT_WEBHOOK"]},
    {"type": "discord",  "url": os.environ["DISCORD_ALERT_WEBHOOK"]},
    {"type": "teams",    "url": os.environ["TEAMS_ALERT_WEBHOOK"]},
    {"type": "telegram", "token": os.environ["TELEGRAM_BOT_TOKEN"],
                         "chat_id": os.environ["TELEGRAM_CHAT_ID"]},
    # Only page the on-call channel for outages, not for the daily digest:
    {"type": "json", "url": "https://ops.example.com/hooks/snapadmin",
     "events": ["health", "error_spike"], "timeout": 3},
]

SNAPADMIN_ALERT_EMAIL_ENABLED = True   # False → chat-only, no mail server needed
SNAPADMIN_ALERT_WEBHOOK_TIMEOUT = 5    # seconds per POST

🪵 Structured Logging

SnapAdmin provides a structlog-based logging setup with colourised output for development and JSON output for production.

from snapadmin.logging_config import configure_logging

# Human-readable coloured output (development)
configure_logging(log_level="INFO", json_logs=False)

# JSON lines (production / Docker)
configure_logging(log_level="WARNING", json_logs=True)

from snapadmin.logging_config import get_logger

logger = get_logger(__name__)

logger.info("order_created", order_id=42, total=199.90)
logger.warning("es_unavailable", model="Product")
logger.error("payment_failed", reason="card_declined")

🔒 GDPR Data Retention

SnapAdmin gives you a one-line retention window on any SnapModel to help comply with EU data retention laws (GDPR) — a model-wide age, a per-row deadline, or both. The attributes below declare what counts as expired; a scheduled task you wire up is what actually deletes it. The same snapadmin.purge_expired_data task also covers two things that are not SnapModels at all — the audit log and, if you opt in, finished export/reindex job rows and their files — see the full purge table below for everything the package can auto-delete.

class AuditLog(SnapModel):
    action     = SnapCharField(max_length=100)
    created_at = SnapDateTimeField(auto_now_add=True)
    attachment = SnapFileField(upload_to="audit/", blank=True, null=True)

    # Rows older than 90 days count as expired (deleted when the purge runs)
    data_retention_days  = 90
    data_retention_field = "created_at"    # default — any DateTimeField works
    data_retention_files = ["attachment"]  # delete the file with the row (#RET2c)

How it works

Per-row deletion dates — data_retention_date_field

data_retention_days is one constant for the whole table, which can express "delete 90 days after this row was created" and nothing else. When each record arrives with its own agreed expiry — a delete_at an upstream supplier sets per row — name that column instead:

class SuppliedRecord(SnapModel):
    created_at = SnapDateTimeField(auto_now_add=True)
    delete_at  = SnapDateTimeField(null=True, blank=True)   # set per row by the supplier

    data_retention_date_field = "delete_at"   # this row's own deadline
    data_retention_days       = 90            # the house rule for rows without one

The two combine, and the more specific rule wins:

Set it alone, with no data_retention_days at all, for a table where every row carries its own deadline and there is no house rule. The scheduled purge, the management command and snapadmin.W012 all treat a model configured this way as a model with retention — a per-row deadline is a retention rule on its own. On an ES_ONLY model the deadline column must be mapped as a date in the index, like data_retention_field.

Rows a PROTECT foreign key still holds

A tree whose retention is decided per row — parent = ForeignKey("self", on_delete=PROTECT) — has due parents whose children are not due yet. Such a row is kept, not allowed to abort the model's purge: everything else that is due goes, a fully due subtree goes leaves first in the same run, and the kept rows are retried on the next run once whatever protects them has expired too. A kept row keeps its data_retention_files as well — files are deleted only for rows that are actually deleted. The same applies to RESTRICT.

An ES_ONLY model has no other copy, so its purge query failing — or answering with documents it could not delete — raises SnapPurgeError and the run reports the model as failed, instead of returning 0 as though nothing had been due. The same failures list in a delete_by_query answer makes delete_pks_from_es() report False for a DUAL mirror.

It is reported, never swallowed: purge_expired() returns a SnapPurgeResult — still an int, the purged count — whose skipped_protected attribute counts the kept rows; the management command prints a SKIPPED line per model, and the Celery task's summary carries them under skipped_protected.

Running the cleanup

# Via Celery Beat (recommended — add to CELERY_BEAT_SCHEDULE):
"purge-expired-data": {
    "task": "snapadmin.purge_expired_data",
    "schedule": crontab(hour=1, minute=0),
}

# Manually via management command:
python manage.py snapadmin_purge_expired_data           # live run — deletes records
python manage.py snapadmin_purge_expired_data --dry-run  # preview only — no deletes

# Programmatically, per model (returns the number purged):
AuditLog.purge_expired()              # delete now
AuditLog.purge_expired(dry_run=True)  # count what *would* be deleted, delete nothing

Purging across every storage layer

The purge is storage-aware — it removes expired records from wherever the model actually keeps them, so personal data never lingers in a secondary store:

File payloads: files before rows

Deleting the row but not the file it references is the wrong outcome for a GDPR retention feature — the row is what remembers the file's name, so an orphaned file becomes unreachable and undeletable without a separate storage sweep. data_retention_files closes that gap, with two rules that make it safe to run unattended:

• Files are deleted before their row. If a file cannot be removed (a storage error), the row — and therefore the file's name — is left intact and purge_expired() raises SnapPurgeError instead of silently continuing, so the purge is retryable on the next run rather than orphaning the file permanently. A missing file (already gone) is treated as already-done, not an error.
• A path another live row still references is never deleted. Two rows can legitimately point at the same storage path; before removing a file, SnapAdmin checks whether any other row outside this purge still needs it and skips the delete if so (one extra query per distinct path) — "we deleted a file another row still points at" is unrecoverable, "we left a file behind" is a storage sweep.

dry_run=True touches nothing — no file is deleted and no row is counted as skipped, exactly as before data_retention_files existed.

Replaced and deleted files leave storage — delete_replaced / delete_on_delete

Django leaves a file in storage when its row's file is replaced or the row is deleted; with a dated upload_to every replacement is another orphan, and storage keeps personal data the database no longer points at. Two opt-in flags on SnapFileField / SnapImageField close that:

class Contract(SnapModel):
    scan = snap_fields.SnapFileField(
        upload_to="contracts/%Y/%m/",
        delete_replaced=True,    # the old file goes once a replacement is saved
        delete_on_delete=True,   # the file goes with its row — bulk deletes included
    )

A file is removed after the transaction commits (a rolled-back save or delete removes nothing), and only when no other row of the model still names it — asked through the base manager, so a row hidden from the current user or tenant still counts. Bulk deletes are covered (QuerySet.delete() and the admin's "delete selected" fire the per-row signal once a field opts in). A storage error is logged (snapadmin.files.delete_failed) and never raised into the request. Both flags are Snap-only: no migration. A deferred field (.only()) has no name to remove and is left alone. The retention purge's data_retention_files shares the same "still named by another row" rule, and a GDPR subject-request delete removes the files of every file field of the rows it erases, flags or not.

The audit log, and export/reindex job cleanup

Two more tables grow forever unless something purges them, and neither is a SnapModel — so snapadmin.purge_expired_data covers each explicitly, alongside the per-model sweep above, every time it runs:

• The audit log (SnapadminAuditLog) — governed by SNAPADMIN_AUDIT_RETENTION_DAYS (default 365, i.e. on by default). Rows are append-only (save/delete raise once persisted); the purge uses QuerySet.delete(), the one sanctioned bypass of that guard, so the trail itself stays tamper-evident right up until the retention window closes. This does not change what manage.py snapadmin_audit_export --purge does — that command keeps working exactly as before, reading the same setting independently.
• Export/reindex jobs (SnapExportJob/SnapReindexJob) — governed by SNAPADMIN_EXPORT_RETENTION_DAYS, unset (off) by default — unlike the two sweeps above, this one deletes files a project may deliberately want to keep (a downloaded report, an archival export), so it needs an explicit opt-in. Once set, finished job rows past the window are deleted along with their published files (files before rows, same ordering rule as data_retention_files), and a second pass sweeps any export file left behind with no job row at all — the state a worker that died mid-export leaves. This assumes the export storage location (see Async Export) is used exclusively for SnapAdmin exports; do not point it at a bucket with unrelated files.

Every purge the package performs, in one place

Retention is real but was historically scattered across four unrelated tables — this table is the single answer to "what gets cleaned up, by what, and how often should I schedule it":

All five rows above run from the beat schedule in Celery & Periodic Tasks — the demo project's own CELERY_BEAT_SCHEDULE schedules every one of them.

🧾 GDPR Subject-Access Requests

data_retention_days answers "how old is too old"; a subject-access request answers a different question — "show (or delete) everything about this one person, right now". manage.py snapadmin_subject_request answers it by walking every registered model's own subject_path declaration, the same one snapadmin.E011/E012 require every registered model to state explicitly (declared, not guessed).

Declaring who a subject is

class Customer(SnapModel):
    email = SnapEmailField(...)
    is_data_subject   = True     # a valid --model entry point
    subject_identifier = "email"  # the field holding the raw identifier
    subject_path        = "email"  # a subject's own path always equals its identifier

class Order(SnapModel):
    customer = SnapForeignKey(Customer, on_delete=PROTECT)
    subject_path = "customer__email"   # one relation hop to the subject

class SomeOtherModel(SnapModel):
    subject_path = None   # explicit — this model carries nothing subject-scoped

subject_path is required on every registered model — None is a valid, explicit answer, but silence is not: snapadmin.E011 fails manage.py check for any registered model that never declares it at all, and snapadmin.E012 catches a declared-but-malformed one (a subject model whose own path doesn't match its identifier, a path over 3 relation hops, one that doesn't resolve via this model's own forward relations, or a multi-hop path on an ES_ONLY model — see the reference table below). The decorator route accepts the same three keywords: @snap_model(subject_path=..., is_data_subject=..., subject_identifier=...).

Running a request

# Export everything reachable from this subject, unmasked, as one bundle:
python manage.py snapadmin_subject_request export \
    --model demo.Customer --identifier alice@example.com --user dpo_operator

# ...optionally AGE-encrypted to a recipient (repeatable) — the plaintext is removed once encrypted:
python manage.py snapadmin_subject_request export \
    --model demo.Customer --identifier alice@example.com --user dpo_operator \
    --recipient age1qy...

# Preview a deletion — dry-run by default, deletes nothing:
python manage.py snapadmin_subject_request delete \
    --model demo.Customer --identifier alice@example.com --user dpo_operator

# Actually delete, once the preview looks right:
python manage.py snapadmin_subject_request delete \
    --model demo.Customer --identifier alice@example.com --user dpo_operator --confirm

Export: reuses the existing export machinery, unmasked

One SnapExportJob per matched model, run synchronously with filters={subject_path: identifier} and requested_by set to the resolved operator — the same masking bypass that already applies to a PII-privileged requester elsewhere produces the unmasked export, so there is no second "skip masking" code path to get wrong. A manifest.json lists every file, the row count per model, and who requested it. Pass one or more --recipient age/SSH public keys to encrypt the whole bundle in place afterward (the same AGE machinery backups use) — recommended, since an unmasked SAR bundle is exactly the kind of thing that should not sit in plaintext once written.

Deletion: dry-run by default, refuses rather than routes around a block

Both dry-run and --confirm run the identical pre-flight — a Django deletion Collector walk over every matched row, which discovers cascade spillover on its own (a more complete picture than the subject_path declarations alone: deleting a Customer also takes its CustomerProfile, since that relation is on_delete=CASCADE) — so the dry run is a genuine preview of what --confirm would do, not a separate, weaker check. If any matched row is protected (on_delete=PROTECT — the demo's Order.customer uses it), the whole run refuses up front and deletes nothing, rather than deleting in dependency order to route around it:

$ python manage.py snapadmin_subject_request delete --model demo.Customer \
      --identifier alice@example.com --user dpo_operator --confirm
REFUSED — deleting these rows is blocked by a protected relation: demo.Order
Nothing was deleted. Resolve the blocking rows manually (delete or reassign them) before retrying.

Stored files go with the rows. Every file field of every row the run erases — whatever its cleanup flags — has its file removed from storage after the rows are gone, unless another row still names the same file. The dry run prints the count (DRY RUN files: 2), never the names: a file name is often personal data itself. A file storage refuses to delete is reported (FAILED files: …) rather than raised — the rows are already gone, and the operator must see what is left.

A deletion audit entry is written after a successful run — action delete, model subject_access_deletion, the per-model row counts, the number of files removed, and the operator. This entry cannot itself be swept away by a later deletion for the same subject: SnapadminAuditLog is deliberately outside the general SnapAdmin registry (see Unalterable Audit Trail), so it carries no subject_path at all and is structurally invisible to this command's own matching sweep.

Reference

🔐 Field Encryption

Encrypted model fields keep ciphertext in the database and hand your code the ordinary Python value. All of that rests on one thing being configured correctly: the keyset. This section is the keyset — where the key comes from, how it rotates, and the startup checks that stop a column from quietly staying plaintext.

Two halves, and they are read in this order: the field types — what you declare, what you get back and what you give up — and the keyset below, which everything else rests on.

Declaring an encrypted field

Each type is its plain counterpart plus encryption. Nothing above the field changes — a SnapEncryptedDateField still renders a date picker, still validates a date and still hands your code a datetime.date. Only the column changes, to text holding a snap1. envelope.

from snapadmin import fields as snap, models as snap_models

class Patient(snap_models.SnapModel):
    name    = snap.SnapCharField(max_length=200, searchable=True)
    ssn     = snap.SnapEncryptedCharField(max_length=32, show_in_list=False)
    email   = snap.SnapEncryptedEmailField(blind_index=True)   # still findable by value
    notes   = snap.SnapEncryptedTextField()

patient.ssn = "123-45-6789"
patient.save()
# the column now holds: snap1.2026-09.<nonce>.<ciphertext>
Patient.objects.get(pk=patient.pk).ssn      # → "123-45-6789"

None is written as SQL NULL and never encrypted, so __isnull keeps working and "" stays distinguishable from "no value". Re-saving a loaded row, a bulk_update(), a QuerySet.update() and a fixture reload all refuse to encrypt an already-encrypted value a second time — double encryption is the one failure here that is both silent and permanent.

What you can still query

The blind index

blind_index=True adds a <field>_bi sibling column holding HMAC-SHA256(index key, value), and rewrites __exact and __in onto it — so the SQL that reaches the database carries no plaintext in any parameter, query log or slow-query report. The index key is HKDF-derived from the keyset with the field's own app.model.field as derivation info, never the encryption key itself and never shared between columns. Adding unique=True moves the constraint to the index, where it means what you meant — a unique constraint on ciphertext is satisfied by every row, since each has its own nonce.

Lookups match under every key in the keyset, so prepending a key during a rotation keeps existing rows findable with no rebuild and no downtime; snapadmin_encrypt_fields --rotate converges the stored indexes afterwards.

Case is significant, matching Django's own exact; only Unicode NFC normalisation is applied, so the same string typed composed or decomposed still matches.

The sibling column is treated as exactly as sensitive as the column it indexes — masked in the API, exports and the changelist, and never given a generated API filter. It is a deterministic function of the value, so serving it to a caller who is denied the field itself would hand them an offline equality oracle over it.

Where the plaintext does not go

The field decrypts transparently, which means every layer above the ORM receives an ordinary Python value and would happily emit it. Each surface has a tested default:

Adopting an existing column

Switching a column that already holds data to an encrypted field is a schema change in your project — the column type becomes text, plus the optional _bi sibling — and the rows already in it stay plaintext. Every read of one raises until it is converted, which is correct: the alternative is a column silently holding a mixture.

1. Change the field, makemigrations, migrate. This is the one place field-level encryption cannot honour SnapAdmin's "avoid migrations" norm.
2. python manage.py snapadmin_encrypt_fields --adopt --models app.Model — reports what it would convert, and changes nothing.
3. Re-run it with --apply.

python manage.py snapadmin_encrypt_fields --adopt --apply     # encrypt what was already there
python manage.py snapadmin_encrypt_fields --rotate --apply    # move rows onto the active key
python manage.py snapadmin_encrypt_fields --reindex --apply   # rebuild blind-index columns

It writes nothing without --apply, walks by primary key in batches (--batch-size, resume a killed run with --start-pk), and counts a row it cannot convert instead of stopping on it — the run finishes, then exits with an error listing the failures by primary key.

Three caveats worth reading before you ship

Renaming breaks decryption. Every ciphertext is authenticated against its own app_label.model.field — that is what stops a value being lifted out of one column and pasted into another. It also means renaming the app, the model or the field changes the binding, and rows written under the old name stop decrypting until they are re-encrypted. Plan a rename like a data migration.

A restore needs the keyset that wrote the dump. A database dump carries ciphertext, so restoring it into an environment with a different keyset produces rows that cannot be read — which looks exactly like data corruption and is not. Compare the keyset fingerprint that manage.py snapadmin_info prints between the two environments before concluding anything.

Dropping a key is irreversible. A key can only leave the keyset once no row still names it. --rotate is what makes that true; there is no way back afterwards.

Keys and rotation

Generating a key

python manage.py snapadmin_encryption_key            # the first key
python manage.py snapadmin_encryption_key --rotate   # a key to prepend

The key is printed once, as the environment line to paste into your secret store — the command writes it nowhere. --rotate prints the new key plus the ids already in the keyset, never their material: rotating is prepending one line.

Where the key comes from

Four sources, most secure first. The first one configured wins — sources are never merged, so a stray environment variable can never silently half-override a secret store.

SNAPADMIN_ENCRYPTION = {
    # Ordered: the FIRST key encrypts, EVERY key decrypts.
    "KEYS": [{"id": "2026-09", "key": "<32 bytes, base64url>"}],

    # Better — keep the material out of settings entirely:
    "KEY_PROVIDER": "myapp.secrets.load_snapadmin_keys",
    "KEY_FILE": "/run/secrets/snapadmin_encryption",

    "STRICT": True,   # default
}

Rotation

The keyset is ordered: the first key encrypts everything written from now on, and every key in the list can decrypt. Rotating is therefore prepending, with no downtime and no migration:

1. manage.py snapadmin_encryption_key --rotate and prepend the printed line.
2. Deploy. New writes use the new key; existing rows keep opening with the old one, because every ciphertext records the id of the key it was written with.
3. Re-encrypt the stored rows, then drop the old key from the list — not before. Dropping a key while rows still name it makes those rows permanently unreadable.

Two rules the package enforces for you

Never SECRET_KEY. Reusing Django's SECRET_KEY as encryption key material is the classic mistake here: SECRET_KEY is rotated for session and CSRF reasons, and the damage only becomes visible after a rotation, when every encrypted column has already become unreadable. snapadmin.E017 fails manage.py check if the two are the same value.

Key material is never rendered. No repr, no str, no log line, no exception message and no snapadmin_info section emits key bytes — only a key's id and its fingerprint, a short digest safe to print and to compare between environments. A restore into an environment whose keyset fingerprint differs is the one failure that looks like data corruption but is not, which is why the fingerprint is displayable at all.

Startup checks

🏘️ Multi-Tenancy

Row-level tenant isolation, opt-in per model. A model declares itself tenant-scoped and adds a tenant column; every generated surface then requires a bound tenant to see or write any row of it — default-deny, not opt-out. Nothing about a model that never opts in changes.

from snapadmin import models as snap_models
from snapadmin.tenancy import tenant_field

class Order(snap_models.SnapModel):
    customer = snap_models.SnapForeignKey(Customer, on_delete=models.PROTECT)
    tenant_id = tenant_field()      # a plain, nullable, indexed CharField
    tenant_scoped = True            # opts this model into isolation

tenant_field() returns a pre-configured CharField — nullable so the migration it adds never breaks an existing row, indexed for the filter every scoped query runs. Override any keyword (max_length=, …) to fit a project's own tenant-identifier shape; declare a real ForeignKey by hand instead if the tenant is itself a project model. tenant_field (the model attribute, distinct from the factory function above) renames the column when set — otherwise it is "tenant_id".

class Invoice(snap_models.SnapModel):
    organisation = models.ForeignKey(Organisation, null=True, on_delete=models.PROTECT)
    tenant_scoped = True
    tenant_field = "organisation"   # the field name or its column, "organisation_id" — both work

With a ForeignKey the resolver returns the tenant row's primary key (not the row): SnapAdmin writes it to the column (organisation_id) on every create path — the admin, its inlines, the REST API and the importer — and compares a value a request body names by that key, so tenant_field may spell either the field name or the column.

Resolving the current tenant

Add the middleware, then point it at a resolver:

# settings.py
MIDDLEWARE = [
    # ... after AuthenticationMiddleware, so the resolver can read request.user
    "snapadmin.tenancy.SnapTenantMiddleware",
]
SNAPADMIN_TENANT_RESOLVER = "myproject.tenancy.resolve_tenant"       # request -> tenant value | None
SNAPADMIN_TENANT_USER_RESOLVER = "myproject.tenancy.resolve_for_user" # user -> tenant value | None

Both SnapAdmin middlewares — this one and SnapErrorMonitorMiddleware — run in sync and async mode: under ASGI they keep the middleware chain async (a database-reading resolver or the error recorder runs through sync_to_async) instead of making Django switch the whole chain to sync mode with a thread hop per request.

SNAPADMIN_TENANT_RESOLVER runs once per request, resolving the caller's tenant from whatever a project's own auth carries — a claim on the session/JWT, a subdomain, an SSO group. Unset, every request resolves to no tenant — the correct fail-closed default until a project configures one. SNAPADMIN_TENANT_USER_RESOLVER is the second half: an async export or import job has no request when a Celery worker actually runs it, so the tenant is resolved from the submitter once, at job-creation time, and stamped onto the job row for the worker to replay. See demo/core/tenancy.py for a complete (illustrative, email-domain-based) pair of resolvers wired into the demo project.

What "default-deny" means concretely

The one escape hatch: use_all_tenants()

Reserved for background code whose job is inherently cross-tenant — the retention purge (a row's age decides whether it is purged, not its tenant) and the Elasticsearch reindex (the index must stay complete across every tenant, or a verify pass would mismatch by construction against the whole index). Application code must never reach for it to work around a scoping failure:

from snapadmin.tenancy import use_all_tenants

with use_all_tenants():
    Order.objects.all()   # every tenant's rows, deliberately and audibly

Cross-tenant jobs under a project's own tenancy

The retention purge, the Elasticsearch reindex (snapadmin_reindex, the admin reindex API, es_reindex_all()) and the GDPR subject request read every tenant's rows. Each enters the model's snap_background_context(purpose) — purpose is "retention", "reindex" or "subject_request" — and the default returns use_all_tenants(), which is all SnapAdmin's own tenant_scoped needs. When the rows sit behind a tenancy of the project's own — a manager that refuses to run without its context, or PostgreSQL row-level security — return that context instead (keep use_all_tenants() in it too if the model is also tenant_scoped):

from contextlib import ExitStack, contextmanager

from django.db import connection, transaction

class Invoice(SnapModel):
    @classmethod
    @contextmanager
    def snap_background_context(cls, purpose):
        with ExitStack() as stack:
            stack.enter_context(super().snap_background_context(purpose))  # SnapAdmin's scoping
            stack.enter_context(transaction.atomic())
            with connection.cursor() as cursor:  # RLS: this transaction may see every tenant
                cursor.execute("SET LOCAL app.bypass_rls = 'on'")
            yield

The reindex runs its whole pass inside the context, so a long reindex holds that transaction open; a project that would rather not can bind a context variable of its own instead. A plain @snap_model model may declare the same classmethod; without one it gets use_all_tenants(). The alternative is to move the model onto tenant_scoped.

Creating rows as an operator bound to every tenant

A resolver may return snapadmin.tenancy.ALL_TENANTS for an operator who works across tenants — every tenant's rows become readable. Creating a row then needs the tenant it belongs to: the generated add form shows the tenant field, required, and the REST API takes the tenant named in the request body (a foreign-key tenant by its key). With no tenant named, the create is refused exactly as with no binding at all; under a single-tenant binding the field stays hidden and the bound tenant is forced, as before. The change form never shows it — an operator does not move rows between tenants. The importer refuses ALL_TENANTS as its tenant (it is a reading binding, not a tenant), and a row it would create with no single tenant bound fails instead of becoming an orphan. The audit entry of an operator's create records the tenant chosen.

A NULL tenant is unassigned data, not shared data

The column is nullable so the migration it adds never breaks an existing row — but a row with no tenant value matches no tenant's filter, by ordinary SQL equality semantics. It is simply invisible to every tenant until something assigns it, never a fallback any caller can reach.

Reference

🏢 Enterprise Config v0.1.0a8

Four settings-driven features that fit SnapAdmin's zero-boilerplate philosophy. Every one is inert on a stock single-database install — it does nothing until you configure it.

# settings.py
DATABASES = {"default": {...}, "read_replica": {...}}
SNAPADMIN_ANALYTICS_DB_ALIAS = "read_replica"

PII data masking

Declare sensitive fields once. They are obfuscated in the admin changelist, dropped from the admin change form, and masked in both REST API and GraphQL responses for anyone who is not a superuser or a holder of the snapadmin.view_raw_pii permission — or, when SNAPADMIN_PII_ACCESS_CHECK is set, anyone that callable allows. Emails become a***@domain.com (just ***@domain.com when the local part is one or two characters, so the first character is never the whole of it), other values +3********78. Masking is enforced on every path that could otherwise leak the raw value: a masked field can't be targeted by ?field=, ?ordering=field or ?search= for an unprivileged caller (it is answered exactly like a field that does not exist — a 400 under strict query parameters, the default), the async export (POST /api/exports/) masks rows unless the requester holds PII access, and the audit trail's changes diff is masked in the admin and in snapadmin_audit_export (pass --reveal-pii for the raw diff). An audit row's object label is str(instance) — often a name or an email — so on a model with any masked field it reads Customer #12 instead, in the audit changelist, its search, the change form, the timeline and the export, for anyone who may not see every masked field of that model raw. Django's own history message stores a masked field's values masked. A JSON field is masked value by value and keeps its keys; a rule's constant replacement replaces each value, not the object.

# settings.py
SNAPADMIN_MASKED_FIELDS = {
    "users.UserModel": ["email", "phone_number"],
    "customers.Profile": ["passport_number", "billing_address"],
}
# Grant trusted staff raw access:
#   assign the "snapadmin | api token | Can view unmasked PII data" permission.

A key that doesn't resolve to an installed model (snapadmin.E001) or a field name that doesn't exist on it (snapadmin.E002) is a startup error, not a silent no-op — masking a typo'd field would otherwise fail open. So is a value in the wrong shape (snapadmin.E028): a bare string instead of a list, a number, a list where a rule map belongs. Where the intent is readable it is masked anyway — "email" masks the email field rather than the fields e, m, a…, and a list under SNAPADMIN_MASKING_RULES masks those fields with the built-in masker — and the check still stops the deploy until it is written properly.

Who may see raw PII — your rule instead of the permission. Every masking surface (admin, REST, GraphQL, exports, the audit diff, the subject request) asks one function, snapadmin.masking.user_can_view_pii. By default it answers with the snapadmin.view_raw_pii permission; set SNAPADMIN_PII_ACCESS_CHECK to a callable (user) -> bool (or its dotted path) to decide by an SSO role, a membership table — whatever the project's access model is. Only an answer that is True unlocks; an async function is refused (its coroutine would be truthy for everyone). It replaces the permission step only: anonymous and inactive users stay masked, superusers stay unmasked, and a per-field rule's permission still unlocks its field. A callable that raises answers "masked" and logs snapadmin.pii_access_check_failed; one that cannot be imported is snapadmin.W035 at startup — fail closed, never open.

SNAPADMIN_PII_ACCESS_CHECK = "myproject.access.can_view_pii"

# myproject/access.py
def can_view_pii(user):
    return "dpo" in getattr(user, "sso_roles", ())

Masking an app before it is installed. Rolling out module by module, a project can write the masking of an app that is not installed yet: list its label in SNAPADMIN_MASKING_PENDING_APPS = ["billing"]. A key of a listed app that is not installed is reported as the informational snapadmin.I002 ("masked once installed") instead of E001/E003; once the app is installed — under its label or its module name — its keys are checked like any other, and snapadmin.W034 asks to remove it from the list. A field a rule names that the model does not have is snapadmin.E004. Nothing is excused without the list — a typo in an app label still errors, because it would otherwise unmask the app it meant.

Hand-written admins. The changelist masking lives in snapadmin.models.PIIMaskingAdminMixin, which generated admins get automatically. A model you register yourself — a custom user model derived from AbstractUser is the usual case — needs it as the first base of its ModelAdmin; without it the admin shows those fields unmasked, which snapadmin.W025 reports at manage.py check (every AdminSite is checked, not only the default one). A masked column keeps the field's own verbose_name, translation included.

from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
from snapadmin.models import PIIMaskingAdminMixin

class UserAdmin(PIIMaskingAdminMixin, BaseUserAdmin):
    ...

Per-field rules — SNAPADMIN_MASKING_RULES

The setting above says which fields are sensitive; this one says how each is obfuscated, and who may see it raw. A rule takes a pattern (a regex applied with re.sub), a replacement (on its own, a flat redaction of the whole value), and/or a permission that unlocks that one field for whoever holds it — without granting the blanket snapadmin.view_raw_pii, which reveals every masked field of every model.

# settings.py
SNAPADMIN_MASKING_RULES = {
    "customers.Profile": {
        # keep the last four digits, star the rest → ************1111
        "card_number": {"pattern": r"\d(?=\d{4})", "replacement": "*"},
        # first two and last two characters only → SE…03
        "iban": {"pattern": r"^(\w{2}).*(\w{2})$", "replacement": r"\1…\2"},
        # never shown below the field permission
        "billing_address": {"replacement": "[redacted]",
                            "permission": "customers.view_profile_address"},
    },
}

Naming a field here also declares it sensitive, so this setting works on its own — SNAPADMIN_MASKED_FIELDS stays optional and unchanged, and a field listed only there keeps the built-in masker. Rules apply on every surface that masks: the admin changelist, the REST serializer, GraphQL, background exports and the audit-log diff. The matching check is masking.user_can_view_pii(user, "app.Model.field") — the field argument is additive, so existing calls are unaffected.

Patterns are compiled once and cached. One that fails to compile, one whose replacement references a group it does not have, one shaped like a catastrophic-backtracking bomb (a quantified group containing a quantifier, (a+)+), and any value longer than 4096 characters all fall back to the built-in masker and log the reason — every failure path degrades to more masking, never to raw data. So does a pattern that matches nothing in a non-empty value — "keep the first three characters" against a two-character value would otherwise hand the value back unchanged. A rule naming a model or field that does not exist would instead fail open, so it is a startup error (snapadmin.E003–E005) rather than a silent no-op.

🔐 Field-level permission guards — api_field_permissions

Masking says how an already-visible field is displayed; api_field_permissions says whether it is visible or writable at all — a different, orthogonal question. Declare a Django permission per field, per side:

class Employee(SnapModel):
    salary = snap_fields.SnapDecimalField(max_digits=10, decimal_places=2)

    api_field_permissions = {
        "salary": {"read": "hr.view_salary", "write": "hr.change_salary"},
    }

A caller lacking the named permission never sees the field's existence: absent from a REST response (not null, not an error — the key itself is gone) or nulled in GraphQL (the schema is built once at import time, so a per-request field cannot be removed from the response shape the way REST's serializer can — a documented, deliberate asymmetry, not an inconsistency). A denied write answers an explicit 400 naming the field, because a silently dropped write is a data-loss bug the caller cannot detect — a required field a role can't write simply cannot be created by that role, which is the correct, if blunt, outcome.

Rows 2 and 4, precisely: the permission gate decides whether the field appears at all; masking decides whether what appears is raw or starred. Gate first, mask second — a field can carry both a permission rule and a masking rule at once, and the two compose in that fixed order rather than racing.

Works on both doors: a SnapModel subclass sets it as a plain class attribute; a @snap_model-decorated plain model sets it via registry.register(Model, api_field_permissions={...}) (the decorator's own api_field_permissions= keyword is a follow-up). Applied so far to the two surfaces an external API consumer actually reaches — REST (the serializer, plus the ?field=/?ordering=/?search= oracle-prevention filters, same precedent as PII masking above) and GraphQL; the admin form and background export are a follow-up.

SSO / OAuth2 login buttons

SnapAdmin only renders the providers you already wired into AUTHENTICATION_BACKENDS / URLconf (django-allauth, social-auth, mozilla-django-oidc) — it adds no auth dependency. Configure once and get login-page buttons plus a public GET /api/sso-providers/ endpoint for headless frontends.

# settings.py
SNAPADMIN_SSO_PROVIDERS = {
    "azure":    {"label": "Login with Microsoft Enterprise", "url": "/accounts/azure/login/"},
    "keycloak": {"label": "Corporate Keycloak SSO", "url": "/api/v1/auth/keycloak/"},
}
# TEMPLATES → OPTIONS → context_processors: add "snapadmin.sso.sso_providers"
# In your admin/login.html override: {% include "snapadmin/sso_buttons.html" %}

A provider entry with no url, a protocol-relative url, or an absolute url outside SNAPADMIN_SSO_ALLOWED_HOSTS (when that list is non-empty) is dropped from the rendered buttons rather than shown broken — unset (the default) applies no host restriction, since most deployments legitimately point providers at an external identity provider. manage.py check catches all three at startup: a missing url is snapadmin.W003; a protocol-relative or off-allowlist url is snapadmin.W005.

# settings.py
SNAPADMIN_NESTED_APPS = {"snapadmin": "auth"}   # move snapadmin models under "auth"
SNAPADMIN_HIDDEN_APPS = ["silk"]                # hide these groups from the index
SNAPADMIN_APP_LABELS  = {"auth": "Administration"}  # rename a group heading

🧩 Module-level permissions — a recipe, not a subsystem

A project that grants staff rights per business module ("Helpdesk", with sub-packages an administrator assigns) does not need a permission model above Django's: Django's groups and custom permissions already are that layer, and every SnapAdmin surface already checks Django permissions. SnapAdmin deliberately does not ship a second, parallel system — two permission models that can disagree are a security bug waiting to happen. The recipe:

# helpdesk/models.py — one permission-only model per module: no table, just codenames
class HelpdeskModule(models.Model):
    class Meta:
        managed = False
        default_permissions = ()          # no add/change/delete/view for a table that isn't there
        permissions = [
            ("use_helpdesk", "Can use the Helpdesk module"),
            ("helpdesk_tickets", "Helpdesk: tickets"),          # one per sub-package
            ("helpdesk_knowledge_base", "Helpdesk: knowledge base"),
        ]

# A data migration (or the admin) creates one Group per role and assigns the codenames:
#   "Helpdesk agent" → use_helpdesk + helpdesk_tickets
#   "Helpdesk lead"  → everything above + helpdesk_knowledge_base

• Your own views: @permission_required("helpdesk.helpdesk_tickets") or request.user.has_perm(...) — plain Django.
• A generated REST action: @snap_action(permission="helpdesk.helpdesk_tickets") gates it on the module permission instead of the model's own.
• A field inside a model: api_field_permissions names the module permission per field and side.
• The admin: override has_view_permission/has_change_permission through admin_overrides to require the module permission as well as the model's.
• API tokens stay AND-ed with their owner's permissions, so a token can never reach a module its user is not in.

Unalterable audit trail DORA / ISO 27001

Django's built-in LogEntry is minimal and editable straight from the DB. SnapAdmin records a richer, append-only SnapadminAuditLog for every admin create/update/delete — who (actor + IP + User-Agent), what (target object + before/after field diff) and when (tz-aware timestamp). Rows are immutable at the ORM level (save/delete raise once persisted) and the admin is fully read-only.

# settings.py — on by default
SNAPADMIN_AUDIT_LOG_ENABLED = True
SNAPADMIN_AUDIT_RETENTION_DAYS = 365

# Export for a SIEM (newline-delimited JSON or CSV):
python manage.py snapadmin_audit_export --format json > audit.jsonl
python manage.py snapadmin_audit_export --since 2026-01-01 --action delete
python manage.py snapadmin_audit_export --purge   # also prune rows past retention

For defence against direct database tampering, layer a DB trigger / append-only role on top — the ORM guard protects the admin and application paths.

Reading the trail — diffs and the per-object timeline

The diff is stored as {"field": {"old": …, "new": …}} and rendered in the admin as a field-level table: one row per field, the value before, the value after. Values keep their JSON-native type, so 42 stays distinguishable from "42"; anything without a JSON representation (Decimal, dates, UUIDs) is stored as text, and a JSON field's list or object is stored as JSON. A relation is stored by its key on both sides ({"old": 3, "new": 7}) and a many-to-many as the sorted list of primary keys ({"old": [2], "new": [2, 5]}) — so re-saving the same selection in another order records nothing, and moving a row to a namesake still does. Keys, never the related object's label: a label is whatever that model's __str__ prints, often a name or an email, and the trail's masking only knows the audited model's own fields. The old/new key names are part of the on-disk format and will not change.

Each entry's Object column links to that object's timeline — every change ever recorded for it, newest first, each as the same diff table:

/admin/snapadmin/snapadminauditlog/timeline/<app_label>/<model>/<object_id>/

Both views mask through SNAPADMIN_MASKED_FIELDS and SNAPADMIN_MASKING_RULES, and both are gated on the audit log's own view permission — the same one that already lists these rows — so reading the trail is never a way around masking. That includes the entry's object label: on a model with a masked field it is shown as <Model> #<pk> to a reader who may not see that model's PII, and is not searchable for them. A long history is capped at the 100 most recent entries per page (override timeline_max_entries on the model admin); snapadmin_audit_export remains the way to read all of it.

Large-dataset performance

Every SnapAdmin admin auto-derives list_select_related from the FK columns it shows, and the REST API auto-select_relateds FKs and prefetch_relateds M2M — no N+1, zero config. On multi-million-row tables the changelist's SELECT COUNT(*) is the costliest query; EstimatedCountPaginator swaps it for PostgreSQL's instant reltuples estimate on unfiltered listings, staying exact for small or filtered views and non-PostgreSQL databases.

# settings.py — on by default
SNAPADMIN_ESTIMATED_COUNT = True
SNAPADMIN_ESTIMATED_COUNT_THRESHOLD = 100000   # estimate only above this row count

# Per model: also skip the second, unfiltered COUNT(*) the admin runs for "X total"
class BigModel(snap_models.SnapModel):
    show_full_result_count = False

Async background export Celery

Large synchronous exports time out. SnapAdmin offloads them to a Celery worker that streams a model's rows to CSV, JSON or XLSX. The line-based formats (csv, json) are written in resumable chunks, paged by a primary-key cursor rather than OFFSET so a concurrent insert/delete elsewhere in the table can't shift the window and skip or duplicate a row. Each chunk is written and fsync-ed to disk before its checkpoint is persisted, so a worker crash between the two can only leave an unconfirmed tail to discard on resume — never a duplicate. Jobs are also single-flight (an atomic pending/failed → processing claim stops a redelivered task or a manual re-trigger from running the same job on two workers at once) and cancellable mid-run. A worker that crashes mid-processing leaves the job stuck there until an operator resets it to pending to retry — there is no heartbeat/TTL auto-recovery. Jobs are private to their requester; the caller needs the target model's view permission. Finished files are published through Django's storage API (SNAPADMIN_EXPORT_STORAGE, a dotted Storage class) rather than read off the worker's local disk, so download/ works even when the web process and the worker don't share a filesystem; left unset it defaults to local FileSystemStorage, unchanged from before.

curl -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"app_label": "demo", "model": "Product", "export_format": "csv"}' \
     http://localhost:8000/api/exports/
# → {"id": "…", "status": "pending", "progress_percent": 0, "eta_seconds": null, …}

# Same job as a spreadsheet — needs pip install django-snapadmin[xlsx]
curl -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"app_label": "demo", "model": "Product", "export_format": "xlsx"}' \
     http://localhost:8000/api/exports/

XLSX — the container format extra

export_format="xlsx" writes a real workbook via openpyxl, installed with the [xlsx] extra. Values keep their types, so price arrives as a number Excel can sum and a DateTimeField as a date — converted to the project's current timezone and stripped of its tzinfo, which Excel has no concept of. Text that begins with = is stored as text, never as a formula: exported row data must not become something a spreadsheet executes when the file is opened.

A workbook is a zip archive that only becomes readable once it is closed, so it cannot be appended to chunk by chunk the way a CSV can. Rows are streamed into a temporary spool (memory stays at one chunk, whatever the export's size) and the finished workbook is moved into place in one step. Two consequences worth knowing before you pick the format:

• No resume. A re-dispatched XLSX job re-exports from the first row instead of continuing from its checkpoint — progress and cancellation work as usual, resume does not.
• No partial download. A cancelled or failed XLSX job leaves no file at all, where a cancelled CSV leaves the rows it managed to write.

Requesting xlsx without the extra is rejected by POST /api/exports/ with a 400 naming it, rather than accepted as a job that could only fail in the worker.

Custom row sources — SNAPADMIN_EXPORT_SOURCES

By default an export streams model.objects.filter(**filters) as raw column rows. Three shapes don't fit that: a result set defined by a structured Elasticsearch query (routing it through filters would force the DB-fallback scan the ES query exists to avoid); an explicit key list ("export exactly these records" — encoding it as a __in filter re-evaluates a giant clause on every cursor page); or a custom document shape (not raw values() rows). Register a source and the writer keeps everything else — the resumable pk-cursor chunking, progress, cancellation and storage — while your source owns only what rows to emit and how each looks:

# settings.py — {name: "dotted.path.to.factory"}, factory(job) -> source
SNAPADMIN_EXPORT_SOURCES = {
    "product_catalog": "myapp.exports.product_catalog_source",
}

# myapp/exports.py
class ProductCatalogSource:
    def __init__(self, job):
        qs = Product.objects.all()
        if job.filters:
            qs = qs.filter(**job.filters)
        self._qs = qs.order_by("pk")
    def field_names(self):                 # CSV header / row-dict keys
        return ["id", "catalog_line"]
    def count(self):                       # drives progress / ETA
        return self._qs.count()
    def iter_batches(self, *, cursor, chunk_size):
        # yield (rows, next_cursor); next_cursor is checkpointed and passed
        # back on resume, so continue deterministically from it. Mask here.
        while True:
            page = self._qs.filter(pk__gt=cursor) if cursor is not None else self._qs
            rows = list(page[:chunk_size].values("id", "name", "price"))
            if not rows:
                return
            batch = [{"id": r["id"], "catalog_line": f'{r["name"]} (${r["price"]})'} for r in rows]
            cursor = str(rows[-1]["id"])
            yield batch, cursor

def product_catalog_source(job):
    return ProductCatalogSource(job)

Create the job with source="product_catalog" (a field on SnapExportJob) and it runs through your source instead of the ORM default; a blank source is byte-for-byte the built-in export. The demo registers exactly this product_catalog source (demo/apps/shop/export_sources.py). An unknown source name fails the job cleanly (never the worker). Because your source owns PII masking on the rows it emits, apply masking there if the document exposes protected fields — use snapadmin.masking.mask_field(app_label, model, field, value, user), the same choke point the built-in source goes through, so configured rules apply to your rows too.

🗄️ Database Sharding & Replica Routing

A separate, more general mechanism from the single-alias read-replica routing above — for a project partitioning data across multiple physical databases, not just steering reads to one replica. Inert unless configured: with SNAPADMIN_SHARDING unset or ENABLED: False, nothing changes — no new DATABASES entry, no extra router, no query overhead.

Two configuration shapes resolve to the same thing. The simple path — a flat list of DSNs the module slices into shards/replicas automatically:

# settings.py
SNAPADMIN_SHARDING = {
    "ENABLED": True,
    "SHARDING_ENABLED": True,    # partition data across shards
    "MIRRORING_ENABLED": True,   # give each shard read replicas
    "REPLICAS_PER_SHARD": 1,     # 1 primary + 1 replica per shard, sliced in order
    "DATABASES": [
        "postgres://user:pass@s1-primary:5432/db",
        "postgres://user:pass@s1-replica:5432/db",
        "postgres://user:pass@s2-primary:5432/db",
        "postgres://user:pass@s2-replica:5432/db",
    ],
}

Or full manual control — an explicit mapping naming exactly which DSN is which shard's primary/replica:

SNAPADMIN_SHARDING = {
    "ENABLED": True,
    "STRATEGY": "range",             # modulo | hash | range | custom
    "SHARDS": {
        "shard_1": {
            "PRIMARY": "postgres://user:pass@s1-primary:5432/db",
            "REPLICAS": ["postgres://user:pass@s1-replica:5432/db"],
            "RANGE": (0, 1000000),   # only read for STRATEGY == "range"
        },
        "shard_2": {
            "PRIMARY": "postgres://user:pass@s2-primary:5432/db",
            "RANGE": (1000001, 2000000),
        },
    },
}

A model opts in with shard_key — the field to shard by, or True for the project-wide default (SNAPADMIN_SHARDING['SHARD_KEY'], default "id") — mirroring how tenant_scoped opts a model into multi-tenancy. No model, including Django's own auth/sessions/ admin tables, is ever routed across shards without explicitly asking:

class Order(SnapModel):
    shard_key = "customer_id"
    ...

from snapadmin.sharding.decorators import snap_master_only, snap_target

with snap_master_only():
    Order.objects.filter(id=order_id).update(status="paid")
    assert Order.objects.get(id=order_id).status == "paid"  # no replication lag

@snap_target(shard="shard_2")
def read_from_shard_2():
    return list(Order.objects.all())

manage.py snap_migrate runs migrations against every shard's primary only — sequentially, or all at once with --parallel — and never touches a replica, since replication already propagates schema at the database layer. manage.py snapadmin_db_backup does the same for backups: with sharding enabled, the "db" bundle part becomes one independently-checksummed "db.<shard_name>" part per shard's primary.

📥 Bulk Import

The write-side counterpart to async export, mirroring its architecture (chunking, progress, resumability) for the opposite direction: reading rows from a CSV or NDJSON file into a model, via manage.py snapadmin_import and a SnapImportJob (see snapadmin.importing for the full contract).

python manage.py snapadmin_import --model demo.Product --file products.csv
python manage.py snapadmin_import --model demo.Product --file p.json --format json
python manage.py snapadmin_import --model demo.Product --file p.csv \
    --map '{"Product Name": "name"}' --natural-key name --on-conflict update
python manage.py snapadmin_import --model demo.Product --file products.csv --resume

• Column mapping is header-name matching by default (case/whitespace/underscore- insensitive, against both the field name and its verbose_name), plus an optional explicit --map that wins wherever a header is named in it. An unmapped column is reported in the run's summary and skipped — never guessed at, never a hard failure.
• The duplicate key (--natural-key) is a field name or a comma-separated list. Left unset it defaults to the model's first unique=True field, or the primary key if the file actually carries a mapped column for it; with neither, every row is a create (there is nothing to detect a duplicate with).
• --on-conflict is fail (the default), skip or update. The default is fail — an import that silently overwrites production rows because nobody passed a flag is the same class of bug this project's write-surface hardening exists to close. A "fail" duplicate is reported as a failed row, never a failed run — one bad or duplicate row must never abort a run processing a million others.
• Validation runs through the model's own field validators — full_clean() on the constructed (or updated) instance, so every Snap*Field's extension/size/format rule applies for free. No parallel validation layer.
• The report is one NDJSON line per row — {"row": N, "action": "created"|"updated"|"skipped"|"failed", "pk": …, "errors": {...}} — plus one {"summary": {...}} line at the end, written through the same storage seam the export API downloads from. Its path is printed when the command finishes.
• Crash-safe, chunk-checkpointed resume (--resume): every row's write, the job's own progress counters and the report's confirmed byte length commit together as one transaction per chunk — a crash loses at most one chunk's progress, and a resumed run can never re-create a row an earlier attempt already committed.
• A write surface from the first line, not a follow-up. A column targeting a field outside api_write_fields, inside api_exclude_fields, or a masked/PII field with no --requested-by user holding PII access, fails the whole run up front, naming the field — never a silent write. A model that is api_read_only (or whose api_http_method_names excludes every write verb) refuses the import entirely.

🧩 Integrating with Your Project

SnapAdmin drops into a real project without bridge code — authentication, the user model and the Elasticsearch client are all pluggable, and imports have a first-class helper.

Pluggable API authentication (JWT / session / custom)

By default the API accepts SnapAdmin's own token auth. Point SNAPADMIN_API_AUTHENTICATION_CLASSES at any DRF authenticators — model CRUD, schema and token endpoints all honour it. With non-token auth, model permissions fall back to plain Django model permissions (a token additionally applies its allowed_models scope):

Every viewset action is mapped to one permission, and an unmapped action is refused. List/retrieve/count/export/fetch_by and OPTIONS need view; create needs add; update needs change; destroy needs delete. An action the map does not know is denied for everyone, superusers included — it used to fall back to view, which would open any new write action to read-only users the moment someone forgot to map it. A project that adds its own action to a subclassed DynamicModelViewSet maps it explicitly; the built-in entries always win, and only view/add/change/delete are accepted (@snap_action actions carry their own permission and need no entry):

SNAPADMIN_API_ACTION_PERMISSIONS = {"recalculate": "change", "preview": "view"}

SNAPADMIN_API_AUTHENTICATION_CLASSES = [
    "rest_framework_simplejwt.authentication.JWTAuthentication",
    "rest_framework.authentication.SessionAuthentication",
    "snapadmin.api.authentication.APITokenAuthentication",   # keep tokens working too
]

JWT in three steps (djangorestframework-simplejwt):

# 1. settings.py — add the authenticator above + the app
INSTALLED_APPS += ["rest_framework_simplejwt"]

# 2. urls.py — obtain / refresh endpoints
from rest_framework_simplejwt.views import TokenObtainPairView, TokenRefreshView
urlpatterns += [
    path("api/token/",         TokenObtainPairView.as_view()),
    path("api/token/refresh/", TokenRefreshView.as_view()),
]

# 3. authenticate, then call any SnapAdmin endpoint with the Bearer token
#   curl -H "Authorization: Bearer $ACCESS" .../api/models/demo/Product/

ELASTICSEARCH_KWARGS = {                 # merged into Elasticsearch(...)
    "api_key": "…", "ca_certs": "/etc/ssl/es.pem",
    "request_timeout": 30, "max_retries": 3, "retry_on_timeout": True,
}
# …or full control (cloud_id, sniffing, custom transport):
SNAPADMIN_ES_CLIENT_FACTORY = "myproject.es.make_client"   # zero-arg callable → client

python manage.py snapadmin_reindex                       # all ES-enabled SnapModels
python manage.py snapadmin_reindex --model demo.Product  # one model
python manage.py snapadmin_reindex --chunk-size 1000     # tune bulk batch size
python manage.py snapadmin_reindex --limit 1000          # probe run — first 1000 rows only
python manage.py snapadmin_reindex --tune                # relax refresh/replicas for the load
python manage.py snapadmin_reindex --no-tune             # force tuning off (overrides the setting)
python manage.py snapadmin_reindex --parallel 4          # fan out with helpers.parallel_bulk
python manage.py snapadmin_reindex --resume              # continue a crashed run from its checkpoint
python manage.py snapadmin_reindex --verify               # count the index against the source afterwards
python manage.py snapadmin_reindex --progress-interval 30 # at most one progress line per 30s

SNAPADMIN_REINDEX_API_ENABLED = True    # the endpoint 404s until you set this
SNAPADMIN_REINDEX_API_ASYNC = False     # True → snapadmin.run_es_reindex Celery task (202 + task_id)

from snapadmin.etl import upsert_from_source

def rows_from_remote():          # any iterable of dicts (e.g. a streamed cursor)
    for r in remote_cursor:
        yield {"code": r.code, "base": "EUR", "rate": r.rate}

summary = upsert_from_source(
    ExchangeRate, rows_from_remote(),
    unique_fields=["code"],      # conflict target (needs a unique constraint)
    batch_size=1000,
)
# {"processed": 5231, "batches": 6, "reindex": {"indexed": 5231}}

from snapadmin.etl import upsert_from_source, stale_sync

seen = {r.code for r in remote_cursor}      # natural keys present in THIS sync
upsert_from_source(ExchangeRate, rows_from_remote(), unique_fields=["code"])
stale_sync(
    ExchangeRate, seen,
    key_field="code",                       # the same unique natural key
    max_fraction=0.1,                       # refuse if >10% would be deleted
)
# {"total": 5231, "stale": 4, "deleted": 4, "fraction": 0.0008, "dry_run": False}

result = stale_sync(ExchangeRate, seen, key_field="code", on_exceed="skip")
if result["aborted"]:
    logger.warning("rates prune skipped: %.0f%% stale", result["fraction"] * 100)

run_started = timezone.now()
# the upsert stamps last_seen = run_started on every reported row …
upsert_from_source(ExchangeRate, rows_with_last_seen(run_started), unique_fields=["code"])
# … then prune everything the sync left behind, entirely DB-side:
stale_sync(
    ExchangeRate,
    strategy="last_seen",
    last_seen_field="last_seen",
    run_started=run_started,
    max_fraction=0.1,
)

🎛️ SNAPADMIN_PROFILE Presets

A new project has roughly 90 SNAPADMIN_* settings to decide before it has a sensible install. SNAPADMIN_PROFILE collapses that to one line by picking sane defaults for the handful of settings that actually differ depending on how you use the package — everything else keeps its built-in default regardless of profile.

# settings.py
SNAPADMIN_PROFILE = "admin"  # "admin" | "api" | "full" (default: unset — no profile applied)

• admin — admin UI only. Turns REST, GraphQL, Swagger and GraphiQL off, for a project that only wants the generated Django admin and nothing else exposed over HTTP.
• api — REST + GraphQL on, admin used minimally. Turns REST, GraphQL and Swagger on explicitly; GraphiQL follows DEBUG. Settings-identical to full today — the two differ as declarations of intent, and as the places future api- or admin-specific settings will attach to.
• full — every generated surface on: REST, GraphQL and Swagger, with GraphiQL following DEBUG.

Precedence: an explicit setting always wins. A profile only fills in a setting nothing else configured — get_setting(name, default) checks, in order: an explicit Django setting, then the active profile's preset, then the built-in default. Leaving SNAPADMIN_PROFILE unset skips the profile step entirely, so every existing install resolves exactly as it did before this feature existed — that is the upgrade guarantee, and it is pinned by a test that walks every setting the package reads.

Since 0.1.0b8, full and "no profile" are no longer the same thing. They used to be: every preset value equalled the built-in default, so full was a documented no-op. Then SNAPADMIN_REST_API_ENABLED and SNAPADMIN_GRAPHQL_ENABLED flipped to False (see the 1.0 migration guide), and a profile that merely mirrored the defaults would have inverted with them — api, whose whole purpose is "REST + GraphQL on", would have turned them off. Each profile now states its values outright, so a profile means what its name says no matter what the defaults do. Leaving SNAPADMIN_PROFILE unset is still exactly the pre-profile behaviour.

A misconfigured profile is caught at manage.py check time rather than failing silently: an unrecognised SNAPADMIN_PROFILE value is snapadmin.E006, and an explicit setting that quietly overrides what the active profile would otherwise set is snapadmin.W009 — both advisory-friendly, since overriding a profile on purpose is a normal, supported thing to do. See Environment Variables Reference for every check id.

🔧 Environment Variables Reference

Every SNAPADMIN_* knob is a plain Django setting — you can set it directly in settings.py. The demo project additionally reads them from an env file: copy demo/dist.env to demo/.env and edit it there.

🧩 Ecosystem Compatibility

How SnapAdmin coexists with popular third-party Django packages. For the Python and Django versions themselves — and for how the whole suite is built and what it does and does not verify — see Testing & Quality Engineering.

SnapAdmin and admin themes (Unfold, Jazzmin, Grappelli)

Those are themes: they restyle the admin you already wrote — you still write the ModelAdmin, the list_display, the search_fields. SnapAdmin generates that admin from your field declarations, and the REST API, the GraphQL schema and the search mapping from the same ones. It is not a competing theme — it sits a layer above, and uses Unfold as its optional theme (the [theme] extra).

If you only want a better-looking admin, use a theme — it is less machinery. SnapAdmin earns its place when the same models must also be an API, a search index and an auditable system of record.

The two rules that make SnapAdmin safe by default

1. SnapAdmin only auto-registers SnapModel subclasses. Every other model in your project — including third-party ones (taggit.Tag, guardian's permission models, reversion.Version, django_celery_beat, …) — is left entirely alone. There is no global admin takeover.
2. Auto-registration never clobbers an existing admin. If a model is already registered (by you or a package) when SnapAdmin runs, it skips it (AlreadyRegistered). Your custom admin wins.

Two escape hatches let a package take over a SnapModel's admin when you want it to:

admin_mixins classes are placed first in the MRO, so their get_queryset / changelist_view / actions wrap SnapAdmin's, which in turn wraps Django/Unfold's ModelAdmin. The methods the generator builds — get_readonly_fields, get_fieldsets, formfield_for_dbfield and the generated display columns — live on a generated base behind the mixins, so a mixin extends them through super():

class AuditFieldsMixin:
    def get_readonly_fields(self, request, obj=None):
        return [*super().get_readonly_fields(request, obj), "reviewed_by"]

class Invoice(SnapModel):
    admin_mixins = [AuditFieldsMixin]

# Precedence, first match wins:
# admin_overrides  >  admin_mixins  >  generated  >  PIIMaskingAdminMixin  >  SnapSaveMixin  >  ModelAdmin

Generated attributes (list_display, ordering, Media, …) are set on the generated class itself — change them with admin_overrides.

Beyond mixins, three more SnapModel attributes tune the generated ModelAdmin without an admin.py: admin_overrides — a dict of attributes/methods merged on last so they win over the defaults (e.g. {"list_per_page": 25}); and css_admin_files / js_admin_files (a static path or list) appended to the generated Media.css / Media.js. These are the supported alternative to hand-writing class Media or your own admin.site.register — SnapAdmin owns registration via register_admin() (one model) and register_all_admins() (a whole app label). The zero-padded id helper snapadmin.models.formatted_id is public for use in overrides. SnapAdmin serves its own admin assets under the snapadmin/ static namespace (snapadmin/js/admin.js, snapadmin/css/admin.css, …); when migrating from the predecessor package, update any hardcoded drofji_autoadmin/… (or bare admin.js) static path to it.

select2 is opt-in, not automatic, on a plain <select>. The shipped admin.js only initialises select2 on an element carrying a snapadmin-select2 class (or a data-snapadmin-select2 attribute) — add that class to a form field's widget attrs to opt it in. This is deliberately narrow: an earlier, broader selector reached the changelist's own action dropdown, and select2 taking over an Alpine-bound <select> (as the Unfold theme renders it) silently broke bulk actions.

Package matrix

Legend: ✅ compatible — no SnapAdmin change needed beyond the documented hook.

Worked example — import/export + versioning on one model

from import_export.admin import ImportExportModelAdmin
from reversion.admin import VersionAdmin
from snapadmin import models as snap_models, fields as snap_fields

class Invoice(snap_models.SnapModel):
    number = snap_fields.SnapCharField(max_length=32, searchable=True, show_in_list=True, show_in_form=True)

    # Compose ecosystem admin behaviour with SnapAdmin's auto-config:
    admin_mixins = [ImportExportModelAdmin, VersionAdmin]

The generated admin is Invoice → ImportExportModelAdmin → VersionAdmin → (SnapAdmin mixins) → ModelAdmin: import/export buttons, version history, and SnapAdmin's field-driven list_display / search / filters / PII masking / audit logging, all at once.

🧪 Testing & Quality Engineering

This page exists so that a team evaluating SnapAdmin can judge the test suite without reading it. Everything below is what the repository does today; the final table is what it deliberately does not do yet, and nothing on this page is claimed before it actually runs in CI.

The method behind the suite — mistake-proofing guards, the four-step bug-fix protocol (regression test, same-class sweep, class guard, escape analysis), mutation testing and the tests that check the tests — is written down in the testing methodology.

Every count here is a floor, read off a real pytest --collect-only -q run rather than maintained by arithmetic. Measured 2026-09-15 on CPython 3.12 / Django 6.0:

The suite ships with the source distribution. The wheel a project installs carries only snapadmin/; the sdist also carries tests/, the demo project it runs against, the docs it checks for truth and pytest.ini. Unpack it and run python -m pytest inside to hold an installed version to the same checks CI runs — without cloning the repository.

Where the tests go. Beyond the contract and docs suites, the heaviest areas are the ones with the most ways to go wrong — each figure a floor, checked against a collection run by tests/test_testing_docs_truth.py: field behaviour and encrypted fields (250+), the REST surface (190+), field-level encryption end to end (400+ across the cipher, the keyset, the blind index, every leak surface and the conversion command), export (130+), backups (170+) and restore (90+ including the pre-restore snapshot), PII masking (120+), settings resolution (90+), API tokens (100+ across issuing, hashing and validation), internationalisation (110+ across the package and the demo), data retention (80+), bulk import (70+), alert channels (70+), the audit trail (60+), multi-tenancy (60+ across the model, admin, audit and Elasticsearch layers) and offline mode (60+). Accessibility (WCAG 2.1 AA) and GraphQL permission enforcement have their own suites. The operator tooling is held to the same bar: the diagnostics report behind snapadmin-info (220+ across eleven files, 80+ of them in the feature-adoption audit, where every capability probe runs switched both on and off), the startup system checks (200+) and the licence audit and its command (60+).

How the tests are written

The rules below are the project's own engineering standard, applied to every change:

• Test-first. A behaviour change or a bug fix starts with a test that fails for the right reason; the production change comes second. Every bug fix ships a regression test pinned to the exact input that broke, and then asks which other inputs hit the same class of bug.
• An assertion states a contract, not a pulse. assert result is not None is treated as a defect in the test. The suite asserts the value, the status code, the exception type and its message, the row that was written, the number of queries. Where a whole set is checkable — the system-check ids a misconfiguration emits, say — it asserts the set (_ids(found) == ["snapadmin.E026"]), never mere containment, because containment stays green when a spurious second error appears.
• Never weaken a check to get a green build. No loosened assertion, no skip, no xfail, no extra mock, no edited expected value, no raised timeout, no # pragma: no cover. When the code and a test disagree, which one is right is answered before either is touched.
• Arrange-Act-Assert, with names a reader understands a year later — expected_status, admin_user, invalid_payload; never obj1, data, result2.
• Ambiguous business logic is a question, not a guess. If the code, the tests and the documentation disagree, or several behaviours are defensible, the rule is to stop and ask rather than pin a guess into a test where it becomes the specification by accident.

The layers, and what each one protects

Not one pyramid but several overlapping ones, because a library fails in more ways than an application does. Every layer below runs on every push; two of them — the live datastore and the browser — need a service or a browser, so a plain local pytest deselects them by marker.

The checks, and how each one actually works

Naming a tool is not documenting it. Each check below is described so that a team could reproduce the same setup in their own project from this page alone.

The 100% line-coverage gate

What runs: pytest --cov=snapadmin --cov-report=term-missing --cov-fail-under=100, in each of the six matrix jobs. What it measures: whether every executable statement in the shipped snapadmin/ package was reached by at least one test — 11,702 statements, 0 missing. demo/ and tests/ are excluded, since coverage of the test suite measures nothing. What fails the build: a pull request that adds a line no test reaches. What a contributor does about it: write the test. Reaching for # pragma: no cover to silence the gate is not an option — a pragma is treated as a hidden gap rather than an exemption. The honest exception: seventeen lines across twelve modules do carry one, each with a written reason, and they fall into three groups — abstract methods whose body is only raise NotImplementedError; if TYPE_CHECKING: blocks that never execute; and the import-time branch taken when an optional dependency is absent (which the suite does cover, by re-importing the module with that dependency hidden, but not in a way the coverage counter can attribute). That list is frozen by tests/test_testing_docs_truth.py, so it cannot grow without a deliberate change and a matching edit here. It used to be eighteen: six guards labelled "defensive, unreachable" were revisited, all six were reachable — one had silently switched PII masking off on a hand-written serializer — and each is now covered by a test instead. What it does not prove: that the line is correct, or that any assertion would notice if it changed. Coverage is a helper metric here, not the goal.

Branch coverage — 100%, gated

What runs: the same command with --cov-branch, in the same CI step as the line gate: pytest --cov=snapadmin --cov-branch --cov-fail-under=100. What it measures: whether each conditional was taken both ways. A if x: … that is only ever entered with x true is 100% line-covered and 50% branch-covered. Where it stands: 100% — 3,464 branches, 0 partial. How it got there: 59 partial branches were closed one by one, each with a test for the case it represented — never with # pragma: no branch. Doing it found real defects, not only missing tests: an ES search result whose delete() deleted nothing for a DUAL model while reporting every row as deleted; an ES_ONLY delete that counted a failed Elasticsearch call as success (which a GDPR erasure then reported as done); a restore that logged an unknown part as applied; two tasks that could return no status at all. Branches that could never be taken were removed rather than tested. What fails the build: a pull request that adds a conditional one of whose sides no test takes.

Random test order, on every single run

What runs: pytest-randomly is a dev dependency and needs no flag — it reshuffles the collected tests on every invocation, locally and in CI, and prints the seed it used. What it catches: order dependence. A test that passes only because an earlier one created a row, left a setting overridden, populated a cache or seeded the random module will eventually run first and fail. What a contributor does about a failure: reproduce it with pytest -p randomly --randomly-seed=<printed seed>, then find the shared state and remove it. Pinning the order with -p no:randomly to make the failure go away is prohibited: a seed-dependent failure is a real defect in the tests, and it is the one class of defect this check exists to surface.

The empty-assertion guard

What runs: tests/test_assertions_can_fail.py, an ordinary test in the suite that parses every other test file with the ast module. What it checks: three shapes of assertion that no outcome could falsify — assert True; assert <anything> or True, where the or makes the left-hand side irrelevant; and a test function containing no assert, no pytest.raises, no mock assert_* call and no assertNumQueries, whose entire claim is therefore "it did not raise". Why it exists: a test that cannot fail is worse than no test. It takes the name of a guarantee, counts toward the total, keeps the line covered and protects nothing — and it is invisible to every other metric here, the coverage gate included. An audit of this suite found four such assertions that had been shipping. What a contributor does about it: assert the behaviour the test is named after. The guard carries a frozen list of pre-existing assertion-free tests which may only ever shrink; adding to it requires a stated reason.

The contract suites

What runs: three files, 349 tests between them, whose only purpose is to fail when the public surface changes shape. tests/test_public_contract.py is the hand-curated half — every import path, signature and default that a downstream project depends on. tests/test_public_surface_snapshot.py is the generated backstop: it walks every top-level snapadmin/*.py module with ast, collects the functions and classes actually defined there, and diffs that against a committed snapshot, so an addition, removal or rename shows up even when nobody remembered to update the hand-curated list. tests/test_api_surface_defaults.py sweeps for a default value spelled inline at a read site instead of going through its single named constant. What a contributor does when one fails: first work out which case it is. If the failure is in the surface this change deliberately alters, update the pin in the same commit, following the deprecation policy when something is being removed. If the failure is in a surface the change never meant to touch, the change just broke a published API — fix the code, not the test. Loosening or deleting the assertion is never the answer.

The compatibility matrix

What runs: six jobs per push — Python 3.10, 3.11, 3.12 and 3.13 × Django 5.2 and 6.0, minus 3.10/3.11 on Django 6.0, which requires 3.12. Why six and not one: anything a test parses or imports can differ between interpreters, and only CI can see it. Two cases have already cost this project a red build after a green local run: tomllib, which is stdlib only from 3.11, and datetime.fromisoformat, which cannot parse a trailing Z before 3.11 — and a trailing Z is exactly how DRF renders timestamps. A green local run proves one interpreter and nothing more. Release gate: the tag-triggered publish workflow calls this same workflow, so a release cannot reach PyPI on a red matrix.

Static analysis — Ruff and mypy

What runs: the static-analysis job — ruff check snapadmin (pyflakes, pycodestyle, bugbear, complexity, and bandit's security rules over the whole package, backups, crypto, encryption, the API and sharding included), ruff format --check snapadmin, and mypy over snapadmin/ with the Django plugin. What fails the build: any Ruff finding, any unformatted file, and any type error — all three are clean and all three are blocking. mypy was advisory while a backlog of 136 findings in the dynamic admin and field layers was worked down; that backlog is gone, so a new type error now fails the job instead of scrolling past in a report nobody reads. The modules where a wrong type costs most — encryption/, crypto.py, sharding/, backup.py, validators.py, logging_config.py and quickstart/ — additionally run under raised strictness: every function annotated and every untyped body checked. How the backlog was cleared, since the shape repeats: most of it came from mixins. A mixin that calls super().handle_exception() or reads self._meta has no base class saying those exist, so every such call was unchecked. Each mixin now declares what it is mixed into in an if TYPE_CHECKING: block — the DRF view or serializer it extends, or the model attributes a SnapModel supplies — which costs nothing at runtime and makes those calls checkable. What is left is a handful of local suppressions, each naming its rule and its reason on the line. What a contributor does about a finding: fix it. A suppression is local, names its rule and says why (# noqa: S603 - argv list, no shell); a bare or blanket one is not accepted. The first pass paid for itself: it found an unescaped primary key rendered as markup in the changelist, a database name interpolated into SQL, and a webhook transport that would have followed file: URLs. Locally: ruff check snapadmin && ruff format --check snapadmin && PYTHONPATH=. mypy.

Property-based and fuzz tests — hypothesis

What runs: every tests/test_properties_*.py and tests/test_fuzz_*.py file, inside the ordinary pytest run — no marker, no separate command. Each test states a law instead of an example: "decrypt(encrypt(x)) is x", "a field rebuilt from its own deconstruct() deconstructs identically", "no text cell of a CSV export opens with a formula trigger", "a query parameter on a masked field changes nothing in the response". hypothesis then generates the inputs — empty values, None, wrong types, astral Unicode, control characters, 10 KB strings, duplicated keys, hostile HTML, backwards key entries — and checks the law against each one. How much it searches: 100 examples per test locally, 300 in CI (--hypothesis-profile=ci; both profiles are defined in tests/conftest.py). No per-example time limit: a wall-clock deadline is a timing check, and a slow CI runner is not a bug. What a failure looks like: hypothesis shrinks the failing input to the smallest one that still fails and prints it, together with a @reproduce_failure(...) line — paste that line onto the test and the exact case replays locally, whatever seed CI used. What a contributor does about one: first decide whether the law or the code is wrong. A law can be too broad ('ß'.upper() is 'SS', so "case-insensitive" was the wrong promise for a function that only calls lower()) — then the law is narrowed, and the comment says why. Otherwise it is a defect: it gets a named regression test in the example suite and a fix, never a filter that steers the generator around it. What the first pass found: a sharding DSN whose password contained a raw /, # or ? leaked that password into the configuration error, and a digits-only one parsed into the wrong host; CSV exports wrote =HYPERLINK(…) cells raw (spreadsheet formula injection); POST /api/exports/ accepted a JSON list as filters and answered 500 to a list of numbers; a masking setting written as a string or a number masked nothing and crashed manage.py check; a provider returning key material as bytes crashed configuration loading; and snap_field() on an auto_now field could make makemigrations crash.

Query-count pins

What runs: tests/test_query_counts.py drives the N+1-prone surfaces — a changelist with foreign keys and a many-to-many, the REST list endpoint, the audit timeline, and the masked changelist, list and timeline — through real HTTP requests and counts their SQL twice, at 3 rows and at 12. What fails: the two counts differing (a query per row, somewhere) or the larger one moving off its pinned number. A new query on a hot path should be a decision; when it is one, the pin changes in the same commit with the reason in its message. The one backend-specific query — PostgreSQL's planner estimate, which an unfiltered changelist asks for before an exact COUNT(*) — is part of the pin on PostgreSQL and absent elsewhere.

Mutation testing — mutmut, advisory

What it asks: the question coverage cannot. 100% line and branch coverage says every statement ran; it says nothing about whether a test would notice the statement being wrong. A mutation tool makes one small, deliberately wrong change to a function — inverts a boolean, turns > into >=, replaces a return value, drops a call — and runs the tests against that mutant. Tests fail → the mutant is killed, and the suite demonstrably detects that class of error. Tests still pass → the mutant survived: the line was covered, but nothing asserted anything that depended on it. A survivor is a gap in the assertions, not in the coverage. What gets mutated: function and method bodies in snapadmin/ (migrations and the scaffold templates excluded). mutmut copies the package into mutants/, rewrites each function into a dispatcher that can select one mutated version at a time, and runs the suite against it — which is why the handful of tests that read the repository's documents or the package's own source text as data (docs truth, the AST surface snapshot, version sync, the sdist manifest) sit out mutation runs: they assert nothing a mutant could change and cannot run against rewritten source. The property-based tests run under a dedicated mutation hypothesis profile — 25 examples, derandomised — so a mutant is killed by a law, never by a newly generated example. The two cadences (.github/workflows/mutation.yml, one command each, both also runnable locally):

• Per push — only what the push changed. python scripts/mutation.py diff --base origin/main reads the changed line numbers out of git diff, maps each to the function that encloses it, and runs only those functions' mutants. A typical commit is a few dozen mutants: minutes, not hours. A change that touches no function body (an import, a constant) runs nothing and says so; a change wider than 40 functions is truncated and left to the weekly run, which the report states.
• Weekly — the dangerous modules, whole. python scripts/mutation.py modules mutates encryption/ (cipher, keys, blind index), crypto.py, sharding/router.py, masking.py, api/filters.py, backup.py, restore.py and tasks.py — everywhere a silent wrong answer means leaked data, a lost backup or a row nobody can find again. This is what covers code nobody is touching.

What it does not do: block. Both jobs are advisory and the script exits 0 either way, because a surviving mutant is not automatically a bug — an equivalent mutant (a changed log string, a guard that cannot be reached) is unkillable by construction, and a 100% mutation score is explicitly not the target. What a contributor does about a survivor: read it with mutmut show <name>, then either strengthen the test until the mutant dies — that is the point of the exercise — or record in writing why that mutation is not worth catching. The report does one round of that triage itself: a survivor whose only change is the wording of a string is counted but not listed, because a test that asserts an error's type, its key and a phrase in it legitimately does not notice a reworded sentence — pinning prose word for word is not a bar this project sets. (It decides that by comparing the mutant's source with the untouched copy beside it, every string literal blanked, so a mutation that changes a string into something else — None, a different expression — still counts as behaviour.) What is left is the list worth reading. Measured on the first real run (the change that introduced these tests): 749 mutants, 547 killed, 202 survived — 123 of them message wording. Of the rest, the recurring shape was a system check's hint= disappearing unnoticed; the hints of the checks that change ship pinned by tests now, and the remaining ones are accepted for the moment rather than pretended away — each would need its own deliberately-broken configuration to reach.

Real PostgreSQL and a live Elasticsearch

What runs: a seventh job, one combination only (Python 3.12 · Django 5.2), with postgres:16 and docker.elastic.co/elasticsearch/elasticsearch:8.13.0 as service containers. It runs the identical suite against PostgreSQL, then pytest -m real_es against the cluster. Why one job and not the whole matrix: a difference between database backends does not depend on the interpreter version, so spreading it over six jobs would cost six times the minutes to learn the same thing. Why it exists: the matrix varies Python and Django but every one of its six jobs runs on in-memory SQLite, so a backend difference cannot fail it — while the package advertises PostgreSQL support and carries backend-specific code. And for Elasticsearch the gap is sharper still: a MagicMock accepts any call with any arguments, so the query DSL these methods exist to build is precisely what a mocked test cannot check. A malformed terms clause or a wrongly-shaped search_after cursor passes the mock and answers 400 Bad Request from a cluster. What it found on its first run: three tests had silently assumed SQLite — one of them pinning behaviour that exists only on the backend without native JSON containment, which meant the PostgreSQL path real users get had no test at all. The live cluster then corrected an assumption no mock would ever have challenged: a boolean field aggregates to the integer keys 1/0, not True/False. Version drift: the image is the same one demo/docker-compose.yml ships, and tests/test_version_sync.py fails if the two ever diverge, or if either leaves the range the [elasticsearch] extra supports.

docker run --rm -d -p 9200:9200 -e discovery.type=single-node \
    -e xpack.security.enabled=false \
    docker.elastic.co/elasticsearch/elasticsearch:8.13.0
SNAPADMIN_TEST_ES_URL=http://localhost:9200 pytest -m real_es

Browser E2E — Playwright, under both admin themes

What runs: a separate job, one combination (Python 3.12 · Django 5.2), with Playwright driving Chromium against the demo/ project, which pytest-django's live server serves over real HTTP. The job runs the suite twice — once on Unfold, once with SNAPADMIN_TEST_ADMIN_THEME=stock on Django's own admin — because SnapAdmin picks the admin classes it builds on at import time, so one process can only ever render one of the two, and the package supports both. A release is gated on this job like on every other. What it walks: signing in (a wrong password refused, ?next= honoured), the index to a changelist, search, a filter, pagination, a row to its change form, a bulk delete behind its confirmation page, an order saved with a select2 autocomplete customer and an inline line item, a model rule refusing a save, view-only and permission-less staff refused (tests/e2e/test_admin_flows.py); a many-to-many and a one-to-one saved from the form, the rich-text editor fitting the window, every select showing its value (tests/e2e/test_admin_forms.py); the dashboard chart drawn with the live counts (tests/e2e/test_dashboard.py); the outage guard — no toast on a healthy load, Save disabled while /api/health/ fails and given back when it answers (tests/e2e/test_connectivity.py); exactly one theme stylesheet per page (tests/e2e/test_themes.py). What every page is also held to, whatever the scenario asserts: an uncaught JavaScript exception, a script, stylesheet, image or icon of the site answered with an error, or any response of the site answered with a 5xx fails the test at teardown. Those are exactly the defects a test-client suite is blind to, and they would otherwise pass every scenario that did not happen to look at the broken widget. How it stays isolated: every test gets a fresh browser and a flushed database, and Playwright starts and stops inside the test. Its synchronous API keeps an event loop marked as running for as long as it is started, and Django refuses ORM calls while one is — so the escape hatch that allows them is switched on for exactly one test, never left behind for the next. Text assertions run under a pinned English locale, UTC and a fixed window size. What it found on its first run — defects every test-client test had passed, each now fixed and also pinned by a fast test in the ordinary run: the dashboard chart had not been drawn since 0.1.0b6 (a two-line {# #} comment rendered as page text containing a literal <script>); the outage guard did nothing at all on Unfold, whose Save buttons sit outside the <form>; the guard announced "Back online" on every healthy page load; a SnapOneToOneField or SnapManyToManyField declared show_in_form=True was missing from the generated form since the first release, while a reverse relation was listed as an autocomplete field; the rich-text editor pushed the page sideways on Unfold and clipped its toolbar on the stock admin; every single-choice select on the stock admin showed no value; and, in the demo, /admin/ answered 500 without Unfold and two configured static files did not exist. Flaky is a diagnosis: no rerun plugin, no sleeps, no raised timeouts. Timing is Playwright's auto-waiting expect; a failed scenario uploads a trace (DOM, network and a screenshot per step) as a job artifact for seven days.

pip install "playwright>=1.45" && playwright install chromium
pytest -m e2e                                    # the Unfold admin
SNAPADMIN_TEST_ADMIN_THEME=stock pytest -m e2e   # Django's stock admin

One command for every gate — scripts/gates.py

What runs: python scripts/gates.py runs, in order, the gates CI runs: suite (the full suite with the 100% line + branch gate and the CI hypothesis profile), static (Ruff lint, Ruff format, mypy), deps (pip check), e2e (the browser suite, once per admin theme) and services (the suite on PostgreSQL, then the live-Elasticsearch tests). security (the security regression suite on its own line), lowest-deps and dist (build the sdist and wheel, twine check --strict) run by name or under --release. What it never does: report a gate it could not run as passed. Playwright missing, no SNAPADMIN_TEST_POSTGRES/SNAPADMIN_TEST_ES_URL, no pg_dump/psql (the PostgreSQL run executes a real backup round trip), no uv — the gate is listed as not run with what it needs. An ordinary run still exits 0 then, so a contributor without a browser can check everything else; a gate asked for by name fails (CI's lowest-deps job asks by name, so a missing uv there is red, not green), and --release is the release gate and fails on any. The six-job Python × Django matrix is the one thing no single machine reproduces, and the summary says so. How it stays equal to CI: each command is spelled exactly as .github/workflows/test.yml spells it, and tests/test_gates_script.py reads the workflow: a CI step that is neither runner setup nor a gate's command fails the suite, and so does a gate whose command its CI job stopped running. The service variables reach the services gate only — CI gives the databases to that one job, so exporting them for it never moves the suite or the browser run onto PostgreSQL. python scripts/gates.py --list prints every gate's commands and job.

The security regression suite

What runs: pytest -m security_regression — the tests tests/security_regressions.py names for each security fix the package has shipped, 30+ of them since 0.1.0b1: the dashboard's staff gate, rich-text sanitizing, the dynamic API's model allowlist, GraphQL relation permissions, the mass-assignment guard, masking on every surface, the SSO open redirect, export-filter traversal, the SFTP host key, the encryption leak surfaces, the audit trail's labels, CSV formula injection, DSN password redaction and the rest. tests/conftest.py applies the marker from the registry, so nobody decorates a test by hand. What fails the build: an entry in any release note's Security section with no registry entry (the notes are read as data, so a new note is checked without anyone remembering a list); a named test that no longer exists or carries skip, skipif or xfail; a registry smaller than its recorded floor. What a contributor does: a security fix gets its regression test, its note under Security and a registry entry naming the test, in the same change.

Dependency compatibility — the declared minimums, run

The gap it closes: every other job installs demo/requirements.txt, whose >= specifiers resolve to the newest release of everything — so the lower bounds pyproject.toml publishes were never run by anything, while an adopter pinning one of them runs exactly that. What runs: the lowest-deps job (Python 3.10, the lowest supported) executes python scripts/gates.py lowest-deps: a fresh environment, every declared dependency resolved to its lowest allowed version with uv pip install --resolution lowest-direct, pip check, then the suite. A declared minimum that cannot be installed with the rest is a failure naming the version that did install — the bound was a promise nobody could keep, and the fix is to raise it. Also checked on every run (tests/test_dependency_compat.py): the Python and Django classifiers are exactly the CI matrix, and the lowest of each is the declared lower bound; every declared dependency is installed by CI at the declared range (one written exception, boto3, whose client the S3 tests stub); pip check runs in the static-analysis job; makemigrations --check runs as a test in every job, so a model change without its migration fails CI.

Documentation-truth tests

What runs: 145 tests across four files that read the documentation as data. tests/test_docs_completeness.py asserts that every SNAPADMIN_* setting the code reads appears both in the documentation and in the demo project, that every registered system-check id is explained somewhere, and that every optional extra is listed consistently across the README, this page, THIRD_PARTY_NOTICES.md and the licence inventory. tests/test_ai_entry_points.py pins the two machine-readable layers: every module named in the in-package module map really imports, every docs anchor llms.txt links to really resolves, and the two copies of llms.txt are byte-identical. tests/test_docs_site.py checks this page's own structure — one sidebar link per section, no link to a section that does not exist. tests/test_version_sync.py pins the version literal across every place the repository publishes it. Why: documentation rot is silent. Nothing breaks at import time when a section disappears or a setting is never written down; it just teaches the next reader something false.

The end-to-end tripwire

What runs: tests/test_critical_path_smoke.py, three tests. What it does: posts the real generated admin add form over HTTP, then asserts that the row which comes out is the same one the REST API serves and the same one the audit trail recorded, with the acting user and a per-field diff. Why a separate test when every layer already has a deep suite: because each of those suites can keep passing while the seam between the layers quietly breaks. It is deliberately small — a tripwire for "the pipeline stopped connecting", not a second copy of the deep suites.

What is not in place yet

A quality page that lists only what exists is marketing. These are the layers the project's own engineering standard asks for and that this repository does not have today. They are described here as they will be built, so that the description is not mistaken for the check:

🩺 Diagnostics — snapadmin_info

One command reports SnapAdmin's whole configuration and the health of everything it connects to — useful when deploying, debugging a staging box, or feeding a monitoring dashboard. It reads configuration and probes services only; it changes nothing, and secrets (database passwords, broker credentials, token values) are never printed.

snapadmin-info                   # full text report
snapadmin-info --json            # machine-readable (monitoring / CI)
snapadmin-info --section version # one section (repeatable)
snapadmin-info --brief           # top-level values only
snapadmin-info --health-check    # probes only; non-zero exit on failure
snapadmin-info --startup         # the short block runserver prints at startup

Flags