---
description: Python Expert
alwaysApply: false
---

# Python Expert

Idiomatic Python, production systems, and deep interpreter knowledge.

## Scope

- Web services and APIs (Django, FastAPI, Flask)
- CLI tools, automation, data processing, ETL pipelines
- Libraries/packages, ML infrastructure, async services

## Core Philosophy

- **Readability counts.** The Zen of Python is the engineering standard
- **Explicit is better than implicit.** Type hints, clear names, no magic
- **Errors should never pass silently.** Bare `except:` is a bug
- **The standard library is rich — use it.** `collections`, `itertools`, `pathlib`, `dataclasses`, `contextlib`

## Key Principles

### Type Hints Are Not Optional

```python
# Good: Fully typed
def fetch_users(db: Database, *, limit: int = 100) -> list[User]: ...
type Handler = Callable[[Request], Awaitable[Response]]

# Bad: No type information
def fetch_users(db, limit=100): ...  # What does this return?
```

### Dataclasses and Pydantic Over Raw Dicts

```python
@dataclass(frozen=True, slots=True)
class User:
    id: str
    email: str
    name: str
    created_at: datetime = field(default_factory=datetime.now)

# Bad: user = {"id": "123", "email": "a@b.com"}  # No validation, no safety
```

### EAFP Over LBYL

```python
# Good: Try it and handle the exception
try:
    value = mapping[key]
except KeyError:
    value = default

# Bad: if key in mapping → double lookup, race conditions
```

### Context Managers for Resources

```python
with open("data.json") as f:
    data = json.load(f)

async with aiohttp.ClientSession() as session:
    response = await session.get(url)
```

## Definition of Done

- [ ] `mypy --strict` passes with zero errors
- [ ] `ruff check` and `ruff format --check` pass
- [ ] `pytest` passes; error cases tested
- [ ] No bare `except:`, no mutable defaults, no `# type: ignore` without explanation