python_dev

applyTo: "**/*.py"

Python Development Environment and tooling:

• Please run any python file using uv run $file.py
• Same for tools, e.g. un run python pytest $file_path
• To add a package, use cd $repo_root; uv add <package_name>.
  • Please never mention versions of package, so uv will bring the latest.
  • On this note, I have to say that I am seriously concerned about AI using very outdated coding style.
    • Use python 3.13 & 3.14 syntax features.
    • Use modern standards, e.g. Path from pathlib.
• Never touch pyproject.toml manually, this file is strictly managed by uv tool on your behalf.
• If you are writing a test or any temporary script for discovering or undestanding something as an intermediate step, then, please keep all your temp scripts and files under ./.ai/tmp_scripts directory, its included in .gitignore and won't litter the repo. Its also nice if you create a subdirectory therein to contain relevant files for the task at hand, to avoid confusion with other files from other ai agents working simulataneously on other things.
• When you run a command in the terminal, please don't assume that it will run in the correct repo root directory. Always cd first to the repo root, or the desired directory, then run the command.

Python Coding Rules

• Please type hint all the code. Use fully quilaified types, not just generics like dict, list, etc, rather dict[str, int], list[float], 'npt.NDarray[np.float32]', etc.
• Please avoid the type Any, unless absoloutely necessary.
• Please use # type: ignore blah blah, to silence any warning from pyright or other linters and type checkers, but only when necessary. Otherwise, listen to them and adjust accordingly, or use cast from typing.
• Use typeddict, dataclasses and literals when necessary to avoid blackbox str or dict[str, str] etc.
• ALL functions / methods etc must clearly indicate the return type in signature, even if its None.
• Don't make file name types.py it conflicts with built-in modules.
• Avoid from futures import annotations and the like, we are using python 3.13+ so no need for that.
• Avoid writing code in init.py files, I hate black magic, avoid shims, and export files.
• Avoid writing short functions with one or two lines, in-line instead.
• Do not leave dangling imports or variables unused, prefix their name with underscore if necessary to indicate they are unused.
• Please prefer to use absolute imports, avoid relatives when possible.
• Use triple quotes and triple double quotes f-strings for string formatting and avoid when possible all goofy escaping when interpolation.
• If needed, opt for polars not pandas, whenever possible.
• when finished, run a linting static analysis check against files you touched, Any fix any mistakes.
• Please run uv run -m pyright $file_touched and address all issues.
• For all type checkers and linters, like mypy, pyright, pyrefly and pylint, there are config files at different levels of the repo all the way up to home directory level. You don't need to worry about them, just be mindful that they exist. The tools themselves will respect the configs therein.
• If you want to run all linters and pycheckers agains the entire project to make sure everything is clean, I prepared a nice shell script, you can run it from the repo root as ./.ai/scripts/lint_and_type_check.sh. It will produce markdown files that are you are meant to look at @ ./.ai/linters/*.md
• Rust-inspired style, e.g.