.cursorrules (deprecated)

1# Modern Python 3.12+ — Cursor Rules
2# Production Python with type hints, dataclasses, modern patterns, and strict quality
3 
4# Project Context
5You are writing modern Python 3.12+. The project uses type hints throughout, leverages
6dataclasses and Pydantic for data modeling, follows PEP standards strictly, and uses
7modern Python features including match statements, type parameter syntax, and f-strings.
8 
9# Type Hints (Mandatory)
10- Type ALL function signatures: parameters and return values.
11- Use built-in generic types (Python 3.9+): `list[str]`, `dict[str, int]`, `tuple[int, ...]`.
12- DON'T: Import `List`, `Dict`, `Tuple`, `Set` from `typing` — use builtins.
13- Use the `|` union syntax (Python 3.10+): `str | None` instead of `Optional[str]`.
14- Use `type` statement for type aliases (Python 3.12+):
15```python
16  type UserId = int
17  type UserMap = dict[str, User]
18  type Callback[T] = Callable[[T], None]  # generic alias
19```
20- Use `Self` type (Python 3.11+) for methods returning the same class:
21```python
22  from typing import Self
23  class Builder:
24      def set_name(self, name: str) -> Self:
25          self.name = name
26          return self
27```
28- Use `TypeGuard` for type-narrowing functions:
29```python
30  def is_valid_user(data: dict) -> TypeGuard[UserDict]:
31      return 'id' in data and 'email' in data
32```
33 
34# Dataclass Patterns
35- Use `@dataclass` for data containers. Use `@dataclass(frozen=True)` for immutables.
36- Use `@dataclass(slots=True)` for better memory and attribute access performance.
37- Use `field(default_factory=list)` for mutable defaults — never `field(default=[])`.
38- Use `__post_init__` for validation:
39```python
40  @dataclass(frozen=True, slots=True)
41  class Temperature:
42      celsius: float
43      def __post_init__(self) -> None:
44          if self.celsius < -273.15:
45              raise ValueError("Temperature below absolute zero")
46```
47- Use `kw_only=True` (Python 3.10+) when fields are numerous to force keyword arguments.
48 
49# Match Statements (Structural Pattern Matching)
50- Use `match` statements for complex conditional logic with destructuring:
51```python
52  match command:
53      case {"action": "create", "data": data}:
54          return create_item(data)
55      case {"action": "delete", "id": int(item_id)}:
56          return delete_item(item_id)
57      case {"action": str(action)}:
58          raise ValueError(f"Unknown action: {action}")
59      case _:
60          raise TypeError("Invalid command format")
61```
62- Prefer match over long if/elif chains when checking structure or type.
63- Use guard clauses with `if`: `case Point(x, y) if x > 0 and y > 0:`.
64 
65# Exception Handling
66- Use exception groups (Python 3.11+) for concurrent error handling:
67```python
68  try:
69      results = await asyncio.gather(*tasks, return_exceptions=True)
70  except* ValueError as eg:
71      handle_value_errors(eg.exceptions)
72  except* ConnectionError as eg:
73      handle_connection_errors(eg.exceptions)
74```
75- Create custom exception hierarchies with `__init__` typing:
76```python
77  class AppError(Exception):
78      def __init__(self, message: str, code: str, *, context: dict | None = None) -> None:
79          super().__init__(message)
80          self.code = code
81          self.context = context or {}
82```
83- Use `raise ... from e` to chain exceptions and preserve context.
84- DON'T: Catch bare `Exception` — catch specific exceptions.
85- DON'T: Use `except: pass` — always handle or log the error.
86 
87# Async Patterns
88- Use `async`/`await` for all I/O-bound operations.
89- Use `asyncio.TaskGroup` (Python 3.11+) for structured concurrency:
90```python
91  async with asyncio.TaskGroup() as tg:
92      task1 = tg.create_task(fetch_users())
93      task2 = tg.create_task(fetch_products())
94  users = task1.result()
95  products = task2.result()
96```
97- Use `asyncio.timeout()` (Python 3.11+) instead of `asyncio.wait_for`:
98```python
99  async with asyncio.timeout(10):
100      data = await slow_operation()
101```
102- DON'T: Mix sync and async code without `asyncio.to_thread()`.
103- DON'T: Use `asyncio.gather()` without handling individual task exceptions.
104 
105# String Formatting
106- Always use f-strings for string interpolation. Never use `%` formatting or `.format()`.
107- Use `=` in f-strings for debugging: `f"{variable=}"` prints `variable=value`.
108- For multi-line strings, use dedented triple-quoted f-strings.
109- DON'T: Concatenate strings with `+` in loops — use `"".join()`.
110 
111# Comprehensions and Generators
112- Use list/dict/set comprehensions for simple transformations.
113- Use generator expressions for large sequences to save memory:
114```python
115  total = sum(item.price for item in items if item.in_stock)
116```
117- DON'T: Nest more than 2 levels of comprehensions — use a for loop instead.
118- Use `itertools` for complex iteration patterns (chain, islice, groupby, product).
119 
120# File and Path Operations
121- Use `pathlib.Path` exclusively — never `os.path`:
122```python
123  config_path = Path(__file__).parent / "config" / "settings.json"
124  content = config_path.read_text(encoding="utf-8")
125```
126- Use context managers for file operations: `with open(...) as f:`.
127- Always specify encoding: `encoding="utf-8"`.
128 
129# Project Standards
130- Use `ruff` for linting and formatting (replaces black, isort, flake8).
131- Use `mypy` with strict mode for type checking.
132- Use `pytest` for testing with `pytest-cov` for coverage.
133- Use `pyproject.toml` for all project configuration (not setup.py/setup.cfg).
134- Structure imports: stdlib, third-party, local (ruff handles this).
135 
136# Naming Conventions
137- Variables and functions: `snake_case`
138- Classes: `PascalCase`
139- Constants: `UPPER_SNAKE_CASE`
140- Private members: `_single_leading_underscore`
141- Module-level dunder: `__all__`, `__version__`
142- Type aliases: `PascalCase` (they represent types)
143- Boolean variables: `is_`, `has_`, `should_`, `can_` prefix
144 
145# Testing
146- Use `pytest` with fixtures, parametrize, and markers.
147- Type test fixtures and use factories for test data.
148- Use `pytest.raises` with `match` parameter for exception testing:
149```python
150  with pytest.raises(ValueError, match="Temperature below"):
151      Temperature(celsius=-300)
152```
153- Use `tmp_path` fixture for file system tests.
154- Use `monkeypatch` for environment variables and module-level patches.
155- Aim for: business logic 95%+, utilities 100%, integration 80%+.
156 
157# Common Mistakes to Avoid
158- DON'T: Use mutable default arguments: `def f(items: list = [])` — use `None` and create inside.
159- DON'T: Use `type()` for type checking — use `isinstance()`.
160- DON'T: Use `is` to compare values — use `==`. (`is` compares identity, not equality.)
161- DON'T: Import with wildcard: `from module import *`.
162- DON'T: Use global variables for state — pass dependencies explicitly.
163- DON'T: Ignore `mypy` errors with `# type: ignore` without a specific error code.
164- DON'T: Use `dict.keys()` in membership tests — just use `key in dict`.
165