🚀 SnapAdmin

Write your data model once. Get the admin panel, the REST API, the GraphQL endpoint and the search index — automatically.

📚 Documentation · 📦 Django Packages · 📝 Changelog · 🔒 Security · 🧭 llms.txt

Try it — 60 seconds, no setup

pip install "django-snapadmin[api,graphql]"
snapadmin-new myshop
cd myshop
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 GraphQL (/api/graphql/) are already running against a working example model — SQLite, no Docker, nothing to edit by hand. Only want to look around? snapadmin-demo downloads a fully-loaded demo (search, audit trail, background jobs); log in with admin / admin.

Quickstart

There are two ways in, and they end in the same place. Neither adds a database migration of its own.

A new project or an MVP — SnapModel in 3 steps

The declarative route: your fields say how they behave, and every surface is generated from them.

1. Declare the model.

# models.py
from snapadmin import fields as snap, models as snap_models

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

    api_write_fields = ["name", "price", "available"]   # what an API client may set
    subject_path = None   # no personal data here — snapadmin.E011 asks every model

2. Turn on the surfaces you want.

# settings.py
SNAPADMIN_REST_API_ENABLED = True    # off by default — you opt in
SNAPADMIN_GRAPHQL_ENABLED  = True    # same
SNAPADMIN_SWAGGER_ENABLED  = True

3. Register every model — one line.

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

That is the whole setup. You now have:

snapadmin-new already wired INSTALLED_APPS and urls.py for you. By hand, it is the minimal install plus the four API apps; subject_path is the GDPR subject-access declaration every model answers (what to put there).

An existing project you cannot rewrite — @snap_model

A brownfield schema, a base class from a third-party package, fields from django-money or phonenumber_field: opt the model in from the outside. No inheritance change, and — because the decorator adds no field and no attribute — no migration.

1. Install, and let snapadmin-init tell you what is missing. It reads your project and prints the exact snippets to paste; it never edits a file.

pip install "django-snapadmin[api]"
snapadmin-init --api

2. Add the apps and the routes it names.

# settings.py
INSTALLED_APPS += ["rest_framework", "drf_spectacular", "django_filters", "snapadmin"]
SNAPADMIN_REST_API_ENABLED = True

# urls.py  (from django.urls import include, path)
urlpatterns += [path("api/", include("snapadmin.urls"))]

3. Decorate the model.

from django.db import models
from snapadmin import snap_model

@snap_model(
    api_write_fields=["name", "price"],   # what an API client may set
    api_exclude_fields=["cost_price"],    # never leaves the server
    search_fields=["name"],               # what ?search= matches on
    subject_path=None,                    # no personal data here — snapadmin.E011 asks every model
)
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)

You get the REST API (/api/models/<app_label>/Product/, documented at /api/docs/), GraphQL with the [graphql] extra, the offline endpoints, the system checks and the snapadmin-info inventory. You keep your own ModelAdmin — the parts that need SnapModel's machinery (Elasticsearch mirroring, the retention purge, the generated admin) skip a decorated model rather than half-work — so the decorator reads search_fields from its own keyword, not from field flags. When you later move a model onto SnapModel, snap_field() gives a field you already have (a django-money or phonenumber_field column) the Snap flags without changing its class, and bare, wrapped and Snap*Field fields mix freely in one class body. Which capability lives where, side by side · snap_field() · mixing fields.

The cheat sheet — the kwargs you'll actually use

None of these touch the database except required, so you can change your mind without a migration.

On the model itself:

30+ field types (SnapPhoneField, SnapColorField, SnapStatusBadgeField, …) and the layout kwargs (tab, row, autocomplete, wysiwyg, upload validation) are in the field reference.

The commands

snapadmin-info ≡ python manage.py snapadmin_info, and both inspect a live project. You also see the short version without asking: under DEBUG, runserver prints one block to stderr saying which capabilities are on, which are off, which lack their extra, and whether your dependencies allow commercial use — configuration only, never a query or a secret. SNAPADMIN_STARTUP_REPORT = False silences it (startup report).

⏱ Nothing runs on a schedule by itself. Backups, digests and the data purge are management commands (snapadmin_db_backup, snapadmin_purge_expired_data, snapadmin_send_error_digest, …) that need a Celery Beat entry or a cron line. → Background tasks & scheduling

Is your integration actually correct?

snapadmin-init prints this checklist itself, with a ✅/❌/⚠️ per row (⚠️ = needs a running project to check, never a false green):

→ Full checklist · Production playbook — the decisions to settle before the first migration, the build order, what your own test suite should cover, and which defaults stop being right under load.

Why this exists

