65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
---
|
||
name: python
|
||
description: >
|
||
Python coding conventions, style, and tooling.
|
||
Use for anything involving Python code.
|
||
---
|
||
|
||
# Python Coding Conventions
|
||
|
||
## Tooling
|
||
|
||
- **Always use `uv`** — never bare `pip`, `python`, `venv`, or `virtualenv`.
|
||
- Run code: `uv run script.py` (or `uv run python -m module`)
|
||
- Add dependencies: `uv add <pkg>`; sync: `uv sync`
|
||
- One-off tools: `uv run --with <pkg> ...` or `uvx <tool>`
|
||
- **Format before done:** `uv run ruff format`
|
||
- **Lint before done:** `uv run ruff check --fix`
|
||
- Treat "done" as: formatted, linted clean, type hints present.
|
||
|
||
## Core Principles
|
||
|
||
- **Readability first** — code must be easily readable and understandable at a glance
|
||
- **Simplicity** — prefer the simplest solution that solves the problem; avoid unnecessary abstractions and cleverness
|
||
- **Clean Code** — meaningful names, small focused functions, single responsibility, no duplication (DRY), clear intent
|
||
|
||
## Style
|
||
|
||
- Follow PEP 8, but max line length **120 characters** (not the default 88)
|
||
|
||
## Types and Annotations
|
||
|
||
- Use Python 3.12+ built-in generics: `list[str]`, `dict[str, int]`, `tuple[int, ...]`
|
||
- Use `X | Y` instead of `Union[X, Y]`, `str | None` instead of `Optional[str]`
|
||
- Do not import from `typing` unless truly necessary (e.g., `Protocol`, `TypeVar`)
|
||
- All public functions and methods must have type hints
|
||
|
||
## Docstrings and Comments
|
||
|
||
- Add a docstring or comment only when it explains **intent** not obvious from the code or signature
|
||
- First line: short imperative summary; omit parameter/return docs if self-explanatory
|
||
- Prefer clear naming over explanatory comments; never restate what the code does
|
||
|
||
## Functions
|
||
|
||
- Break complex functions into smaller ones; one thing at one level of abstraction
|
||
- Keep the parameter count low (0–3)
|
||
- No boolean flag arguments — split into two well-named functions or use an enum
|
||
- Command-Query Separation: a function that returns a value must not mutate state
|
||
- Handle edge cases explicitly; prefer specific exceptions over bare `except`
|
||
|
||
## Control Flow
|
||
|
||
- Fail fast — validate inputs up front with guard clauses and early returns
|
||
- Avoid deep nesting (max 2–3 levels); invert conditions to return early
|
||
- Replace magic numbers and strings with named constants
|
||
|
||
## Error Handling
|
||
|
||
- Never silently swallow exceptions
|
||
- Do not unnecessarily wrap exceptions in other exception types
|
||
|
||
## Paths
|
||
|
||
- Prefer `pathlib.Path` over `os.path`
|