# CLAUDE.md

Instructions for Claude Code when working on this repository.

## Project Overview

`mail_connector` is a Python mail connector library (published as `mes-courriels`).
MIT license. Early stage (v0.0.1). Provides a read-only Gmail connector via OAuth2.

## Tech Stack

- **Python** >= 3.12 (pinned in `.python-version`)
- **uv** for package management and virtual environments
- **hatchling** as the build backend
- **src layout**: package code lives in `src/mail_connector/`
- PEP 561 typed package (`py.typed` marker present)

## Common Commands

```bash
uv sync                              # Install dependencies
uv build                             # Build the package
uv run python -m mail_connector      # Run as module
uv add <package>                     # Add a dependency
uv add --dev <package>               # Add a dev dependency
```

No test runner or linter is configured yet. When added, expect `uv run pytest` and `uv run ruff check .`.

## Testing

- **Always run tests via `uv run`** (e.g. `uv run pytest`). Never run `pytest` directly.
- **No mocks**: write real unit tests and end-to-end tests against actual services/data. Do not use `unittest.mock`, `MagicMock`, or `patch`.
- **Every new feature must have an E2E test**. Tests must be implemented and passing (`uv run pytest`) before any commit/push.
- **Commit and push frequently** — small, focused commits after each logical change.

## Architecture

```
src/mail_connector/
├── __init__.py    # Package root, exports __version__ and GmailConnector
├── gmail.py       # GmailConnector class (read-only Gmail via OAuth2)
└── py.typed       # PEP 561 marker
```

## Conventions

- Version is declared in both `pyproject.toml` and `src/mail_connector/__init__.py` — keep them in sync.
- `uv.lock` is gitignored; not committed.
- OAuth2 credentials are loaded from `.env` (see `.env.example`).

---

## Behavioral Guidelines (Karpathy)

Reduce common LLM coding mistakes. Bias toward caution over speed. For trivial tasks, use judgment.

### 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

### 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

### 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it — don't delete it.
- Remove imports/variables/functions that YOUR changes made unused.

### 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

---

## Python Style Guide (Bobain's Crew)

Based on PEP 8 with team-specific modifications.

### Line Length

Maximum 120 characters. Strictly enforced for docstrings and comments. Code may occasionally exceed when Black formatter would allow it.

### Indentation

4 spaces per indentation level.

### Imports

- **Group**: stdlib → third-party → local. Sorted alphabetically within groups.
- **Absolute imports** only.
- **Remove unused imports**.

### Naming

| Element    | Convention  | Example              |
|-----------|-------------|----------------------|
| Variables | snake_case  | `user_name`          |
| Constants | UPPER_CASE  | `MAX_VALUE`          |
| Functions | snake_case  | `calculate_total()`  |
| Classes   | CamelCase   | `UserManager`        |
| Modules   | snake_case  | `user_utils`         |

### Docstrings

Google style. Triple double quotes. First line: concise summary.

```python
def my_function(param1: int, param2: str) -> bool:
    """Single-line summary.

    More detailed description, if necessary.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        True for success, False otherwise.

    Raises:
        ValueError: If param2 is invalid.
    """
```

### Type Hints

Use type hints. Follow PEP 484.

### Comments

Explain the "why", not the "what". Comment sparingly. Well-written code should be self-documenting.

### Logging

Use the built-in `logging` module. Log at appropriate levels. Provide context in log messages.

### Error Handling

- Use specific exceptions when possible.
- Handle exceptions gracefully with informative messages.
- Do not over-engineer: the code is not mature enough to catch every specific exception.

### Misc

- Remove unused variables.
- Consider all code in the repo when making a change: try not to break anything.
