Cursor rule

1---
2description: Python
3globs: **/*.py
4alwaysApply: false
5---
6## Python
7 
8 
9When writing Python:
10 
11* Assume the latest python, version 3.13.
12* Prefer Pathlib methods (including read and write methods, like `read_text`) over `os.path`, `open`, `write`, etc.
13* Prefer docstr to multi-line comments at the top of a function or file.
14* If a docstr does not span multiple lines, do not use triple-quoted strings.
15* Do not create `__init__` files unless specifically instructed
16* Use Pydantic models over dataclass or a typed dict.
17* Use SQLAlchemy for generating any SQL queries.
18* Use `click` for command line argument parsing.
19* Use `log.info("the message", the_variable=the_variable)` instead of `log.info("The message: %s", the_variable)` or `print` for logging. This object can be found at `from app import log`.
20  * Log messages should be lowercase with no leading or trailing whitespace.
21  * No variable interpolation in log messages.
22  * Do not coerce database IDs, dates, or Path objects to `str`
23* Do not fix import ordering or other linting issues.
24* Never edit or create any files in `migrations/versions/`
25* Place all comments on dedicated lines immediately above the code statements they describe. Avoid inline comments appended to the end of code lines.
26* Do not `try/catch` raw `Exceptions` unless explicitly told to. Prefer to let exceptions raise and cause an explicit error.
27* Always make an explicit copy before mutating a dictionary that you did not create in the current narrow scope.
28* Never use `from __future__`
29* Always use `re.compile(pattern, re.VERBOSE)` and inline `#` comments to document the logic of each capture group or condition in any complex regular expression.
30* **IMPORTANT** never edit app/generated/ files. These are autogenerated.
31 
32### Package Management
33 
34- Use `uv add` to add python packages. No need for `pip compile`, `pip install`, etc.
35 
36### Typing
37 
38* Assume the latest pyright version
39* Prefer modern typing: `list[str]` over `List[str]`, `dict[str, int]` over `Dict[str, int]`, etc.
40* Prefer to keep typing errors in place than eliminate type specificity:
41  * Do not add ignore comments such as `# type: ignore`
42  * Never add an `Any` type.
43  * Do not `cast(object, ...)`
44 
45### Data Manipulation
46 
47* Prefer `funcy` utilities to complex list comprehensions or repetitive python statements.
48* `import funcy as f` and `import funcy_pipe as fp`
49* Some utilities to look at: `f.compact`
50 
51For example, instead of:
52 
53```python
54params: dict[str, str] = {}
55if city:
56    params["city"] = city
57if state_code:
58    params["stateCode"] = state_code
59```
60 
61Use:
62 
63```python
64params = f.compact({"city": city, "stateCode": stateCode})
65```
66 
67### Date & DateTime
68 
69* Use the `whenever` library for datetime + time instead of the stdlib date library. `Instant.now().format_iso()`
70* DateTime mutation should explicitly opt in to a specific timezone `SystemDateTime.now().add(days=-7)`
71