Index of every page on this site: llms.txt
All skills
suleyman avatar

/python-fastapi

@920a44a
Run it yourself

Opinionated rules for production Python APIs built with FastAPI, Pydantic v2, SQLAlchemy 2.0 (async), Alembic, and PostgreSQL, including JWT/OAuth authentication, authorization, error handling, pagination, background jobs, and testing. Use when creating or reviewing FastAPI endpoints, request/response schemas, services, database access, dependencies, auth, settings, workers, or API tests, or when debugging slow or failing API requests.

Use this Skill: https://skilld.dev/gh/suleyman/fullstack-agent-skills/python-fastapi

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesproject-skeleton.md

≈3.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Project skeleton

Reference implementations of the app/core modules, the app factory, and test fixtures. Copy what you need and adapt the names.

app/core/config.py

from functools import lru_cache
from typing import Literal

from pydantic import PostgresDsn, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

    environment: Literal["local", "test", "staging", "production"] = "local"
    database_url: PostgresDsn                      # postgresql+asyncpg://...
    jwt_issuer: str
    jwt_audience: str
    jwt_public_key: SecretStr                      # PEM, verifies access tokens
    jwt_private_key: SecretStr | None = None       # only on the service that issues tokens
    cors_origins: list[str] = []                   # empty when only servers call the API

    @property
    def is_production(self) -> bool:
        return self.environment == "production"


@lru_cache
def get_settings() -> Settings:
    return Settings()  # raises ValidationError at startup if anything is missing

app/core/db.py

from collections.abc import AsyncIterator
from datetime import datetime
from typing import Annotated

from fastapi import Depends
from sqlalchemy import DateTime, MetaData
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase

from app.core.config import get_settings

NAMING_CONVENTION = {
    "ix": "ix_%(column_0_label)s",
    "uq": "uq_%(table_name)s_%(column_0_name)s",
    "ck": "ck_%(table_name)s_%(constraint_name)s",
    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
    "pk": "pk_%(table_name)s",
}


class Base(DeclarativeBase):
    metadata = MetaData(naming_convention=NAMING_CONVENTION)  # deterministic constraint names
    type_annotation_map = {datetime: DateTime(timezone=True)}  # Mapped[datetime] -> timestamptz


engine = create_async_engine(
    str(get_settings().database_url),
    pool_size=10,
    max_overflow=5,
    pool_pre_ping=True,
    pool_recycle=1800,
)
# statement_timeout / idle_in_transaction_session_timeout are set on the DB role, not here,
# so they also apply behind PgBouncer.

SessionLocal = async_sessionmaker(engine, expire_on_commit=False)


async def get_session() -> AsyncIterator[AsyncSession]:
    async with SessionLocal() as session:
        yield session  # closing the session rolls back anything uncommitted


SessionDep = Annotated[AsyncSession, Depends(get_session)]

app/core/ids.py

import uuid


def new_id() -> uuid.UUID:
    """Time-ordered UUIDv7: good index locality, not enumerable."""
    return uuid.uuid7()  # Python 3.14+. On older versions use the `uuid-utils` package.

app/core/schemas.py

from typing import Generic, TypeVar

from pydantic import BaseModel, ConfigDict
from pydantic.alias_generators import to_camel

T = TypeVar("T")


class APISchema(BaseModel):
    """Base for every request/response schema: camelCase on the wire, snake_case in Python."""

    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True, from_attributes=True)


class Page(APISchema, Generic[T]):
    items: list[T]
    next_cursor: str | None

app/core/pagination.py

import base64
import json
from datetime import datetime
from uuid import UUID

from app.core.errors import BadRequest


def encode_cursor(created_at: datetime, row_id: UUID) -> str:
    raw = json.dumps([created_at.isoformat(), str(row_id)]).encode()
    return base64.urlsafe_b64encode(raw).decode().rstrip("=")


def decode_cursor(cursor: str) -> tuple[datetime, UUID]:
    try:
        raw = base64.urlsafe_b64decode(cursor + "=" * (-len(cursor) % 4))
        created_at, row_id = json.loads(raw)
        return datetime.fromisoformat(created_at), UUID(row_id)
    except (ValueError, TypeError) as exc:
        raise BadRequest(code="invalid_cursor", detail="The pagination cursor is invalid.") from exc

