Python style rules

When you write or change Python code in this project:

Version and tooling

• Target the Python version declared in pyproject.toml (requires-python). Do not use syntax or standard-library features newer than that.
• Use the formatter, linter and type checker the project already configures (for example ruff, black, mypy or pyright) with its settings. Do not add new tools or reformat code you did not change.
• Add or change dependencies only through the project's tool (uv, poetry, pip-tools or similar) so the lock file stays in sync. Never install packages globally.

Types

• Annotate every function and method signature, including return types. Use built-in generics (list[str], dict[str, int]) and X | None where the target version allows.
• Avoid Any. Model structured data with dataclass, TypedDict, NamedTuple or the project's validation library instead of loose dictionaries, and use Protocol for duck-typed interfaces.

Files, paths and resources

• Use pathlib.Path, not string concatenation or os.path joins.
• Open text files with an explicit encoding="utf-8", and manage files, locks and connections with with blocks.
• Use timezone-aware datetimes (datetime.now(tz=UTC)); never mix naive and aware values.

Logging and output

• In library and service code, log through logger = logging.getLogger(__name__), never print. Use print only for a command-line program's intended output.
• Pass values as logging arguments (logger.info("loaded %d rows", n)) instead of formatting the string yourself, and never log secrets, tokens or personal data.

Errors

• Catch the narrowest exception that you can handle. Never write a bare except: or except Exception: pass.
• Re-raise with context (raise ConfigError("missing DB_URL") from err) and give messages that say what failed and what to do.
• Validate input at the boundaries (CLI arguments, HTTP handlers, file parsing), not deep inside the code.

Safety

• Call subprocess.run with a list of arguments and check=True. Never use shell=True with interpolated input.
• Never use eval, exec or pickle on untrusted data. Build SQL with parameters, never with f-strings.
• Never use mutable default arguments. Use None and create the value inside the function.

Layout and style

• Follow the existing package layout. For new projects, use a src/ layout with pyproject.toml and tests under tests/.
• Keep __init__.py to imports and exports. Guard script entry points with if __name__ == "__main__":.
• Use f-strings for formatting. Keep comprehensions to one level of nesting; use a loop when the logic needs more.
• Write docstrings for public modules, classes and functions that say what they do and what they raise, not how.