/python-patterns

name: python-patterns
description: "Python backend patterns: layered architecture, async I/O, dependency injection, repository/service separation. TRIGGER when: creating routes, models, schemas, or services in a Python backend. SKIP: REST contract design (use api-design); schema/index tuning (use database-optimization). (Examples: FastAPI + SQLAlchemy + Pydantic.)"

Python Backend Patterns Skill

Purpose

Best practices for Python backend development: layered architecture, async I/O, dependency injection, and clear separation between HTTP handling, business logic, and data access. The concrete examples below use FastAPI, SQLAlchemy, and Pydantic, but the patterns apply to any Python web framework, ORM, and validation library.

Auto-Invoke Triggers

• Creating backend routes / endpoints
• Working with ORM models
• Implementing async operations
• Creating request/response validation schemas

---

Layer Responsibilities

| Layer | Responsibility | |-------|----------------| | **Endpoints** | HTTP handling, request/response | | **Services** | Business logic, orchestration | | **Repositories** | Data access, queries | | **Models** | Database schema | | **Schemas** | Data validation, serialization |

These layers are framework-agnostic — keep HTTP concerns, business rules, and data access in separate modules regardless of which framework/ORM you use.

---

Example: FastAPI + SQLAlchemy + Pydantic (illustrative)

> Illustrative — this is one concrete stack shown as an example. Substitute your > framework's equivalents (any ASGI/WSGI framework, ORM, and validation library). > The layering and separation-of-concerns patterns above are the reusable part.

Project Structure

app/
└── backend/
    ├── app/
    │   ├── main.py              # FastAPI app initialization
    │   ├── config.py            # Settings (pydantic-settings)
    │   ├── api/v1/endpoints/    # Route handlers
    │   ├── core/                # Security, exceptions
    │   ├── models/              # SQLAlchemy models
    │   ├── schemas/             # Pydantic schemas
    │   ├── services/            # Business logic
    │   ├── repositories/        # Data access
    │   └── db/session.py        # Database session
    ├── tests/
    ├── alembic.ini
    └── requirements.txt

---

Async Database Patterns

Session Management

• Use `async_sessionmaker` for async sessions
• Use dependency injection for session
• Commit in dependency, rollback on exception
• Use `expire_on_commit=False` for response data

Query Patterns

• Use `select()` statements (SQLAlchemy 2.0 style)
• Prefer `scalar_one_or_none()` for single items
• Use `scalars().all()` for lists
• Eager load relationships with `selectin` or `joinedload`

---

Pydantic Schema Patterns

Schema Types

| Type | Purpose | Example | |------|---------|---------| | Base | Shared fields | `UserBase(email, username)` | | Create | POST request | `UserCreate(Base + password)` | | Update | PATCH request | `UserUpdate(all optional)` | | Response | API response | `UserResponse(Base + id, created_at)` | | InDB | Internal with secrets | `UserInDB(Response + hashed_password)` |

Best Practices

• Use `model_config = ConfigDict(from_attributes=True)` for ORM
• Use `Field()` for validation constraints
• Use `field_validator` for custom validation
• Separate request and response schemas

---

Repository Pattern

Base Repository Methods

• `get_by_id(id)` - Single item by primary key
• `get_all(skip, limit)` - Paginated list
• `create(**kwargs)` - Insert new record
• `update(id, **kwargs)` - Update existing
• `delete(id)` - Remove record

Specific Repositories

• Extend base with domain-specific queries
• Example: `get_by_email()`, `get_active_users()`

---

Service Layer

Responsibilities

• Validate business rules
• Coordinate multiple repositories
• Transform data between layers
• Raise domain exceptions

Pattern

• Inject repository via constructor
• Return Pydantic schemas, not models
• Raise specific exceptions (NotFoundError, ConflictError)

---

Dependency Injection

Common Dependencies

• `get_db` - Database session
• `get_current_user` - Authenticated user
• `get_current_superuser` - Admin user
• Service factories - `get_user_service(session)`

Pattern

# Endpoint receives dependencies, passes to service
async def create_user(
    data: UserCreate,
    session: AsyncSession = Depends(get_db)
):
    service = UserService(session)
    return await service.create(data)

---

Configuration

Settings Class

• Use `pydantic-settings` for env loading
• Use `@lru_cache` for singleton
• Define defaults for optional settings
• Use `@property` for computed values

Environment Variables

• `DATABASE_URL` - Database connection
• `SECRET_KEY` - JWT signing
• `DEBUG` - Development mode
• `CORS_ORIGINS` - Allowed origins

---

Testing Patterns

Fixtures

• `db_session` - In-memory SQLite session
• `client` - AsyncClient with app
• Override `get_db` dependency for tests

Test Structure

• One test file per module
• Use `pytest.mark.asyncio` for async tests
• AAA pattern: Arrange, Act, Assert
• Mock external services

---

Best Practices

DO

• Use async/await consistently
• Use type hints everywhere
• Use Pydantic for all validation
• Use dependency injection
• Use repository pattern for data access
• Separate business logic into services

DON'T

• Mix sync and async database calls
• Put business logic in routes
• Use raw SQL without parameters
• Catch generic Exception
• Store secrets in code
• Skip server-side validation

---

Code Quality

| Tool | Purpose | |------|---------| | black | Code formatting | | ruff | Linting | | mypy | Type checking | | pytest | Testing | | pytest-cov | Coverage |