Python
Write Python that passes the gates on every platform. The pre-commit hook runs every
check that basicly.toml declares for mode fast, for example ruff and pyright.
This skill holds the decisions that those gates cannot make.
Rules
- Leave
except A, B:unchanged. On Python 3.14 and later, PEP 758 makes it valid, and it catches either type. It is not the Python 2 capture form. - Keep the parentheses when the clause binds a name:
except (A, B) as err:. Without them Python raises multiple exception types must be parenthesized when using 'as'. - Copy
os.environinto a child environment. A bareenvdict dropsPATH, and Windows then raises[WinError 2]. - Pass an argv list, not a shell string.
shlex.splitremoves the backslashes of a Windows path. - Type-hint public functions, methods and dataclass fields. A public signature is a contract. Inference covers obvious local names.
- Use
pathlib.Pathfor filesystem work, notos.pathstring operations. - Let the formatter own layout. Do not format by hand. Run
ruff formatandruff check. - Commit early and let the hook name a type error. A clean
ruff checkand a greenpytestdo not prove thatpyrightpasses.
Type test doubles and helpers
Make a helper precise about the type it returns. Make a parameter structural about the double it receives.
- Return the concrete type:
def _fake_args() -> argparse.Namespace:, not-> object. AnobjecttripsreportArgumentTypeat the first call site that passes it on. - Type a captured container to its real value type:
dict[str, list[str]], notdict[str, object]. Anobjectvalue tripsreportOperatorIssuewhen the test indexes or compares it. - Type a parameter that receives a double as
Callable[..., _Proc]or aProtocol, never as a sibling fake class. A second fake or alambdathen fails with"_FakeB" is not assignable to "_FakeA" (reportArgumentType).
Shell out on every platform
Two subprocess mistakes pass on POSIX and fail only on Windows CI. The failure is deterministic, not flaky. Read references/cross-platform.md before you change code that starts a process or builds a command line.
Design decisions
A gate reports a size, a suppression or a complexity, but not the fix. Read references/design.md before you split a file, add an abstraction, silence a warning or choose what to raise and catch.