Setup Python Django

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Scaffolds a Django 6.1 project with uv and startproject, or brings an existing Django project up to date, and layers this catalog’s Python toolchain and a small, tested project skeleton on top.

Purpose

iru-setup-python-django runs uv init --bare, uv add and django-admin startproject config ., then post-processes the result:

  • A PEP 621 pyproject.toml (version = "0.1.0.dev0", uv_build backend) with Ruff (including DJ rules, Google docstrings), mypy strict with django-stubs, pytest-django, and coverage with an 80% floor and Cobertura XML at build/coverage/coverage.xml.

  • A split settings package config/settings/{base,local,test,production}.py driven by fail-fast environment variables, plus config/env.py.

  • Apps under apps/: apps.accounts (custom user created before the first migration), apps.core (abstract TimeStampedModel, /healthz and /readyz probes) and a sample catalog app (model, @transaction.atomic service, admin, API).

  • The API as Django REST Framework with drf-spectacular (default), Django Ninja, or none.

  • Fast tests on in-memory SQLite and, for PostgreSQL, an integration tier on a testcontainers PostgreSQL.

  • WhiteNoise, Gunicorn (gthread on WSGI, or uvicorn_worker.UvicornWorker on ASGI for Ninja), Sphinx API docs under docs/api/, a multi-stage non-root Dockerfile, .dockerignore, compose.yaml (postgres:18, one-shot migrate, app), .env.example, and sonar-project.properties when Sonar is enabled.

  • A browser UI tier for the server-rendered pages it ships (the Django admin), per the catalog’s UI contract (see Building user interfaces): .ui-quality.yml, pytest-playwright and axe-playwright-python, LocaleMiddleware (so right-to-left renders for real), the shared tests/ui/ui_screenshots.py helper and an AdminLoginScreen test that captures .ui-screenshots/ across left-to-right/right-to-left x light/dark with an axe check. It is selected with -m ui and kept out of the fast tier and its 80% coverage floor; the template lives in reference/ui-tests.md.

The generated code is the first exemplar of the iru-django-code-one-task conventions, and every verification command is the one the CI workflows and the iru-python-* gate skills run. The skill announces whether it is scaffolding from scratch or updating an existing project and, per owned artifact that already exists, asks Update / Keep as is / Replace (or Stop) unless on-existing pre-answers. Replace is not offered for manage.py, settings, config/urls.py or apps.

Purpose group

Python Bootstrap

Plugin

Shipped by the iru-python plugin of the ai-catalog marketplace (install with /plugin install iru-python@ai-catalog; see Plugins).

Invocation

/iru-setup-python-django

When called from iru-setup-python-repository, the resolved answers arrive as args key: value lines.

Inputs

Argument Required Description Default

name, package, description

No

Distribution name (lowercase kebab-case, also image and compose project name), snake_case identifier (names the default PostgreSQL database and user) and description.

Repository directory name; asked

license, developer-name, developer-email, organization-url

No

[project] license (SPDX; "No license" adds the Private :: Do Not Upload classifier) and authors.

Asked (existing projects: read from pyproject.toml)

python-version

No

CPython minor (3.12 to 3.14) for .python-version, the Dockerfile and Sonar; requires-python stays >=3.12.

3.13

database

No

postgresql or sqlite. none is invalid because Django auth, sessions and admin need a database.

postgresql

api

No

drf, ninja or none. Fixed by an existing project’s installed API framework.

drf

open-source, visibility, ci, distribution

No

Shared pipeline vocabulary. visibility and ci only drive the Sonar recommendation; distribution is reported only (the Dockerfile is always written).

Asked or derived (gh repo view)

sonar (+ sonar-organization, sonar-project-key, sonar-host-url)

No

cloud, self-hosted or none; writes sonar-project.properties unless none.

Asked; none recommended for private repositories

accessibility

No