The cursor keeps full microsecond precision. A client that built cursors from displayed timestamps would lose precision (JavaScript Date keeps only milliseconds) and skip or repeat rows. That's why cursors are opaque.

app/core/errors.py

import logging

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

logger = logging.getLogger(__name__)


class DomainError(Exception):
    status_code = 400
    code = "bad_request"
    title = "Bad request"

    def __init__(self, detail: str | None = None, *, code: str | None = None) -> None:
        super().__init__(detail or self.title)
        self.detail = detail
        if code:
            self.code = code


class BadRequest(DomainError): ...

class NotAuthenticated(DomainError):
    status_code, code, title = 401, "not_authenticated", "Authentication required"

class PermissionDenied(DomainError):
    status_code, code, title = 403, "permission_denied", "Permission denied"

class NotFound(DomainError):
    status_code, code, title = 404, "not_found", "Resource not found"

class Conflict(DomainError):
    status_code, code, title = 409, "conflict", "Conflict"


def problem(request: Request, *, status: int, code: str, title: str,
            detail: str | None = None, errors: list[dict] | None = None) -> JSONResponse:
    body = {
        "type": f"https://api.example.com/problems/{code}",
        "title": title,
        "status": status,
        "code": code,
        "detail": detail,
        "requestId": getattr(request.state, "request_id", None),
    }
    if errors:
        body["errors"] = errors
    headers = {"WWW-Authenticate": "Bearer"} if status == 401 else None
    return JSONResponse(body, status_code=status, media_type="application/problem+json", headers=headers)


def register_error_handlers(app: FastAPI) -> None:
    @app.exception_handler(DomainError)
    async def _domain(request: Request, exc: DomainError) -> JSONResponse:
        return problem(request, status=exc.status_code, code=exc.code, title=exc.title, detail=exc.detail)

    @app.exception_handler(RequestValidationError)
    async def _validation(request: Request, exc: RequestValidationError) -> JSONResponse:
        errors = [
            {"field": ".".join(str(p) for p in err["loc"][1:]), "code": err["type"], "message": err["msg"]}
            for err in exc.errors()
        ]
        return problem(request, status=422, code="validation_failed", title="Request validation failed", errors=errors)

    @app.exception_handler(Exception)
    async def _unhandled(request: Request, exc: Exception) -> JSONResponse:
        logger.exception("unhandled_error")
        return problem(request, status=500, code="internal_error", title="Internal server error")

app/auth/dependencies.py

from typing import Annotated
from uuid import UUID

import jwt
from fastapi import Depends
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer

from app.core.config import get_settings
from app.core.db import SessionDep
from app.core.errors import NotAuthenticated, PermissionDenied
from app.users.models import Role, User

bearer = HTTPBearer(auto_error=False)


def decode_access_token(token: str) -> dict:
    settings = get_settings()
    return jwt.decode(
        token,
        settings.jwt_public_key.get_secret_value(),
        algorithms=["ES256"],                    # pinned; never trust the token's own alg
        audience=settings.jwt_audience,
        issuer=settings.jwt_issuer,
        options={"require": ["exp", "iat", "sub"]},
        leeway=30,
    )


async def get_current_user(
    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(bearer)],
    session: SessionDep,
) -> User:
    if credentials is None:
        raise NotAuthenticated()
    try:
        claims = decode_access_token(credentials.credentials)
        user_id = UUID(claims["sub"])
    except (jwt.InvalidTokenError, ValueError) as exc:
        raise NotAuthenticated() from exc
    user = await session.get(User, user_id)
    if user is None or user.disabled_at is not None:
        raise NotAuthenticated()
    return user


CurrentUser = Annotated[User, Depends(get_current_user)]


def require_role(minimum: Role):
    async def dependency(user: CurrentUser) -> User:
        if not user.role.at_least(minimum):
            raise PermissionDenied()
        return user

    return dependency

app/main.py

import re
import uuid
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

import httpx
from fastapi import Depends, FastAPI, Request

from app.admin.router import router as admin_router
from app.auth.dependencies import get_current_user
from app.core.config import get_settings
from app.core.db import engine
from app.core.errors import register_error_handlers
from app.orders.router import organizer_router, router as orders_router
from app.public.router import router as public_router