Every internal tool needs the same four things: a screen where staff manage the data, an API for the mobile app, an API for the frontend team, and a search box. Today each one is written and maintained separately — four descriptions of the same data, four places to update when a field changes, four chances to leak a field you meant to keep private. SnapAdmin generates all four from one.

The admin screen your ops team asks for on Friday is a keyword argument, not a sprint. A new field reaches the API, the search index and the audit log the moment it reaches the model, and the fields you don't want exposed are excluded once, in the model, rather than in every surface.

What it is not. Not a theme, not a framework, not a lock-in. Underneath it is ordinary Django — models, ModelAdmin, DRF viewsets — so you can override any generated piece, or stop using it, without rewriting your data layer. Your hand-written ModelAdmin classes are never replaced, and manage.py check tells you when one of them shows masked fields unmasked (snapadmin.W025). Unfold, Jazzmin and Grappelli restyle an admin you still write; SnapAdmin generates it — and uses Unfold as its optional theme. If a better-looking admin is all you need, a theme is less machinery (the comparison).

What you get

🖥 Admin panel — list columns, search and filters derived from your fields · themed responsive UI · status badges, tabs, inlines, autocomplete · field-level change history · an offline mode that keeps a list usable with no connection

🔌 APIs — REST CRUD with Swagger and auto-derived filters (an unknown query parameter is a 400, never silently ignored) · GraphQL with permissions on every traversed relation · API tokens hashed at rest · per-field read/write guards · @snap_action exposes approve / refund / recalculate as a permission-checked endpoint · a rejected write answers 400 naming the field, and api_full_clean runs your Model.clean() for API clients too

🔍 Search (optional) — Elasticsearch with the mapping derived from your fields · ?search= routed to ES automatically, falling back to the database when ES is down · resumable bulk reindex · deletes keep the index in step, cascades included

⚙️ Operations — audit trail · GDPR retention · PII masking · backups (with daily/weekly/monthly retention) · alerts to email, Slack, Discord, Teams or Telegram · structured logging · 10 languages

🔐 Encrypted model fields — SnapEncrypted*Field (eight types, behind the [encryption] extra) stores AES-256-GCM ciphertext in the column and hands your code the ordinary value; keys come from a KMS/Vault provider, a mounted secret, the environment or settings — never SECRET_KEY — and rotate by prepending one. The cost is stated up front: the database cannot compare, order or index what it cannot read, so icontains, gt and ORDER BY raise a FieldError naming the field rather than returning nothing, and blind_index=True buys back __exact / __in / unique at the documented price that equality becomes observable. Field encryption

🗄 Sharding and replica routing — SNAPADMIN_SHARDING replaces hand-rolled DATABASES / DATABASE_ROUTERS with one settings dict: a flat list of DSNs or named shards, modulo / hash / range / custom strategies, opt-in per model with shard_key, failover in HA_SETTINGS, and snap_migrate / snapadmin_db_backup that only ever touch primaries. Completely inert until ENABLED: True. Database sharding

🧭 Operability — misconfiguration surfaces at startup as a Django system check (snapadmin.E0xx / W0xx), not as a mystery at request time · snapadmin-info reports what is switched on, what is in use and what is unreachable · snapadmin-license-check answers the legal question in one command

Proof it holds up

Adoption risk is the real question, so every answer below is something you can verify yourself.

For teams and enterprise

Quality & compatibility

This is a package other people's products depend on, so the test suite is treated as part of the product. Every count is a floor, read off a real pytest --collect-only -q run rather than kept current by arithmetic. The full account — every layer, how each check works, where the tests go — is Testing & Quality Engineering.

• 5,000+ tests across 153 files, in random order on every run. Twelve need a live Elasticsearch and are deselected by default, so cloning the repository and typing pytest starts no container and takes about forty seconds.
• 100% line and branch coverage of the shipped snapadmin/ package, gated in CI (pytest --cov=snapadmin --cov-branch --cov-fail-under=100) — never closed with # pragma: no branch. Seventeen lines across twelve modules carry a # pragma: no cover, each with a written reason (abstract methods, if TYPE_CHECKING: blocks, optional-import branches); that list is pinned by a test so it cannot quietly grow.
• Every push runs, in CI: the six-way Python × Django matrix; the whole suite on PostgreSQL 16 plus the live Elasticsearch 8.13.0 tests; Ruff + mypy, clean and blocking; the generated admin driven in a real browser under both admin themes; and lowest-deps, which installs every dependency at its declared minimum. A release is gated on the same jobs.
• Property-based and fuzz tests (hypothesis, 100 examples per test locally, 300 in CI) state laws that must hold for every generated input — deconstruct() round-trips, the encryption envelope, masking rules — and throw hostile input at the request-facing surfaces.
• Mutation testing (mutmut, scripts/mutation.py) proves the tests can detect a wrong change, not merely run the line — per push over the functions the push changed, weekly over the modules where a wrong answer costs most. Advisory: it reports, never blocks.
• Every security fix ever shipped keeps a named test (30+, pytest -m security_regression), and a new security note without one fails the build.
• Ten translation catalogs, linted mechanically (placeholders, plurals, markup, a .mo matching its .po) by tests/test_translation_lint.py. Only en and ru are native-reviewed; the other eight await a native speaker.

