python

Python

When writing Python:

• Assume the latest python, version 3.13.
• Prefer Pathlib methods (including read and write methods, like read_text) over os.path, open, write, etc.
• docstrs and comments:
  • If a docstring needs formatting, use markdown. Use Google Style.
  • Prefer docstr to multi-line comments at the top of a function or file.
  • If a docstr does not span multiple lines, do not use triple-quoted strings.
  • Add a newline after """ when using triple-quoted docstrings.
  • If a comment or docstr is a single line, do not end it in a period.
• Do not create __init__ files unless specifically instructed
• Use Pydantic models over dataclass or a typed dict.
• Use SQLAlchemy for generating any SQL queries.
• Use click for command line argument parsing.
• 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.
  • Log messages should be lowercase with no leading or trailing whitespace.
  • No variable interpolation in log messages.
  • Do not coerce database IDs, dates, or Path objects to str
• Do not fix import ordering or other linting issues.
• Never edit or create any files in migrations/versions/
• Place all comments on dedicated lines immediately above the code statements they describe. Avoid inline comments appended to the end of code lines.
• Do not try/catch raw Exceptions unless explicitly told to. Prefer to let exceptions raise and cause an explicit error.
• Always make an explicit copy before mutating a dictionary that you did not create in the current narrow scope.
• Never use from __future__
• 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.
• IMPORTANT never edit app/generated/ files. These are autogenerated.

Package Management

• Use uv add to add python packages. No need for pip compile, pip install, etc.