Python Backend Development Standards

Architecture Overview

Router/Controller → Service → Repository → Database
      ↓                ↓            ↓
   Schemas         Business      SQLAlchemy
  (Pydantic)        Logic         Models

Layer Responsibilities

Naming Conventions

Files

• All lowercase with underscores: user_profile.py
• One entity per file
• Match filename to class: user.py → class User

Classes

• Models: User, BlogPost (PascalCase, singular)
• Schemas: UserCreate, UserResponse, UserUpdate
• Repositories: UserRepository
• Services: UserService

Database

• Table names: plural snake_case (users, blog_posts)
• Column names: snake_case (created_at, user_id)

Alembic Migrations

File Naming Convention

yyyymmdd_HHmm_<feature>.py

Examples:

• 20260117_0930_create_users_table.py
• 20260117_1045_add_email_to_users.py
• 20260117_1400_create_api_keys_table.py

Create Migration Command

# Generate with autogenerate
alembic revision --autogenerate -m "description"

# Then rename the file to follow convention:
# FROM: xxxx_description.py
# TO:   yyyymmdd_HHmm_description.py

Code Standards

Async Everything

• All database operations must be async
• Use async def for all handlers, services, repositories
• Use await for all I/O operations

Dependency Injection

• Use FastAPI Depends() for dependencies
• Inject database sessions into services
• Services inject repositories

Error Handling

• Use custom exceptions in app/core/exceptions.py
• Let FastAPI exception handlers convert to HTTP responses
• Never catch and swallow exceptions silently

Security

• Argon2id for password hashing
• Parameterized queries (SQLAlchemy ORM)
• Input validation (Pydantic)
• Rate limiting on auth endpoints

Reference Navigation

Core Patterns:

• python-models.md – SQLAlchemy ORM (User, ApiKey)
• python-schemas.md – Pydantic v2 patterns
• python-repositories.md – Repository pattern
• python-services.md – Service layer patterns
• python-api-design.md – FastAPI routes and controllers
• python-migrations.md – Alembic migration patterns
• python-utils.md – Utility functions (datetime, string, validation)

Security & Auth:

• python-authentication.md – JWT, API Keys, OAuth
• python-middleware.md – Dual auth, rate limiting, credits
• python-security.md – OWASP Top 10, input validation

Quality & Operations:

• python-testing.md – pytest patterns, fixtures
• python-performance.md – Caching, query optimization, async
• python-debugging.md – Logging, profiling, error tracking
• python-devops.md – Docker, CI/CD, deployment