python-fastapi-ddd-tooling-skill
Scannednpx machina-cli add skill iktakahiro/python-fastapi-ddd-skill/python-fastapi-ddd-tooling-skill --openclawTooling & DX for FastAPI DDD Projects (uv / ruff / mypy / CI)
This skill is about developer experience and quality automation for a DDD FastAPI project, following the conventions in dddpy.
Goals
- One-command local setup (
make install) - Fast feedback loop (
make test,make format,make dev) - Reproducible CI (GitHub Actions + Python matrix)
Recommended stack (dddpy-style)
- Python
>=3.13 uvfor venv + dependency install + running toolsrufffor formatting/lintingmypyfor type checkingpytestfor tests
Makefile workflow (core targets)
Keep a small Makefile that shells out to tools inside .venv/:
venv: create.venvinstall: install editable package + dev depstest: run mypy + pytestformat: run ruff formatterdev: runfastapi devvia uv
CI workflow
Run make install + make test on push/PR with a Python version matrix (e.g., 3.13, 3.14) and install uv in CI.
App bootstrap patterns
- Use FastAPI
lifespanto create tables on startup and dispose the engine on shutdown. - Keep SQLAlchemy engine/session setup in
infrastructure/sqlite/database.py(or equivalent). - Configure logging once at startup (
logging.config.fileConfig(...)).
For concrete file templates (Makefile, workflow YAML, bootstrap snippets), read references/TOOLING.md.
Source
git clone https://github.com/iktakahiro/python-fastapi-ddd-skill/blob/main/skills/python-fastapi-ddd-tooling-skill/SKILL.mdView on GitHub Overview
This skill standardizes developer experience and quality automation for a Python FastAPI + SQLAlchemy DDD/Onion Architecture project, following dddpy conventions. It covers uv-based environment setup, Makefile workflows, ruff linting, mypy typing, pytest tests, and GitHub Actions CI.
How This Skill Works
It ships a compact Makefile that shells out to tools inside .venv, exposing targets like venv, install, test, format, and dev. A one-command setup (make install) bootstraps the environment; make test runs mypy and pytest for fast feedback, while make format enforces ruff formatting. CI replays the same steps with a Python version matrix to ensure reproducible builds.
When to Use It
- Bootstrapping a new FastAPI + SQLAlchemy DDD/Onion project with consistent tooling.
- Tightening developer experience by standardizing formatting, typing, and tests across the team.
- Adding reproducible CI with a Python version matrix and Makefile-driven checks.
- Onboarding new contributors with a single, documented setup flow.
- Migrating an existing project to dddpy-style tooling for better DX and quality gates.
Quick Start
- Step 1: Create a small Makefile with targets venv, install, test, format, and dev that operate inside .venv.
- Step 2: Add a GitHub Actions workflow that runs make install and make test on a Python version matrix.
- Step 3: Implement the bootstrap snippets (FastAPI lifespan, SQLAlchemy engine/session, and logging config) in your app.
Best Practices
- Keep Makefile small and delegate to tools in .venv (venv, install, test, format, dev).
- Pin Python to >=3.13 and install tools in a dedicated virtual environment (uv-based).
- Leverage FastAPI lifespan patterns and centralize DB startup/shutdown in infrastructure.
- Configure logging at startup with logging.config.fileConfig(...).
- Run type checks and tests locally before pushing (mypy + pytest) and mirror in CI.
Example Use Cases
- Bootstrapping a brand-new project with a Makefile, uv environment, and GitHub Actions CI.
- Upgrading an existing repo to include ruff, mypy, pytest, and a Python matrix CI.
- Implementing FastAPI lifespan-based DB initialization and cleanup in startup/shutdown.
- Centralizing engine/session creation in infrastructure/sqlite/database.py.
- Adding logging.config.fileConfig-based logging configuration across the app.
