# Python Patterns & Preferences

## Package Management
- Always use `uv` for package and environment management
- Never use pip directly; prefer `uv pip`, `uv sync`, `uv run`

## Linting & Formatting
- Use **Ruff** for linting and **Black** for formatting
- Include both as dev dependencies in new projects (`uv add --dev ruff black`)

## Code Style
- Utilize dependency injection pattern whenever possible
- Never add lazy imports to the middle of a file — all imports at the top

## FastAPI / Backend Services
Use **Ports & Adapters (Hexagonal Architecture)** to cleanly separate concerns:

```
project/
  domain/           # Pure business logic, no framework imports
    models.py       # Domain entities / value objects
    services.py     # Use cases / business rules
    ports.py        # Abstract interfaces (ABC) for external dependencies
  adapters/
    inbound/        # FastAPI routers, CLI handlers — drive the domain
    outbound/       # Database repos, API clients — implement domain ports
  config/           # App wiring, dependency injection, settings
  main.py           # FastAPI app creation, adapter registration
```

### Key rules
- **Domain layer has zero framework imports** — no FastAPI, SQLAlchemy, httpx, etc.
- **Ports** are abstract base classes in the domain that define what the domain *needs* (e.g., `UserRepository(ABC)`)
- **Outbound adapters** implement ports (e.g., `PostgresUserRepository(UserRepository)`)
- **Inbound adapters** (routers) depend on domain services, never on outbound adapters directly
- **Dependency injection** wires adapters to ports at startup in `config/` or `main.py`
- **Tests** can swap outbound adapters for in-memory fakes by implementing the same port
- Models passed across boundaries should be domain models or DTOs — never ORM models in router responses