Copilot instructions

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