Python Backend

Apply these rules when producing or modifying Python backend code. Optimize for correctness, performance, and maintainability while keeping changes small and reversible.

Defaults

• Prefer clarity first, then optimize hotspots based on evidence (profiling/benchmarks) rather than blanket micro-optimizations.
• Avoid unnecessary abstractions; keep code minimal and easy to review.
• Use descriptive names; avoid one-letter names outside tight comprehensions.

Tooling

• Use uv for dependency management and virtual environments (.venv) when appropriate for the repo.
• Use Ruff for formatting + linting (do not mix with Black/isort unless the repo already does).
• Use mypy for static type checking when the repo is typed; match the repo's existing strictness.
• Use pytest for tests; follow Arrange-Act-Assert for readability.
• For notebooks, install ipykernel/ipywidgets into the local .venv when needed, but do not add them to runtime requirements.

Code style

• Follow PEP 8; default to 4-space indentation.
• Prefer pathlib.Path over raw string paths for file operations (unless the repo standard differs).
• Use f-strings for formatting; use enumerate() over manual counters.
• Avoid mutable default arguments.

Types and APIs

• Type all public function signatures (params + return types).
• Avoid Any; if unavoidable, isolate it at the boundary (e.g., parsing/IO) and convert to typed structures quickly.
• Prefer dataclasses (or pydantic models if the repo already uses them) for structured data.

Errors and logging

• Catch specific exceptions; never use bare except:.
• Do not swallow exceptions silently; log and re-raise or translate to a domain-appropriate error.
• Prefer structured logging; use logger.exception(...) when handling unexpected failures.

Data work

• Prefer polars over pandas for new dataframe work unless the repo standardizes on pandas.
• When printing a polars DataFrame, do not redundantly print both schema and row counts unless explicitly requested.

Security and config

• Never hardcode secrets/tokens/credentials; load from environment variables or .env for local dev.
• Ensure .env is excluded via .gitignore when relevant.
• Avoid logging secrets or URLs containing secrets.

Testing expectations

• Add unit tests for new logic (pure functions and business rules first).
• Mock external dependencies (network, databases, filesystem) at the boundary.
• Do not generate "tests" inside production modules; place them in dedicated test files matching repo conventions.

Pre-PR checklist

• Run Ruff and relevant tests for changed modules.
• Run mypy if the project uses it and types were touched.
• Confirm no debug prints/breakpoints or commented-out code is introduced.