iru-setup-python-fastapi
Scaffold a new FastAPI service with uv (`uv init --bare` + `uv add` with the pinned ranges of the author's docs: `fastapi[standard]>=0.142.2,<0.143.0`, Pydantic 2, pydantic-settings, SQLModel or plain
SKILL.md.claude/skills/iru-setup-python-fastapi/SKILL.md
GitHubSetup Python FastAPI
Scaffold a FastAPI service with uv, then layer on this catalog's Python toolchain and a small, real, tested
application: validated settings, a lifespan-owned database engine, health probes, one sample resource through every
layer, Alembic migrations, fast and container-backed test tiers, API docs sources, a production container image, and
Sonar configuration. Everything in this skill and its reference/ files was rendered into throwaway projects and
proven against the real tooling (2026-10-14: uv 0.12.8, CPython 3.13.15, FastAPI 0.142.4, Starlette 1.8, Pydantic
2.14, SQLModel 0.0.47, SQLAlchemy 2.0.54, Alembic 1.20, pytest 9.1, testcontainers 4.15, Ruff 0.17, mypy 2.4, Sphinx
9.1, Docker 29.8, PostgreSQL 18) — the gotchas called out inline are observed behavior. See Verification notes.
The generated code is the first exemplar of what iru-fastapi-code-one-task enforces (web → service → data
layering, Annotated dependencies, the SQLModel model family, one transaction per request, domain errors mapped in
main.py, Alembic for every schema change), and the commands, paths and markers are the scaffold contract that
iru-python-test/-coverage/-code-quality/-docstrings/-bump-version and iru-setup-python-github-workflows
detect and call.
Reference files — read only what this run needs
| Read | When |
|---|---|
reference/tooling-templates.md |
Always. The uv commands, the verified pyproject.toml (+ per-shape diffs), scripts/export_openapi.py, docs/api/conf.py + index.rst, .env.example per shape. |
reference/app-templates.md |
Always. Every app/ module and every fast test of the default shape. |
reference/persistence-templates.md |
Always. Alembic + the integration tier (database: postgresql/sqlite), and the file replacements for orm: sqlalchemy, database: sqlite, database: none. |
reference/auth-templates.md |
Only with auth: yes. |
reference/docker-and-sonar.md |
Always (the Dockerfile is always written); its Sonar section only when sonar ≠ none. |
Step 0 — Resolve inputs
Invoked stand-alone (/iru-setup-python-fastapi) or by iru-setup-python-repository, which passes resolved answers
through args as key: value lines, one per line, e.g.:
name: orders-api
package: orders_api
description: Order management API.
license: MIT
developer-name: Jane Doe
developer-email: jane@example.com
organization-url: https://github.com/example-org
python-version: 3.13
database: postgresql
orm: sqlmodel
auth: no
open-source: yes
visibility: public
ci: yes
distribution: internal
sonar: cloud
sonar-organization: example-org-github
sonar-project-key: example-org_orders-api
sonar-host-url: https://sonarcloud.io
mode: new
on-existing: ask
Parse any such lines now; every key found is resolved — never ask it again. If args is absent or not in this
format, treat everything as unset.
Recognized keys:
- Identity:
name(the distribution name in[project].name, lowercase kebab-case; also the image name and whatimportlib.metadata.version()looks up),package(snake_case identifier — the code itself always lives in theapp/package per the docs' layout, sopackageis only used for the Compose project/database names and as a fallback title; accept and validate it, don't create a second package),description,license(SPDX id or display name — MIT License →MIT, Apache License 2.0 →Apache-2.0, No license → omit thelicensekey and say so),developer-name,developer-email,organization-url(→[project].authorsand[project.urls]). - Shape (this skill):
python-version(default3.13;requires-pythonstays>=3.12),database(postgresql/sqlite/none, defaultpostgresql),orm(sqlmodel/sqlalchemy, defaultsqlmodel; ignored withdatabase: none),auth(yes/no, defaultno). - Shared pipeline vocabulary:
open-source(yes/no),visibility(public/private/internal— only keys the Sonar recommendation),ci(yes/no— only consulted by the Sonar question),distribution(none/internal/store— recorded for the report only: theDockerfileis written in every case andiru-setup-python-github-workflowsdecides what is pushed),sonar(cloud/self-hosted/none) plus, only whencloud/self-hosted,sonar-organization/sonar-project-key/sonar-host-url,mode(new/existing),on-existing(ask/keep/update/replace, defaultask, for scripted runs).
Ignore any other key (ci-tests, pages, publish, integration-branch, stable-branch, api, flavor — an
orchestrator may send its whole vocabulary). mode: existing marks an update run but never means "update
silently": Step 1 still warns and asks per pre-existing artifact unless on-existing says otherwise.
Step 1 — Survey the repository
- If
modewasn't supplied, derive it: a rootpyproject.toml⇒existing, elsenew. Don't ask it. - Classify an existing
pyproject.toml:fastapiamong its dependencies (orrequirements*.txt, or anapp/main.py/src/*/main.pycreatingFastAPI() ⇒ an existing FastAPI service — nouv init; later steps merge into it. Read its layout (app/package vssrc/<pkg>/vs the Full Stack template'sapp/api/+app/core/), its persistence (sqlmodel/sqlalchemy/alembic.ini), its runner (uv.lock/poetry.lock/pdm.lock/Pipfile.lock/ plain pip) and fixdatabase/orm/authfrom what is there, telling the user when that disagrees withargs. Never move existing code into theapp/layout — adapt paths ([tool.coverage.run] source, Sphinx automodules,DockerfileCOPY,[tool.fastapi] entrypoint) to the real package instead. A non-uv runner: say this skill's commands are uv-based, and ask Adopt uv (convert dev extras to[dependency-groups],uv lock, keep the other tool's files until the user removes them) / Stop. Anything else with apyproject.toml(Django, a library, Flask) ⇒ stop and say so (suggestiru-setup-python-repositoryto pick the right flavor); neveruv initover another project. - Survey every artifact this skill owns:
pyproject.toml([project]metadata/version,[build-system], the dependency groups,[tool.fastapi],[tool.ruff*],[tool.mypy]/[tool.pydantic-mypy],[tool.pytest.ini_options],[tool.coverage.*]),uv.lock,.python-version, theapp/package (main.py,settings.py,db.py,dependencies.py,routers/,services/,data/,models/,security.py), the sample resource (app/routers/books.pyand siblings),tests/(conftest.py,fakes.py,unit/,integration/),alembic.ini+migrations/(env.py,script.py.mako,versions/),scripts/export_openapi.py,docs/api/conf.py+docs/api/index.rst,Dockerfile,.dockerignore,compose.yaml/docker-compose.yml,.env.example,sonar-project.properties. - Announce the mode before asking anything else:
- Nothing owned exists: "Scaffolding the FastAPI service from scratch."
- Anything owned exists (or
mode: existing): "Updating an existing setup — found: <list with paths> (FastAPI <version from uv.lock or the installed package>, layout <app/ | src/<pkg>/ | full-stack template>, runner <uv | poetry | ...>)." Warn that each will be handled individually, then resolve one action per artifact:on-existingiskeep/update/replace: apply it to every artifact without asking (still print the warning). Exception:replacenever regenerates existing application source or tests (see below) — treat them askeepand say so.- Otherwise: ask with
AskUserQuestion, up to 4 artifacts per call (one question each), naming concrete contradictions with this run's choices in the question (e.g. "[tool.coverage.xml]writescoverage.xmlat the root — the gates and Sonar readbuild/coverage/coverage.xml", "nointegrationmarker — the workflows' integration job selects-m integration", "main.pyuses@app.on_event— the templates use a lifespan", "alembic.inihard-codessqlalchemy.urlwith a password", "asonar-project.propertiesexists but you chosesonar: none"):- Update (Recommended) — merge: add what's missing and correct what this skill owns (tool sections and
their contract values, missing dev/docs dependencies via
uv add, the coverage XML path, the.dockerignoreentries, theenv.pyURL source), keeping everything else. Show the diff; customizations survive, but a customized part this skill owns may be rewritten. - Keep as is — leave it untouched and skip the steps that only serve it. It may stay out of date or disagree with this run's choices — Step 15 lists each mismatch.
- Replace — regenerate from the template; customizations are lost (recoverable only from git history).
Not offered for application source, tests, or applied migrations (
app/**,tests/**,migrations/versions/**) — that is real code once the project exists; recommend Keep as is and say why. - Stop (first batch only) — end without changing anything; report that and end here.
- Update (Recommended) — merge: add what's missing and correct what this skill owns (tool sections and
their contract values, missing dev/docs dependencies via
- Never add the sample resource to an existing service unless the user asks — on the update path it would be
dead code. Ask once: "Add the
bookssample resource as a reference?" (default No). - Ask about
sonar-project.propertiesonly after Step 2 resolvessonar: withsonar: none, Update/Replace mean removing the file and Keep leaves it as a reported mismatch.
- Placement (new service): the repository root. Other files (docs, CI,
README.md,LICENSE,.git,CLAUDE.md) are fine —uv init --bareonly writespyproject.toml. If the root holds something that looks like another application (src/,app/,manage.py,package.json), ask whether to scaffold into the root anyway or into a subdirectory named<name>.
Step 2 — Collect identity and options
For every key Step 0 resolved, use it. In mode: existing, read identity from [project] (name, description,
license, authors, urls) and confirm it in one line instead of asking. Otherwise ask (plain conversation for free
text, AskUserQuestion for bounded choices):
- name (default: the repository directory's basename, lowercased, kebab-cased), package (derived:
namewith-→_; confirm only — must be a legal identifier and notapp,fastapi,pydantic,test, or a stdlib module), description, developer name/email, organization URL (default fromgit remote get-url origin). - license — MIT (Recommended) "FastAPI's own license" / Apache-2.0 / No license (proprietary) — omit
[project].license/ Other (ask the SPDX id). Remind in Step 15 to add aLICENSEfile if missing. - python-version — 3.13 (Recommended) "what the author's docs run and CI images use" / 3.14 "newest;
check every dependency has wheels" / 3.12 "the floor (
requires-python = ">=3.12")". Use only a versionuv python listcan provide (Step 3). - database — PostgreSQL (Recommended) "async SQLAlchemy engine on asyncpg; fast tests on in-memory SQLite, the integration tier on a real PostgreSQL via testcontainers" / SQLite "aiosqlite file database — a single host and writer; no integration tier" / None "no persistence layer: an in-memory adapter behind the same repository port, no ORM, no Alembic".
- orm (only when
database≠none) — SQLModel (Recommended) "the FastAPI docs' default: one class family for table + validation + OpenAPI" / SQLAlchemy 2.0 "DeclarativeBase+Mappedwith separate Pydantic schemas — full typing, no SQLModel coupling". - auth — "Add a sample bearer-token login protecting the write endpoints (PyJWT + pwdlib/Argon2, one admin account from settings)?" No (Recommended) "add real auth when the product decides on an identity provider" / Yes.
- open-source, then sonar — "Configure SonarCloud / SonarQube for this project?". Resolve
visibilityonly now if missing (gh repo view --json visibility -q .visibility, lowercased; else ask Public/Private —internalcounts as private). Ifopen-source: yesbut private/internal, flag the contradiction and ask which is right. Recommend SonarCloud (cloud) only for a public open-source repository; otherwise say SonarCloud is free only for public open-source projects and recommend None, offering self-hosted second. Withci: no, say no CI workflow would send reports and recommend None; if the user still picks one, write the properties file anyway and say so in Step 15. Forcloudasksonar-organization(suggest<owner>-github) andsonar-project-key(suggest<owner>_<repo>), hosthttps://sonarcloud.io; forself-hostedask the host URL, the organization only if the server uses them, and the project key. - distribution — only recorded for the report (Step 0). Don't ask it stand-alone.
Derive <title> (the human title used in FastAPI(title=...) and the Sphinx project) from name
(orders-api → "Orders API"); confirm it in one line.
Step 3 — Toolchain and versions
- uv:
command -v uv && uv --version. Missing → tell the user to install it (https://docs.astral.sh/uv/getting-started/installation/) and stop; neverpip installinto a system Python. - Python:
uv python find <python-version>oruv python install <python-version>(verified: installs CPython 3.13 in seconds; nothing system-wide changes). - Versions: the
uv addranges inreference/tooling-templates.mdare the digest's pins and were verified — use them as written. Look up the latest releases only to report drift (curl -s https://pypi.org/pypi/<pkg>/json | python3 -c 'import json,sys; print(json.load(sys.stdin)["info"]["version"])'): if FastAPI has moved past the pinned minor (0.143.x existed at verification time), say so in the report and leave the upgrade to a deliberate follow-up (FastAPI is 0.x — breaking changes land in minors). Never pin Starlette. - uv image tag for the
Dockerfile: the latestuvrelease from the same PyPI lookup (verifiedghcr.io/astral-sh/uv:0.13.1); fall back to0.13.1offline. Record live vs fallback for the report. - Docker:
docker info >/dev/null 2>&1— needed only for Step 14's integration tier, Alembic check against PostgreSQL, and image build; without it those are reported unverified, never passed.
Step 4 — Project manifest with uv
New service: run the commands in reference/tooling-templates.md ("uv commands") in order — uv init --bare,
uv python pin, then edit [project] (version = "0.1.0.dev0", license, authors, requires-python = ">=3.12", [project.urls]) and add [build-system] (uv_build) + [tool.uv.build-backend] (module-name = "app", module-root = "") and create app/__init__.py before the first uv add (gotcha, verified: uv add
builds the project and fails with Expected a Python module at: app/__init__.py). Then the three uv add calls
for the run's shape. Don't add readme = "README.md" unless a README already exists (uv_build fails on a missing
readme; iru-setup-readme writes it later).
Existing service (Update): uv add only what's missing from the same lists (respecting ranges the project
already pins — report conflicts instead of overriding them), keep its build backend, and set version only if it
has none (0.1.0.dev0; a version already present is never touched — iru-python-bump-version owns it).
The version's single source is [project].version; the app reads it with importlib.metadata.version("<name>")
(app/__init__.py). Development versions are PEP 440 X.Y.Z.dev0.
Step 5 — Tool configuration (all in pyproject.toml)
Append the tool sections from the verified pyproject.toml in reference/tooling-templates.md, applying its
per-shape diff:
[tool.fastapi] entrypoint = "app.main:app".[tool.ruff] line-length = 88(Ruff/Black's default —ruff formatoutput with no config; PEP 8's 79 is prose advice in the docs, 88 keeps formatter and linter in agreement),[tool.ruff.lint] select = ["E", "F", "W", "I", "N", "UP", "B", "S", "C4", "SIM", "RUF", "D", "PT", "ASYNC", "FAST"],pydocstyle.convention = "google", per-file-ignorestests/** = ["S101", "D"],migrations/versions/** = ["D"].[tool.mypy] strict = true,plugins = ["pydantic.mypy"](+[tool.pydantic-mypy]);uv run mypy .checksapp/,tests/,migrations/,scripts/anddocs/api/conf.py(all verified clean).[tool.pytest.ini_options]addopts = "-ra --strict-markers --strict-config",testpaths = ["tests"],markers = ["integration: needs Docker (testcontainers)"],filterwarnings = ["error::DeprecationWarning"].[tool.coverage.run] branch = true, source = ["app"], concurrency = ["greenlet", "thread"](the concurrency line only with a database — gotcha in the tooling reference),[tool.coverage.report] fail_under = 80, show_missing = true(the author's docs use 90 — offer it as a ratchet, the catalog gate is 80),[tool.coverage.xml] output = "build/coverage/coverage.xml".
An existing service with another layout: point source at its real package; keep its own stricter settings (a
higher fail_under, more Ruff rules) and only add what the contract needs.
Step 6 — Application skeleton
Write the app/ package from reference/app-templates.md (new service, or an existing one only for files that are
absent and the user wants): __init__.py, settings.py (DatabaseSettings with APP_DATABASE_URL as a required
SecretStr, Settings(DatabaseSettings), @lru_cache get_settings), db.py, models/ (naming convention, the
SQLModel Book family, HealthStatus), services/ (errors.py, ports.py, books.py), data/books.py,
dependencies.py, routers/health.py + routers/books.py, main.py (create_app() + module-level app,
lifespan, exception handlers). Replace the placeholders as that file's header says; rename the sample resource only
if the user asked for a different first resource. Apply the shape's replacements from
reference/persistence-templates.md (orm: sqlalchemy, database: none).
Step 7 — Persistence (database ≠ none)
From reference/persistence-templates.md: run uv run alembic init -t async migrations (new service), then replace
alembic.ini, migrations/env.py and migrations/script.py.mako with the templates, delete migrations/README,
and write migrations/versions/0001_create_book_table.py verbatim (Create Date = today) — no database is needed to
write it; Step 14 proves it matches the models. An existing service that already has Alembic: never touch applied
revisions; Update only env.py's URL source (settings instead of a literal URL), compare_type=True, and the
render_as_batch line, and add the post-write hooks to alembic.ini. Schema changes always ship as reviewed
revisions; nothing calls create_all outside tests, and the app never migrates at start-up.
Step 8 — Auth (auth: yes)
From reference/auth-templates.md: uv add "pyjwt>=2.15,<3" "pwdlib[argon2]>=0.3,<0.4", write app/security.py,
app/models/auth.py, app/routers/auth.py, the auth versions of settings.py, dependencies.py,
routers/books.py, the test files, and apply its small diffs (models/__init__.py, main.py, docs/api/index.rst,
compose.yaml, .env.example). Never commit a real secret or hash; .env.example carries placeholders.
Step 9 — Tests
From reference/app-templates.md (and the shape's replacements): tests/__init__.py, tests/unit/__init__.py
(empty), tests/conftest.py, tests/fakes.py, tests/unit/test_*.py; with database: postgresql also
tests/integration/__init__.py, tests/integration/conftest.py and test_books_postgres.py from the persistence
reference — one postgres:18-alpine container per test session via testcontainers.community.postgres (gotcha,
verified: the old testcontainers.postgres path emits a DeprecationWarning that the strict filterwarnings turns
into a collection error on testcontainers 4.15), migrated with alembic.command.upgrade, the real app driven through
asgi_lifespan.LifespanManager, and a compare_metadata(...) == [] test. Every integration test carries
pytest.mark.integration and lives under tests/integration/ — both signals the gates use.
Step 10 — OpenAPI export and Sphinx API docs
Write scripts/export_openapi.py, docs/api/conf.py and docs/api/index.rst from
reference/tooling-templates.md (one .. automodule:: per module of the run's shape; the autodoc-skip-member
hook in conf.py is required — see that file's gotcha). Never create or edit docs/antora.yml,
docs/antora-playbook.yml or docs/modules/ — iru-setup-antora owns them; the Sphinx output goes to
build/api-docs/ and the workflows publish it under the site's api/.
Step 11 — Container image, local stack, .env.example
Write Dockerfile, .dockerignore, compose.yaml (database: postgresql/sqlite — none for database: none)
from reference/docker-and-sonar.md and .env.example from the tooling reference, with python:<python-version>-slim
and the uv tag from Step 3. Written for every run — distribution only decides what the workflows push. An existing
Dockerfile that runs migrations in its CMD/entrypoint, runs as root, or uses shell-form CMD: name it in the
Step 1 question rather than fixing it silently.
Step 12 — sonar-project.properties
Only when sonar is cloud/self-hosted: write it from reference/docker-and-sonar.md (sonar.python.version,
coverage build/coverage/coverage.xml, xunit build/test-results/pytest*.xml, Ruff build/reports/ruff.json).
With sonar: none, write nothing (and handle an existing file per Step 1).
Step 13 — Lock, format, lint-fix
uv lock && uv sync --locked
uv run ruff format .
uv run ruff check --fix .
The templates are already formatted; this catches placeholder substitutions that changed line lengths (fix any
remaining E501 by rewording, never by raising line-length). In an existing service, run ruff format --check .
first and ask before reformatting files this skill didn't write (suggest a separate "apply Ruff format" commit).
Step 14 — Verify with the contract's canonical commands
Run, in order, and fix anything this skill wrote until green — never "fix" pre-existing application code to make a gate pass; report it instead:
uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run mypy .
uv run pytest -m "not integration" --cov --cov-report=xml --cov-report=term-missing \
--junitxml=build/test-results/pytest.xml # coverage ≥ 80% (fail_under) from these tests only
uv run --group docs sphinx-build -W --keep-going -b html docs/api build/api-docs
uv run python scripts/export_openapi.py build/api-docs/openapi.json
uv build # sdist + wheel into dist/
Then, only when Docker is reachable (otherwise mark each unverified — never skip silently):
uv run pytest -m integration --junitxml=build/test-results/pytest-integration.xml # database: postgresql
# Alembic against a throwaway PostgreSQL (database: postgresql), exactly what CI's migrations job runs:
docker run -d --rm --name <name>-verify-db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=app -p 127.0.0.1::5432 postgres:18
PORT="$(docker port <name>-verify-db 5432 | head -1 | cut -d: -f2)" # wait for pg_isready first
APP_DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:$PORT/app" sh -c \
'uv run alembic upgrade head && uv run alembic check && uv run alembic heads && uv run alembic downgrade base && uv run alembic upgrade head'
docker rm -f <name>-verify-db
docker build -t <name>:verify .
database: sqlite: run the same Alembic sequence withAPP_DATABASE_URL=sqlite+aiosqlite:///build/alembic-check.db(no Docker needed); there is no integration tier (pytest -m integrationexits 5 — "no tests collected" — which is expected, not a failure).database: none: no Alembic, no integration tier.- With Docker, smoke-test the image as in
reference/docker-and-sonar.md: database container on a user network,alembic upgrade headfrom the image, then the app —docker inspecthealthhealthy,/readyz→200, onePOST /api/v1/books→201; remove everything you started.auth: yesalso passesAPP_JWT_SECRETandAPP_ADMIN_PASSWORD_HASHat run time. - Expected on a new default-shape service (verified): Ruff clean, 35 files formatted, mypy strict clean on 35 files,
33 fast tests passed at 100% coverage, 4 integration tests passed,
alembic check"No new upgrade operations detected." with one head, Sphinx built with 0 warnings, OpenAPI 3.1.0 exported, wheel + sdist built, image built.
Remove nothing the gates produce under build/ (ignored); delete dist/ only if the user prefers.
Step 15 — Report
Start with the mode (scaffolded from scratch or updated an existing setup) and the location. Then:
- Per owned component, the action actually taken — created / updated / replaced / kept as is / removed /
skipped — for:
pyproject.toml/uv.lock/.python-version, application sources (app/), tests config and tests, quality configs (Ruff/mypy/pytest/coverage sections), Alembic (alembic.ini+migrations/), Sphinx API docs sources (docs/api/),scripts/export_openapi.py,Dockerfile/.dockerignore/compose.yaml/.env.example,sonar-project.properties; and for every kept one, each mismatch with this run's choices. - The resolved shape:
python-version,database,orm,auth, license,open-source,distribution(recorded),sonar(with thevisibilityused and where it came from; ifci: noand Sonar was configured, say no CI step sends reports). - Versions: the installed FastAPI/Starlette/Pydantic/SQLModel or SQLAlchemy/Alembic/pytest/Ruff/mypy from
uv.lock, the uv image tag (live or fallback), and any drift past the pins (e.g. a newer FastAPI minor) left for a follow-up. - Each Step 14 command and its result (tests passed, coverage %, mypy/Ruff counts,
alembic check, Sphinx warnings, image built), plus anything unverified and why. - For the workflows/orchestrator: database URL env var
APP_DATABASE_URL(driverpostgresql+asyncpg://, orsqlite+aiosqlite://), migration commandsuv run alembic upgrade head/check/heads/downgrade base, integration markerintegration+tests/integration/, OpenAPI atbuild/api-docs/openapi.json, Compose servicesdb/migrate/api.
Finish with a Warn explicitly block:
- Review before committing —
[project]identity/license/authors and the Sonar keys. - Never commit
.env;.env.example,uv.lockand.python-versionare committed.auth: yes: keep the Argon2 hash single-quoted in.env. - Migrations run once per release as a one-shot job (
compose.yamlmigrate, a Kubernetes Job), never at start-up or per replica; review every autogenerated revision. database: sqliteis single-host/single-writer;database: nonekeeps data in one worker's memory — both are starting points, not production storage.- The image runs one Uvicorn process: scale with replicas, not
--workers, under an orchestrator. sonar: cloud/self-hosted: aSONAR_TOKENsecret and the Sonar project must exist before CI analysis succeeds.- No
.gitignore, workflows,CHANGELOG.md,README.mdor Antora files were written —iru-setup-python-gitignore(must ignorebuild/,dist/,.venv/,.env, the caches,.coverage*),iru-setup-python-github-workflows,iru-setup-changelog,iru-setup-readmeandiru-setup-antoracover them (iru-setup-python-repositoryruns them next). Addreadme = "README.md"to[project]once the README exists. - If a license was chosen and no
LICENSEfile exists, suggestiru-check-license.
Verification notes
Rendered into $TMPDIR/iru-verify/python/setup-fastapi/ (outside the repository) on 2026-10-14 — uv 0.12.8,
CPython 3.13.15, Docker 29.8.2 — in six projects: the default shape (postgresql + sqlmodel), orm: sqlalchemy,
auth: yes on both ORMs, database: sqlite, database: none. Each passed uv sync --locked, uv lock --check,
ruff check ., ruff format --check ., mypy . (strict), the fast tier with coverage ≥ 80% (98.6–100%),
sphinx-build -W, export_openapi.py, uv build, and docker build. PostgreSQL shapes: integration tier green
(4 tests, ~3.5 s incl. container start) and alembic upgrade head / check / single head / downgrade base /
upgrade head green against postgres:18 with only APP_DATABASE_URL set (as CI does — also with
auth: yes); images migrated a real database and served healthy / 201 (auth: 401 without a token, 201 with
one from /token). SQLite: the Alembic sequence on a file database, image migrated through a volume and served
201. docker compose config -q validated each compose.yaml (not brought up with compose up; the same services
were run with docker run on a user network). Observed gotchas, each fixed in the templates: greenlet missing without
sqlalchemy[asyncio]; coverage under-reporting without concurrency = ["greenlet", "thread"]; uv add failing
before app/__init__.py exists; testcontainers.postgres deprecation; SQLModel Field(regex=...) not enforcing the
pattern (use schema_extra={"pattern": ...}); import sqlmodel in revisions failing mypy; sphinx-autodoc-typehints
warnings from imported names; Starlette 1.8 TestClient requiring httpx2 (the templates use AsyncClient +
ASGITransport instead); Alembic needing a URL-only settings class so migration jobs don't need app secrets. Not
verified: Python 3.12/3.14 runs (only 3.13), and the GitHub Actions side (owned by the workflows skill).
Sources
- irurueta docs:
backend/fastapi/getting-started.adoc(uv,[tool.fastapi]),project-structure-and-layered-architecture.adoc,dependency-injection.adoc,dependencies-with-yield.adoc(scope="function", commit placement),settings-lifespan-and-background-tasks.adoc,sql-databases-with-sqlmodel.adoc(model family, async stack, Alembic),testing.adoc(dependency_overrides, SQLite + PostgreSQL tiers,httpx2note),async-and-concurrency.adoc,oauth2-password-and-jwt.adoc,deployment.adoc(pinning),docker-and-kubernetes.adoc(uv Dockerfile, health probes, Compose, migration job),pydantic-v2-essentials.adoc,introduction-and-architecture.adoc - irurueta docs:
backend/flask/database-migrations.adoc(naming convention, autogenerate review, CI checks),backend/flask/flask-sqlalchemy.adoc,backend/flask/docker-and-kubernetes.adoc(multi-stage uv image, UID 10001, stdlib health check),backend/pyramid/sqlalchemy-transactions-and-migrations.adoc(alembic check, metadata comparison test),backend/tornado/databases-and-async-drivers.adoc(sqlalchemy[asyncio], AsyncSession rules),programming-languages/python/virtual-environments-and-packaging.adoc,programming-languages/python/docstrings.adoc,programming-languages/python/testing.adoc,backend/docker/image-best-practices-and-security.adoc - This catalog: the Python scaffold contract shared with
iru-setup-python-repository,iru-setup-python-github-workflowsand theiru-python-*gates;iru-setup-nestjs-appandiru-setup-php-laravel(structure) - uv: https://docs.astral.sh/uv/guides/integration/fastapi/, https://docs.astral.sh/uv/guides/integration/docker/; Alembic: https://alembic.sqlalchemy.org/en/latest/cookbook.html#using-asyncio-with-alembic; testcontainers-python: https://testcontainers-python.readthedocs.io/; Sphinx: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html