enforce, report, off or none — whether accessibility and assistive-technology support is wanted and the automated level of the browser UI tests, written to .ui-quality.yml. none opts out entirely: accessibility: none is written to .ui-quality.yml, no accessibility test tooling (axe-core) is installed and the accessibility attributes are omitted from the templates. Otherwise the templates carry the assistive-technology attributes. Asked only in a stand-alone run ("Support accessibility and assistive technologies?"); an existing .ui-quality.yml value is never silently flipped.

enforce; an existing .ui-quality.yml pre-selects its value

mode

No

new or existing. Informational: never means "update silently".

Derived: manage.py plus Django dependency means existing

on-existing

No

ask, keep, update or replace, pre-answering the per-artifact question for scripted runs.

ask

Other keys (ci-tests, pages, publish, orm, and so on) are ignored. A Python project that is not Django (a FastAPI service, a library) stops the skill. An existing project with migrations on the default auth.User keeps its user model and skips apps.accounts.

Outputs

  • pyproject.toml, uv.lock and .python-version with all tool sections.

  • manage.py, config/ (settings package, env.py, urls.py, asgi.py, wsgi.py, and api.py for Ninja), gunicorn.conf.py.

  • apps/core/, apps/accounts/ and, for new projects or on request, apps/catalog/ with its API files and generated first migrations.

  • tests/ (conftest.py, factories.py, fast tier, and integration/ with PostgreSQL).

  • .ui-quality.yml and the UI tier: tests/ui/ui_screenshots.py, tests/ui/conftest.py, tests/ui/test_admin_login.py (captures land in .ui-screenshots/screen/AdminLoginScreen/<state>--<direction>--<theme>.png, plus an a11y-report.jsonl); the ui pytest marker, the Playwright dev dependencies and LocaleMiddleware in the settings.

  • docs/api/conf.py and the API reference pages.

  • Dockerfile, .dockerignore, compose.yaml, .env.example, and sonar-project.properties when Sonar is enabled.

  • A report: mode, per-component action (created / updated / replaced / kept as is / removed), resolved choices and server type, versions from uv.lock, .ui-quality.yml action and accessibility level, each verification command and result (including the -m ui tier: captures written, axe violations by rule id; unverified items such as Docker-dependent steps called out), and warnings (review identity and Sonar keys, never commit .env or db.sqlite3, production environment variables, migrations once per release, integration tests need Docker; the UI tier needs uv run playwright install chromium and is unverified without a browser).

No .gitignore, workflows, CHANGELOG.md, README.md or Antora files are written; the orchestrator runs the dedicated skills for those next.

Execution flow

flowchart TD A["Start /iru-setup-python-django"] --> B["Step 0: resolve inputs"] B --> C["Step 1: survey repository;\nannounce mode"] C -- "not a Django project" --> STOP["End without changes"] C -- Stop --> STOP C --> D["Step 2: collect identity and options"] D --> E["Step 3: toolchain and versions"] E --> F{"New project?"} F -- yes --> G["Step 4: scaffold with uv and startproject"] F -- no --> H["Skip scaffold"] G --> I["Step 5: pyproject.toml"] H --> I I --> J["Step 6: settings and entry points"] J --> K["Step 7: apps, custom user, first migrations"] K --> L["Step 8: tests"] L --> M["Step 9: Sphinx API docs"] M --> N["Step 10: Dockerfile, compose, .env.example"] N --> O{"Sonar enabled?"} O -- yes --> P["Step 11: sonar-project.properties"] O -- no --> Q P --> Q["Step 12: format"] Q --> R["Step 13: verify with gate commands"] R -- failure --> S["Fix what this skill wrote"] S --> R R --> T["Step 14: report"]

Dependencies

Invokes

None. It runs uv, docker and curl directly and reads its own reference/ files (project, settings, sample app and tests, DRF or Ninja, docs, Docker and Sonar templates). Step 13 runs the commands that the iru-python-* gate skills and the workflows call, without invoking those skills. The generated code follows the iru-django-code-one-task conventions.

Invoked by

Related agents

None.

Source

SKILL.md on GitHub — the file this page was generated from.