Django Utils

Django Utils is a collection of the small Django helpers, admin power-ups and ORM utilities that most projects end up writing themselves: JSON-aware admin filters, encrypted model fields, memory-bounded queryset iteration, resumable management commands, and more. It builds on the Python Utils library. It is by no means a complete collection, but it has served production projects well and keeps growing.

Full documentation, including a "why this over the alternatives" page, is at https://django-utils-2.readthedocs.io/en/latest/.

Requirements

• Python 3.10+
• Django 4.2, 5.2, or 6.0

Install

1. Run pip install django-utils2
2. Add django_utils to your INSTALLED_APPS

If you want to run the tests, install the tests extra (pip install "django-utils2[tests]") and run pytest.

Quickstart

Filter an admin changelist on a nested JSONField value without writing a custom SimpleListFilter:

from django.contrib import admin
from django_utils.admin.filters import JSONFieldFilterDropdown

from myapp.models import Sandwich


class SandwichAdmin(admin.ModelAdmin):
    list_filter = (
        JSONFieldFilterDropdown.create('data__filling'),
    )


admin.site.register(Sandwich, SandwichAdmin)

A sidebar filter on data['filling'], no JOIN or denormalized column. The quickstart page has two more features like this.

Features

Every feature below has its own page on the docs site, with runnable examples, edge cases, and (for the admin features) screenshots or a live in-browser demo.

• Admin dropdown / Select2 / JSON filters: dropdown, autocomplete, and JSON sub-path list filters for the changelist sidebar, plus an operator selector (gte, lte, icontains, ...) for typed comparisons. See Select / dropdown / autocomplete filters and Operator filters.
• JSON widget: a drop-in JSONField admin widget that pretty-prints and validates JSON as you type. See JSON widget.
• Read-only admin: turn any ModelAdmin into a read-only view: add/change/delete denied for everyone, filtering and search still work. See Read-only admin.
• Count columns: sortable related-object count columns for list_display, without the N+1 or JOIN fan-out footguns. See Count columns.
• Admin export: streaming CSV/JSON export actions for the changelist, memory-bounded via queryset_iterator. See Export.
• Choices: metadata-carrying choices with dict-like access and a real enum.Enum on demand via as_enum(). See Choices.
• PostgreSQL ENUM field: a CharField backed by a native PostgreSQL ENUM type on Postgres, plain VARCHAR everywhere else, with hand-written migration operations for creating the type and adding values. See PostgreSQL ENUM field.
• Request/user context (ASGI-safe): access the current request/user from anywhere via contextvars, isolated per asyncio task, unlike thread-local equivalents. See Current request / user (ASGI-safe).
• Query budgets: catch N+1 regressions in production code paths, not just in tests, with a query-counting context manager/decorator. See Query budgets.
• Auth helpers: superuser_required/staff_required decorators and a permission_string() builder for has_perm() checks. See Auth helpers.
• Fetch-Metadata CSRF middleware: defense-in-depth CSRF hardening using the Sec-Fetch-Site header, run alongside (not instead of) Django's own CSRF middleware. See Fetch-Metadata CSRF middleware.
• Subquery aggregates: SubqueryCount/SubquerySum/SubqueryAvg/... annotate each aggregate in its own subquery, avoiding the JOIN fan-out that multiplies counts. See Subquery aggregates.
• Bulk upsert: bulk_update_or_create(): one INSERT ... ON CONFLICT DO UPDATE batch instead of a racy, two-query-per-row loop. See Bulk upsert.
• Chunked management commands: ChunkedCommand: memory-bounded, resumable processing of large querysets with progress logging and a transactional dry-run. See ChunkedCommand.
• Encrypted model fields: EncryptedCharField/EncryptedTextField/ EncryptedJSONField: Fernet-encrypted values in a plain TEXT column, with key-rotation support. See Encrypted model fields.

Links

• Documentation: https://django-utils-2.readthedocs.io/en/latest/
• Source: https://github.com/WoLpH/django-utils
• Bug reports: https://github.com/WoLpH/django-utils/issues
• Package homepage: https://pypi.org/project/django-utils2/
• My blog: http://w.wol.ph/