karni

Batteries-included Django glue: one call assembles the settings every Django + DRF + Celery project repeats, with production-safe defaults, startup validation, and an escape hatch for every single value. On top of the settings core it ships the three batteries every project rewrites:

• karni.accounts — email-based swappable user, JWT or session auth endpoints, verified-email / password-reset / email-change flows, roles, optional TOTP 2FA and social login (docs)
• karni.api — class EventViewSet(BaseViewSet): model = Event gives CRUD + filtering + search + expansion + OpenAPI, auto-routed (docs)
• karni.admin — zero-config django-unfold admin: every model registered with derived columns, filters, search and soft-delete handling (docs)

pip install karni            # core
pip install 'karni[s3]'      # + S3-compatible storage (django-storages, boto3)
pip install 'karni[images]'  # + thumbnailing (Pillow)
pip install 'karni[sentry]'  # + Sentry (sentry-sdk)
pip install 'karni[social]'  # + social login (django-allauth)
pip install 'karni[2fa]'     # + TOTP two-factor auth (django-otp)

A whole settings.py

from karni.conf import karni_settings

karni_settings(globals())

# Project-specific settings below — anything defined here wins.
INSTALLED_APPS += [
    # "myapp",
]

That call configures: INSTALLED_APPS, middleware, Postgres from DATABASE_URL, Redis cache, DRF (pagination, filter backends, throttling, drf-spectacular schema), Celery (+ django-celery-beat, django-celery-results), file storage (local or S3-compatible), structlog logging (console in dev, JSON in prod), security headers, CORS, and optional Sentry. At startup the merged settings are validated by a Pydantic model and every bad value is reported at once (KARNI_VALIDATE = False skips this).

Overriding defaults

karni_settings() uses setdefault semantics — it never overwrites a name you already defined. Three layers, strongest first:

1. Assign after the call — always wins: REST_FRAMEWORK["PAGE_SIZE"] = 20
2. Define before the call — never touched. For INSTALLED_APPS and MIDDLEWARE, Karni appends its missing entries after yours instead of replacing the list.
3. Keyword overrides — karni_settings(globals(), CELERY_TASK_TIME_LIMIT=60) replaces the Karni default (whole-value replacement) but still yields to names defined in the module.

Most defaults also read environment variables (via django-environ), so the same image runs in dev and prod with only a .env change.

Profiles

DJANGO_ENV=dev (default) or DJANGO_ENV=prod — or force one with karni_settings(globals(), env_name="prod").

Environment variables

Celery

# config/celery.py
from karni.celery import create_celery_app

app = create_celery_app()

Broker, django-db results, database beat scheduler and task autodiscovery are configured from the CELERY_* settings that karni_settings() provided. Periodic tasks declared with karni.schedule.every() / cron() in <app>/schedules.py are merged into the beat schedule (docs/scheduling.md). Model lifecycle listeners live in <app>/listeners.py (docs/events.md). manage.py karni_routes and manage.py karni_schedules list every URL and every schedule (--json for agents).

Health checks

# config/urls.py
path("health/", include("karni.health.urls")),

/health/ is a no-I/O liveness probe; /health/ready/ runs the checks in KARNI_HEALTH_CHECKS (Postgres, Redis, Celery by default — a list of dotted paths you can extend or replace) and returns 200 or 503 with per-check detail.

Storage & thumbnails

KARNI_STORAGE=s3 switches the default storage to karni.storage.S3Storage (S3-compatible, endpoint-aware); anything else uses local FileSystemStorage. karni.storage.thumbnails.make_thumbnail() produces aspect-preserving thumbnails; swap the implementation via the KARNI_THUMBNAILER dotted-path setting.

Development

cd packages/karni
pip install -e . --group dev
pytest
ruff check .