Python

<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

Python

Guidance for writing and editing Python in this ecosystem. Formatting, import order, lint, and typing are enforced by the deterministic gates (ruff format, ruff check, pyright) in the pre-commit hook — never restate a linter's rules here or send an agent to do a formatter's job. This skill carries the judgment those gates cannot.

Style

• Type-hint public functions, methods, and dataclass fields; let inference cover obvious locals. A public signature is a contract — annotate it.
• Prefer pathlib.Path over os.path string munging for filesystem work.
• Do not hand-format to match the formatter. Run ruff format / ruff check (they run in pre-commit) and let them own whitespace, quotes, and import order.

except A, B: is valid here — leave it alone

This repo's floor is Python 3.14 (requires-python = ">=3.14"), where PEP 758 makes an unparenthesized multi-exception clause legal: except ValueError, OSError: catches either type. It is not the Python 2 except Error, name: capture form and not a syntax error — src/basicly/decompose.py uses it and imports fine. Do not add parentheses to "fix" it; that is a no-op diff, and stopping to re-verify that the module parses costs a whole detour.

Parentheses are still required when the clause binds the exception — except (ValueError, OSError) as err:. Dropping them there raises SyntaxError: multiple exception types must be parenthesized when using 'as'.

Type test doubles and helpers precisely

pyright runs as a commit gate, so a loosely-typed test helper blocks the commit itself, not just CI. Annotate test doubles, fakes, and helper return values with the real type they stand in for — never a bare object:

• Return the concrete type, not object — def _fake_args() -> argparse.Namespace:, not -> object. An object returned where a concrete type is expected trips reportArgumentType at the first call site that passes it on.
• Type a captured container to its real value type — captured: dict[str, list[str]], not dict[str, object]. A dict[str, object] value trips reportOperatorIssue the moment the test indexes, iterates, or compares it.

Cross-platform shell-out (fails only on Windows CI)

Two subprocess mistakes pass every local POSIX run and surface only on Windows CI, so they read as "flaky" when they are deterministic. Both, with reproductions and fixes, are in references/cross-platform.md:

• Building the child env — inherit os.environ (keep PATH). A bare env dict drops PATH, which still finds git and friends on POSIX but raises [WinError 2] on Windows.
• Embedding an OS path in a shell string — POSIX shlex.split treats \ as an escape, so a Windows path like sys.executable is mangled. Pass an argv list, or normalize with Path(...).as_posix(); never concatenate a path into a shell string.

Read the reference before touching any code that spawns a process or builds a command line.