pn-python-scaffolding

Python backend scaffolding

When to use

• Starting a new Python API project (FastAPI, Flask, Django).
• Adding a new route, router, or domain module.
• Establishing project structure and config patterns from scratch.

Project structure

# FastAPI — domain-driven layout (preferred)
src/
  users/
    router.py         # APIRouter with route definitions
    service.py        # Business logic
    schemas.py        # Pydantic request/response models
    models.py         # SQLAlchemy ORM models (if used)
  orders/
    router.py
    service.py
    schemas.py
  core/
    config.py         # Settings via pydantic-settings
    database.py       # Async DB engine + session factory
    errors.py         # AppError class and exception handlers
    security.py       # Auth helpers (JWT decode, password hash)
  main.py             # FastAPI app factory, router registration

pyproject.toml        # Dependencies + project metadata (preferred over requirements.txt)
.env.example          # Required environment variables with placeholders

FastAPI scaffold

# src/users/schemas.py
from pydantic import BaseModel, EmailStr, field_validator

class CreateUserRequest(BaseModel):
    email: EmailStr
    name: str
    role: str = "user"

    @field_validator("name")
    @classmethod
    def name_not_empty(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Name cannot be empty")
        return v.strip()

class UserResponse(BaseModel):
    id: int
    email: str
    name: str
    role: str

    model_config = {"from_attributes": True}  # allow ORM model input

# src/users/router.py
from fastapi import APIRouter, Depends, HTTPException, status
from .schemas import CreateUserRequest, UserResponse
from .service import create_user, get_user_by_id
from ..core.security import get_current_user

router = APIRouter(prefix="/users", tags=["users"])

@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
async def create_user_route(
    body: CreateUserRequest,
    current_user=Depends(get_current_user),
) -> UserResponse:
    return await create_user(body)

@router.get("/{user_id}", response_model=UserResponse)
async def get_user_route(
    user_id: int,
    current_user=Depends(get_current_user),
) -> UserResponse:
    user = await get_user_by_id(user_id, requester_id=current_user.id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user