How the tests are written. Test-first, with a regression test pinned to the exact input for every bug fix. Assertions state a contract — the value, the status code, the query count — and a guard (tests/test_assertions_can_fail.py) fails on an assertion no outcome could falsify. No test is ever weakened, skipped or mocked into silence to get green. No test assumes a backend: where SQLite and PostgreSQL genuinely differ, both halves are written.

The public surface and the docs are tests too.

Run every gate yourself — the same checks CI runs, one command:

python scripts/gates.py            # everything this machine can run; a gate it cannot is "not run", never "passed"
python scripts/gates.py --release  # every gate must run, and pass
pytest -m e2e                                    # the browser suite, Unfold admin
SNAPADMIN_TEST_ADMIN_THEME=stock pytest -m e2e   # the browser suite, Django's stock admin

The browser scenarios live in tests/e2e/test_admin_flows.py, tests/e2e/test_admin_forms.py and tests/e2e/test_connectivity.py; every page also fails on an uncaught JavaScript error, a missing asset or a 5xx. Their first run found defects no test-client test could see — a chart not drawn, relation fields missing from forms — each now pinned by a fast test as well.

What is not in place yet

A quality section that only lists what exists is marketing. None of these is claimed above:

Install and configure

pip install django-snapadmin

Requires Python ≥ 3.10 and Django ≥ 5.2; pin an exact version in production. A bare install brings Django, structlog and nh3 — enough for the generated admin, because the REST API and GraphQL are off by default. Everything else is an extra, and the base install carries only permissive licences:

api · graphql · theme (Unfold) · elasticsearch (8.x) · celery · backup (SFTP) · s3 · age (encrypted backups) · encryption (encrypted fields) · xlsx · extra-settings · autocomplete-filter (LGPL) · wysiwyg (bundles CKEditor 5, GPL-or-commercial) · all

snapadmin-license-check tells you what you ended up with. → Installation — the minimal and the full INSTALLED_APPS, what each extra pulls in, and the MySQL driver licence note.

Every surface is a plain Django setting, and switching one off removes its routes entirely:

SNAPADMIN_REST_API_ENABLED       = True    # REST CRUD endpoints — off by default
SNAPADMIN_GRAPHQL_ENABLED        = True    # GraphQL endpoint — off by default
SNAPADMIN_SWAGGER_ENABLED        = True    # Swagger UI + ReDoc
SNAPADMIN_URL_PREFIX             = ""      # relocate the whole API surface
SNAPADMIN_CONNECTIVITY_ENABLED   = False   # admin-wide health poll + offline save-guard (opt-in)

Don't want to decide all ~110 of them? SNAPADMIN_PROFILE = "admin" (or "api" / "full") sets the handful that matter; an explicit setting always wins. Snap fields accept Django's positional label (SnapCharField("Label", max_length=200)), so existing declarations switch over unchanged, and snapadmin.E027 stops SnapModel from silently replacing an objects manager your mixins provide.

→ Every setting · Profiles · Extending & overriding — your own field types, endpoints, auth and templates, without forking · The full demo from a clone — Docker with PostgreSQL, Redis and Elasticsearch

Documentation

Working with an AI assistant? Two entry points ship for exactly that, both pinned by tests: the module map in the snapadmin package docstring (help(snapadmin) — no network needed) and llms.txt.

Security

API tokens are hashed at rest, rich-text HTML is sanitized on write, GraphQL enforces permissions on every traversed relation, and PII masking covers both APIs. Report vulnerabilities privately — see SECURITY.md for the policy, the supported-versions row and the production-hardening checklist.

Contributing

See CONTRIBUTING.md. The suite lives at tests/ and must stay green with 100% line and branch coverage on snapadmin/; pytest runs it. The sdist carries the suite too, so an installed version can be held to the same checks without cloning. Regression tests live next to the subsystem they cover (tests/test_fields.py, tests/test_pii_masking.py, …) — check there before filing a bug that might already be covered. How the suite is designed — the mistake-proofing guards, the four-step bug-fix protocol, mutation testing and the tests that check the tests — is the testing methodology.

License

MIT — see LICENSE.