django-powercrud 0.5.2

Advanced CRUD for perfectionists with deadlines. An opinionated Neapolitan extension, with sprinkles.

Django PowerCRUD

Advanced CRUD for perfectionists with deadlines. An opinionated Django package for shipping production-grade CRUD screens with filtering, bulk operations, inline editing, and async workflows.

PowerCRUD extends Neapolitan’s view layer with the practical infrastructure needed for real operational interfaces.

Why PowerCRUD

• Production-ready CRUD – faster
  HTMX responses, modal forms, inline row editing, and filter sidebars are configured through class attributes rather than custom templates.

• Bulk operations that scale
  Start synchronously with selection persistence and validation controls, then opt into async queueing with conflict locks, progress polling, and an optional dashboard when jobs run longer.

• One async toolkit everywhere
  The async manager, conflict handling, and progress API are reusable from admin actions, management commands, or bespoke launch sites so background work behaves consistently.

• Batteries included
  Sample app, Docker dev stack, management commands, Tailwind safelist tooling, and a maintained pytest/Playwright suite keep the project teachable and testable.

ℹ️ Status

PowerCRUD is still evolving, but now ships with a comprehensive pytest suite (including Playwright UI smoke tests). Expect rough edges while APIs settle, and pin the package if you rely on current behaviour.

See the full documentation.

Key Features

• HTMX-enabled CRUD views with modal create/edit/delete flows.
• Inline row editing with dependency-aware widgets, lock checks, and permission guards.
• Bulk edit/delete with selection persistence and an optional async path.
• Async infrastructure: conflict locks, progress cache, django-q2 workers, cleanup command, optional dashboard persistence.
• Filtering, sorting, and pagination helpers backed by tuned templates.
• Styling controls (daisyUI/Tailwind) plus template scaffolding and Tailwind safelist extraction.
• Extension hooks for custom actions, buttons, and templates, illustrated in the bundled sample app.
• Tooling support: Dockerised dev environment, management commands, pytest + Playwright coverage.

Quick Examples

Core CRUD (synchronous)

from neapolitan.views import CRUDView
from powercrud.mixins import PowerCRUDMixin


class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    model = Project
    base_template_path = "core/base.html"

    # Core configuration
    fields = ["name", "owner", "status", "created_date"]
    properties = ["is_overdue"]
    filterset_fields = ["owner", "status", "created_date"]
    paginate_by = 25

    # UX helpers
    use_htmx = True
    use_modal = True
    inline_edit_enabled = True
    inline_edit_fields = ["status", "owner"]

    # Bulk operations (synchronous)
    bulk_fields = ["status", "owner"]
    bulk_delete = True

This single view serves a filtered list, modal forms, inline edits, and synchronous bulk edits - no async stack required.

Async bulk (opt-in)

from neapolitan.views import CRUDView
from powercrud.mixins import PowerCRUDAsyncMixin


class ProjectAsyncCRUDView(PowerCRUDAsyncMixin, CRUDView):
    model = Project
    base_template_path = "core/base.html"

    bulk_fields = ["status", "owner"]
    bulk_delete = True
    bulk_async = True
    bulk_min_async_records = 20
    bulk_async_conflict_checking = True

    # Optional async dashboard manager
    async_manager_class_path = "myapp.async_manager.AppAsyncManager"

Here async queueing is explicit: you opt in by using PowerCRUDAsyncMixin, enabling bulk_async, and configuring django-q2 (django_q in INSTALLED_APPS, Q_CLUSTER, and any POWERCRUD_SETTINGS overrides you need).

Getting Started

• Install django-powercrud and neapolitan, add powercrud, neapolitan, and django_htmx, then follow the Getting Started guide for base template requirements.
• Continue with Setup & Core CRUD basics to enable filters, pagination, and modals.
• Add Inline editing and Bulk editing (synchronous), then move to Async Manager and Bulk editing (async) when you need background work.
• Use Styling & Tailwind and Customisation tips to adapt templates.

Tooling & References

• Sample app – complete walkthrough of every feature.
• Docker dev environment – Django, Postgres, Redis, Vite, django-q2.
• Management commands – template scaffolding, Tailwind safelist extraction, async cleanup.
• Testing – pytest matrix plus Playwright smoke tests.

Supported Versions

PowerCRUD is tested against the following combinations:

• Python 3.12 with Django 4.2 LTS and Django 5.2
• Python 3.13 with Django 4.2 LTS and Django 5.2
• Python 3.14 with Django 4.2 LTS and Django 5.2

We aim to keep the dependency lock compatible with each pairing; upcoming CI work will exercise this matrix automatically on pushes to main.

Development Setup

PowerCRUD’s development environment is Docker-first. From the project root:

./runproj up          # build images, start services, enter the Django container
./runtests                # run the full test suite, including Playwright smoke tests

Dependencies are managed with uv; the Docker image installs them into the system interpreter so you never need to activate a virtual environment inside the container. See the Dockerised Development Environment guide for full details.