python

Python & FastAPI Coding & Architecture Guidelines

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

---

1. FastAPI & Dependency Injection

We use dependency-injector for wiring application components together.

• Wiring: The container is defined in server/app/core/container.py and wired in server/app/main.py.

• Dependency injection in Routes:

  • Decorate endpoints with @inject (from dependency_injector.wiring).

  • Create clean dependency type aliases using Annotated and Depends(Provide[Container.service_name]).

  • Example:

    TodoServiceDep = Annotated[TodoService, Depends(Provide[Container.todo_service])]
    
    @router.get("/todos/")
    @inject
    async def list_todos(service: TodoServiceDep):
        ...
    

• No Direct Instantiation: Do not manually instantiate services or repositories; resolve them via the container.

---

2. FastAPI Route & Handler Best Practices

Use Annotated

Always prefer the Annotated style for parameter and dependency declarations.

from typing import Annotated
from fastapi import Path, Query

@router.get("/items/{item_id}")
async def read_item(
    item_id: Annotated[UUID, Path(description="The item ID")],
    q: Annotated[str | None, Query(max_length=50)] = None,
):
    ...

Return Types & response_model

• Specify explicit return type annotations (-> Model) for FastAPI validation, filtering, and serialization (running Pydantic's Rust-based serialization).
• If the returned object differs from the API response contract (e.g. returning a database model that needs filtering/serialization to a public schema), use response_model on the router decorator instead:

@router.get("/todos/{todo_id}", response_model=Todo)
async def get_todo(todo_id: UUID) -> Any:
    ...

No Ellipsis (...) for Required Fields

Do not use ... as a default value for required fields or query parameters.