ninja-devx

ninja-devx adds typed controllers and reusable resource policies to Django Ninja. It is intended for Django APIs that repeat ownership, tenant scoping, transaction, dependency-lifetime and error-handling rules across several endpoints. Services, repositories and contrib modules are optional.

Version 0.0.2 is the current alpha (0.0.1 was the first published release). See the scope and design rationale, comparison and support policy before adopting it.

class PostController(SoftDeleteMixin[Post, PostOut], CRUDController[Post, PostOut, PostIn]):
    owner_field = "author"
    search_fields = ("title", "body")
    filter_fields = {"status": ("exact",), "created": ("gte", "lte")}
    ordering_fields = ("created", "title")

    @post("/{pk}/publish", response=PostOut, decorators=[idempotent()])
    def publish(self, request: HttpRequest, post: Instance[Post]) -> Post:
        post.status = Post.Status.PUBLISHED
        post.save(update_fields=["status"])
        return post


api = NinjaAPI(auth=django_auth)
mount(api, {"/posts": PostController}, prefix="/v1")

These lines give you:

• list endpoints with search, generated filters, enum-checked ordering and pagination
• retrieve, create, update and partial update
• soft delete, restore and an idempotent publish action
• owner-only writes and schema-derived relation loading
• 422 for model validation errors, and domain errors mapped without exception handlers
• declared error responses included in OpenAPI

Principles:

• Controllers produce ninja.Routers and use Ninja authentication, pagination and serialization. Async stream preflight has a narrow operation-subclass integration that is tested against supported Ninja versions.
• Layers without force: plain controllers, services, use cases or dishka interactors all fit, and none is required.
• Typed end to end: mypy strict and pyright strict pass, and the package has no typing.Any.
• Configuration errors raise at startup.
• Controller overhead is measured against function views with explicit budgets (see performance).

Requires Python 3.11+, Django 4.2+ and django-ninja 1.7.x (support policy).

pip install ninja-devx    # extras: [guardian] [s3] [crypto] [orjson] [msgspec] [dishka] [svcs] [otel] [client] [contract]

Features

Start with the quickstart, then pick an example:

Every option, parameter, setting and error code is listed with its type and default in the configuration reference, generated from the code.

Contributing and security

See CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md.

License

Apache License 2.0.

Development

For the disposable Docker test stack and release gates, see release validation.

uv sync --group docs
uv run pytest                          # --update-snapshots to accept OpenAPI changes
uv run ruff check . && uv run ruff format --check .
uv run mypy && uv run pyright          # strict; tests/typing holds negative checks
for example in quickstart blog recipes saas async_api; do (cd examples/$example && uv run --project ../.. pytest -q); done
uv run python tools/generate_docs.py   # regenerate docs/options after changing options or docstrings
uv run mkdocs serve                    # DJANGO_SETTINGS_MODULE=tests.settings for the reference
uv run python benchmarks/overhead.py --check benchmarks/budget.json