Metadata-Version: 2.4
Name: django-powercrud
Version: 0.5.43
Summary: Advanced CRUD for perfectionists with deadlines. An opinionated Neapolitan extension, with sprinkles.
Author: doctor-cornelius
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: django-htmx<2.0,>=1.27.0
Requires-Dist: django-template-partials>=25.3
Requires-Dist: pydantic<3.0,>=2.12.5
Provides-Extra: dev
Requires-Dist: commitizen<5,>=4.13.8; extra == 'dev'
Requires-Dist: ipykernel<8,>=7.2.0; extra == 'dev'
Requires-Dist: ruff>=0.15.2; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-awesome-nav<4,>=3.3.0; extra == 'docs'
Requires-Dist: mkdocs-enumerate-headings-plugin<0.8,>=0.7; extra == 'docs'
Requires-Dist: mkdocs-material<10,>=9.7.3; extra == 'docs'
Requires-Dist: mkdocs-mermaid2-plugin<2,>=1.2.3; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6.1; extra == 'docs'
Provides-Extra: tests-core
Requires-Dist: coverage<8,>=7.13.4; extra == 'tests-core'
Requires-Dist: crispy-tailwind<2,>=1.0.3; extra == 'tests-core'
Requires-Dist: django-crispy-forms<3,>=2.5; extra == 'tests-core'
Requires-Dist: django-q2<2,>=1.9.0; extra == 'tests-core'
Requires-Dist: django-redis<7,>=6.0.0; extra == 'tests-core'
Requires-Dist: django-vite<4,>=3.1.0; extra == 'tests-core'
Requires-Dist: django<6,>=4.2.25; extra == 'tests-core'
Requires-Dist: faker<41,>=40.11; extra == 'tests-core'
Requires-Dist: neapolitan<27,>=26.1; extra == 'tests-core'
Requires-Dist: psycopg-binary<4,>=3.3.3; extra == 'tests-core'
Requires-Dist: psycopg<4,>=3.3.3; extra == 'tests-core'
Requires-Dist: pytest-cov<8,>=7.0.0; extra == 'tests-core'
Requires-Dist: pytest-django<5,>=4.12.0; extra == 'tests-core'
Requires-Dist: pytest-mock<4,>=3.15.1; extra == 'tests-core'
Requires-Dist: pytest<9,>=8.4.2; extra == 'tests-core'
Requires-Dist: validators<1,>=0.35.0; extra == 'tests-core'
Provides-Extra: tests-ui
Requires-Dist: playwright<2,>=1.58.0; extra == 'tests-ui'
Requires-Dist: pytest-playwright<1,>=0.7.2; extra == 'tests-ui'
Description-Content-Type: text/markdown

# Django PowerCRUD

[![Run Test Matrix](https://github.com/doctor-cornelius/django-powercrud/actions/workflows/pr_tests.yml/badge.svg)](https://github.com/doctor-cornelius/django-powercrud/actions/workflows/pr_tests.yml)
[![codecov](https://codecov.io/github/doctor-cornelius/django-powercrud/branch/main/graph/badge.svg)](https://codecov.io/github/doctor-cornelius/django-powercrud)
[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](#supported-versions)
[![Django](https://img.shields.io/badge/django-4.2%20%7C%205.2-0C4B33)](#supported-versions)
[![PyPI](https://img.shields.io/pypi/v/django-powercrud.svg)](https://pypi.org/project/django-powercrud/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Renovate](https://img.shields.io/badge/renovate-enabled-brightgreen?logo=renovatebot)](https://developer.mend.io/github/doctor-cornelius/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](https://github.com/carltongibson/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. CI blocks on a curated Playwright smoke subset, while the full browser regression suite remains available locally and for broader release validation. Expect rough edges while APIs settle, and pin the package if you rely on current behaviour.

See the [full documentation](https://doctor-cornelius.github.io/django-powercrud/).

## 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)

```python
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_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)

```python
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](https://doctor-cornelius.github.io/django-powercrud/guides/getting_started/) guide for base template requirements.
- Continue with [Setup & Core CRUD basics](https://doctor-cornelius.github.io/django-powercrud/guides/setup_core_crud/) for the first full view configuration, then use [Filtering](https://doctor-cornelius.github.io/django-powercrud/guides/filtering/) for the dedicated filter guide.
- Add [Inline editing](https://doctor-cornelius.github.io/django-powercrud/guides/inline_editing/) and [Bulk editing (synchronous)](https://doctor-cornelius.github.io/django-powercrud/guides/bulk_edit_sync/), then move to [Async Manager](https://doctor-cornelius.github.io/django-powercrud/guides/async_manager/) and [Bulk editing (async)](https://doctor-cornelius.github.io/django-powercrud/guides/bulk_edit_async/) when you need background work.
- Use [Styling & Tailwind](https://doctor-cornelius.github.io/django-powercrud/guides/styling_tailwind/) and [Customisation tips](https://doctor-cornelius.github.io/django-powercrud/guides/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, blocking Playwright smoke tests, and a fuller local browser regression suite.

## 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 5.2
- Python 3.14 with 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:

```bash
./runproj up          # build images, start services, enter the Django container
./runtests           # run the full local test suite, including the full Playwright browser suite
```

Dependencies are managed with [`uv`](https://github.com/astral-sh/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](https://doctor-cornelius.github.io/django-powercrud/reference/dockerised_dev/) for full details.
