python-conventionslisted

# Python Conventions This file is self-contained for day-to-day use. Deeper reference (needs the full harness checkout, not just this skill — these aren't bundled here since they're documentation, not something this skill runs): `languages/python/CONVENTIONS.md` (complete examples) and `languages/python/COPILOT_INSTRUCTIONS.md` (general agent operating principles for Python repos — inspect before changing, scope discipline, never claim a command passed without running it). ## Naming - `snake_case` — functions, variables. `PascalCase` — classes. `UPPER_SNAKE_CASE` — module-level constants. - Single underscore prefix for private (`_internal`); avoid double underscore except for genuine name-mangling needs. - Exceptions: `PascalCase` + `Error`/`Exception` suffix, specific not generic (`ValidationError`, not `BadThing`). ## Imports & structure Standard library → third-party → local, each group separated by a blank line. Absolute imports over relative. No `from module import *`. ## Type hints Use them on function parameters and returns. Match syntax to the project's minimum Python version — check `requires-python` in `pyproject.toml` before using `list[str]` (3.9+), `X | None` (3.10+), or `match/case` (3.10+). Don't silently raise the minimum version. ## Pitfalls to catch in review ```python # Mutable default argument — persists across calls, shared state bug def f(item, container=[]): # WRONG def f(item, container=None): # RIGHT — default to None, create inside