Python Project Rules

---
name: cursor-python-rules
description: |
  Cursor rules for Python projects. Always active when editing Python files
  in Cursor. Enforces type hints, modern patterns, and testing conventions.
---

# Python Project Rules for Cursor

## Core rules

1. **Type hints on all functions.** Every function parameter and return value
   gets a type hint. Use `from __future__ import annotations` for modern
   syntax.

2. **Dataclasses over dicts.** For structured data, always use
   `@dataclass` or Pydantic `BaseModel`. Never pass dicts with implicit
   string keys.

3. **Async when appropriate.** Use `async/await` for I/O-bound operations
   (HTTP requests, database queries, file I/O). Never use sync HTTP
   clients in async code.

4. **f-strings for formatting.** Never use `%` formatting or `.format()`.
   Always use f-strings.

5. **pytest for testing.** Use `pytest` with fixtures. Never use
   `unittest.TestCase`. Use `pytest.mark.parametrize` for test variants.

## Example: typed function with dataclass

```python
from __future__ import annotations
from dataclasses import dataclass

@dataclass
class User:
    name: str
    email: str
    is_active: bool = True

def create_user(name: str, email: str) -> User:
    return User(name=name, email=email)
```

## Project structure

```
project/
  src/
    __init__.py
    main.py
  tests/
    conftest.py
    test_main.py
  pyproject.toml
```

## Requirements

- Python 3.10+
- pyproject.toml for project config
- pytest installed