python

Python & FastAPI Coding & Architecture Guidelines

Use this skill when extending the Python backend, managing dependencies, writing routes, services, or repositories, or working with core server logic.

---

1. Project Location & Package Management with uv

The backend lives entirely inside the server/ directory at the repository root. Always use uv for Python virtual environments, package management, locking, and task execution. Never use pip, poetry, or conda directly.

All commands below assume execution within the server/ folder (or via uv --directory server ...):

Adding Dependencies

• Production dependency:

  uv add <package>
  # Example:
  uv add httpx
  

• Development dependency:

  uv add --dev <package>
  # Example:
  uv add --dev pytest-mock
  

• Adding specific version or constraint:

  uv add "pydantic>=2.10.0"
  

Removing Dependencies

• Production dependency:

  uv remove <package>
  # Example:
  uv remove httpx
  

• Development dependency:

  uv remove --dev <package>
  # Example:
  uv remove --dev pytest-mock
  

Managing the Lockfile & Environment

• Sync virtual environment with lockfile:

  uv sync
  

• Update lockfile (uv.lock) without installing:

  uv lock
  

• Upgrade all dependencies:

  uv lock --upgrade
  

• Upgrade a specific dependency:

  uv lock --upgrade-package <package>
  

Running Tasks & Commands

Use uv run to execute tasks and Python tools defined in pyproject.toml (via taskipy):

• Development Server: uv run task dev
• Run Formatter & Linter Check: uv run task check
• Format & Auto-fix: uv run task format
• Type Checking: uv run task type-check
• Run Tests: uv run task test
• Generate Coverage HTML: uv run task cov-html
• Database Migrations:
  • Upgrade: uv run task upgrade (runs alembic upgrade head)
  • Downgrade: uv run task downgrade (runs alembic downgrade -1)