REQUEST_ID = re.compile(r"^[A-Za-z0-9._-]{8,64}$")


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    app.state.http = httpx.AsyncClient(timeout=httpx.Timeout(10.0, connect=3.0))
    yield
    await app.state.http.aclose()
    await engine.dispose()


def create_app() -> FastAPI:
    settings = get_settings()
    app = FastAPI(
        title="Example API",
        lifespan=lifespan,
        docs_url=None if settings.is_production else "/docs",
        redoc_url=None,
        openapi_url=None if settings.is_production else "/openapi.json",
    )
    register_error_handlers(app)

    @app.middleware("http")
    async def request_id(request: Request, call_next):
        incoming = request.headers.get("x-request-id", "")
        rid = incoming if REQUEST_ID.match(incoming) else uuid.uuid4().hex  # don't log arbitrary input
        request.state.request_id = rid
        response = await call_next(request)
        response.headers["x-request-id"] = rid
        return response

    authenticated = [Depends(get_current_user)]
    app.include_router(public_router, prefix="/v1")
    app.include_router(orders_router, prefix="/v1", dependencies=authenticated)
    app.include_router(organizer_router, prefix="/v1", dependencies=authenticated)
    app.include_router(admin_router, prefix="/v1")  # router itself requires a staff role
    return app


app = create_app()

Bind request_id into your logger's context (for example structlog.contextvars), so every log line carries it. The asgi-correlation-id package is a pure-ASGI alternative to the http middleware above.

Tests: tests/conftest.py

import os

import pytest
from alembic import command
from alembic.config import Config
from httpx import ASGITransport, AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine

from app.auth.dependencies import get_current_user
from app.core.db import get_session
from app.main import create_app

TEST_DATABASE_URL = os.environ["TEST_DATABASE_URL"]  # a disposable PostGIS database


@pytest.fixture(scope="session")
def anyio_backend() -> str:
    return "asyncio"


@pytest.fixture(scope="session")
def migrated_database() -> str:
    # Sync fixture: Alembic's async env.py calls asyncio.run(), which can't run inside the test loop.
    cfg = Config("alembic.ini")
    cfg.set_main_option("sqlalchemy.url", TEST_DATABASE_URL)
    command.upgrade(cfg, "head")
    return TEST_DATABASE_URL


@pytest.fixture(scope="session")
async def engine(migrated_database: str):
    engine = create_async_engine(migrated_database)
    yield engine
    await engine.dispose()


@pytest.fixture
async def session(engine):
    async with engine.connect() as connection:
        transaction = await connection.begin()
        session = AsyncSession(
            bind=connection,
            expire_on_commit=False,
            join_transaction_mode="create_savepoint",  # service commits become savepoint releases
        )
        try:
            yield session
        finally:
            await session.close()
            await transaction.rollback()  # every test starts from a clean database


@pytest.fixture
async def client_for(session):
    """client_for(user) -> AsyncClient authenticated as `user`; client_for(None) -> anonymous."""
    clients: list[AsyncClient] = []

    async def shared_session():
        # Mirror production: get_session closes the session on errors, which rolls back a failed
        # request's partial writes. Without this, they would leak into later requests in the test.
        try:
            yield session
        except Exception:
            await session.rollback()  # rolls back to the savepoint, keeping earlier committed requests
            raise

    def make(user):
        app = create_app()
        app.dependency_overrides[get_session] = shared_session
        if user is not None:
            app.dependency_overrides[get_current_user] = lambda: user
        client = AsyncClient(transport=ASGITransport(app=app), base_url="http://test")
        clients.append(client)
        return client

    yield make
    for client in clients:
        await client.aclose()

Note: inside one test, every row created gets the same now() value (the transaction start time). Pagination tests therefore exercise the id tie-breaker, which is a feature, not a bug.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill provides a set of high-quality, security-conscious development patterns and reference implementations for building production-ready FastAPI applications. It emphasizes standard industry best practices such as strict input validation, secure authentication using JWT, and object-level authorization.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at 920a44a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 2 months ago
metadata
{
  "author": "suleyman",
  "version": "1.0.0"
}

README badge

README badge for suleyman/fullstack-agent-skills/python-fastapi