python

Sub-Skill: Python Best Practices

Purpose: Prevents the Python-specific mistakes LLMs make on autopilot — mutable defaults, bare excepts, missing guards, and subtle performance traps that pass review but break in production.

Rule classification

• MUST — load-bearing. Violating causes bugs, security issues, or invisible failures. Never break.
• SHOULD — default behavior. Deviation needs a documented reason in the code or PR.
• AVOID — usually wrong; documented exception inline where needed.

Where these rules don't strictly apply: test fixtures, generated code, throwaway scripts, REPL exploration, and tutorial snippets may legitimately differ. The rules below apply to production code paths and reusable libraries.

---

Rules

Type Hints

1. SHOULD: Annotate function signatures with types. def process(data) tells callers nothing. Use def process(data: list[str]) -> dict[str, int]:. Return type None should be explicit too. Exception: lambdas and short generator helpers in private scope.

2. SHOULD: Use built-in lowercase generics for Python 3.9+. list[str], dict[str, int], tuple[int, ...] rather than List, Dict, Tuple from typing.

3. MUST: Use Optional[X] or X | None for nullable parameters, never a bare default of None without a type annotation. def find(id: int) -> User | None: not def find(id):.

4. AVOID: Any as a shortcut. If the type is genuinely unknown, document why with a comment. Any silences the type checker and hides bugs. Exception: third-party libraries without stubs and explicit dynamic-data boundaries (e.g. JSON decode at the API edge).

---

Error Handling

1. MUST: Never use bare except:. It catches SystemExit, KeyboardInterrupt, and GeneratorExit. Always catch except Exception: at minimum, or a specific exception class.

   # Wrong
   try:
       risky()
   except:
       pass
   
   # Correct
   try:
       risky()
   except ValueError as e:
       logger.warning("Invalid value: %s", e)