architecting-python

Python Code Architecture

Core Philosophy: Functional Core, Imperative Shell

Separate code into two distinct layers:

Functional Core (Business Logic)

• Pure functions: values in, values out
• Many conditionals, complex logic
• Zero external dependencies (no I/O, no databases, no APIs)
• Naturally isolated and testable without mocks

Imperative Shell (External World)

• Few conditionals, simple coordination
• All external dependencies live here
• Orchestrates functional core components
• Integration tested, not unit tested

Project Structure

project/
├── handlers/        # Ports (HTTP, CLI, GraphQL)
├── infrastructure/  # Adapters (DB, email, external APIs)
└── domain/          # Functional core (business logic)

Pydantic Patterns

Value Objects (Immutable)

from pydantic import BaseModel, Field

class Event(BaseModel, frozen=True):
    """Immutable value object with validation."""
    id: str | None = None
    name: str = Field(min_length=1, max_length=100)
    start_time: datetime
    max_attendees: int | None = Field(default=None, ge=1)

Request/Response Models

class CreateEventRequest(BaseModel):
    """HTTP/CLI input validation."""
    name: str = Field(min_length=1, max_length=100)
    start_time: datetime

    def to_domain(self) -> Event:
        return Event(name=self.name, start_time=self.start_time)

Infrastructure Patterns

Dictionary-Style Storage

from collections.abc import MutableMapping

class InMemoryEvents(MutableMapping[str, Event]):
    def __init__(self) -> None:
        self._data: dict[str, Event] = {}

    def __getitem__(self, key: str) -> Event:
        return self._data[key]

    def __setitem__(self, key: str, value: Event) -> None:
        self._data[key] = value

    # ... implement other MutableMapping methods

Protocol-Based Services

from typing import Protocol

class EmailService(Protocol):
    def send(self, to: str, subject: str, body: str) -> None: ...

Handler Pattern (Thin Adapters)

Handlers only:

• Transform input (request → domain objects)
• Call domain logic
• Transform output (domain objects → response)

No business logic in handlers.

@app.post("/events")
async def create_event(
    request: CreateEventRequest,
    app: EventApplication = Depends(get_app)
) -> dict[str, str]:
    event_id = app.create_event(
        name=request.name,
        start_time=request.start_time
    )
    return {"event_id": event_id}

Hexagonal Architecture Summary

Handlers (Ports)  →  Domain (Core)  ←  Infrastructure (Adapters)
     ↓                    ↓                      ↓
  HTTP/CLI          Pure functions          Database/APIs
  Transform I/O     Business logic          External systems

Type Safety

• Modern typing: list[str] not List[str], str | None not Optional[str]
• Return type annotations required on all functions (including -> None)
• Imports at top of file - never inline imports
• Annotate self/cls in methods where type information is relevant

Dependencies

• uv for dependency management
• Pin dependencies with version ranges in pyproject.toml

Error Handling

• Explicit error types - use custom exceptions for domain errors
• Fail fast with clear error messages
• Handle errors at boundaries - not scattered throughout code
• Push error handling to appropriate layers (handlers catch, domain raises)

Documentation

• AsciiDoc preferred for comprehensive docs, Markdown acceptable
• Comments explain WHY, not WHAT
• Self-documenting code with good names
• No unnecessary comments on obvious code

Code Quality

• Good names - clear, descriptive, no abbreviations
• No over-engineering - only what's needed for current requirements
• Delete unused code - no backwards-compatibility hacks
• Pythonic patterns - context managers, properties, magic methods

Anti-Patterns to Avoid

• Business logic in handlers
• Direct database calls from domain
• Mocking in unit tests (indicates wrong boundaries)
• Repository pattern for simple storage (use dict-style)
• Inheritance hierarchies for services (use protocols)
• Inline imports
• Missing return type annotations