python-fastapi-setup

Python FastAPI Setup

Overview

Create or modernize FastAPI services around a small repeatable structure:

app/main.py -> app/core/config.py -> app/api/v1/endpoints/ -> middleware -> tests -> deployment

Prefer direct startup commands, typed settings, explicit lifespan ownership for process-level resources, and a minimal test suite. Keep the scaffold boring on purpose: a future maintainer should be able to find the app, settings, routers, health check, and startup command without hunting through wrapper scripts.

Workflow

1. Classify the workspace before writing files.

   • Treat the target as greenfield if it is empty or the user asks for a new service.
   • Treat it as existing if it has Python source, pyproject.toml, requirements.txt, an ASGI app, tests, Docker files, CI, or git history.
   • For existing projects, inventory the current entrypoint, router layout, dependency manager, settings pattern, middleware, tests, deployment files, and startup commands before editing.

2. For greenfield scaffolds, run the bundled script from this skill directory:

python3 scripts/scaffold_fastapi_project.py \
  --name inventory_api \
  --out /path/to/inventory_api

• The scaffold always generates gunicorn.conf.py, Docker, and Compose files for a production-ready default.
• The scaffold script renders reusable project and deployment configuration from assets/ for pyproject.toml, Docker, Compose, and Gunicorn. Update those assets when the shared standard changes; update the Python script when generation logic, arguments, app files, or dependency policy change.
• Read references/python-fastapi-blueprint.md before changing generated files or adding new script options.

1. For existing projects, patch conservatively.
   • Preserve working endpoints and behavior.
   • Before moving routes, record the existing endpoint contract: path, method, status code, response shape, sample payloads, headers, and any query/path parameters visible in the current code or tests.
   • Add or update regression tests for those existing contracts before or during the refactor. The tests should assert the old payloads and status codes, not newly invented placeholder data.
   • Move toward app/main.py only when it improves clarity or matches the user's request.
   • Retire wrapper launchers such as run_service.py after replacing them with documented direct commands.
   • Keep the repo's dependency manager unless there is a clear reason to change it.
   • Add only the modules and settings the service actually uses.
   • Do not replace legacy route payloads, IDs, names, or response field types with new sample fixtures just because the code moved into a cleaner module.