python-code-quality

Python Code Quality

Quick Commands

All commands run from the python/ directory:

# Syntax formatting + checks (parallel across packages by default)
uv run poe syntax
uv run poe syntax -P core

Pre-commit Hooks (prek)

Prek hooks run automatically on commit. They stay lightweight and only check changed files.

They run changed-package syntax formatting/checking, markdown code lint only when markdown files change, and sample syntax lint/pyright only when files under samples/ change. They intentionally do not run workspace pyright or mypy by default.

Type checking architecture

Following the "too many type checkers" approach, type checkers are split by target:

• Pyright is the only strict source-code checker, and it ALSO runs in a relaxed basic profile over the tests and samples (so the surfaces customers copy from are validated by every checker, including pyright). MyPy was removed from source; its [tool.mypy] block is now a relaxed profile used only for tests/samples.
• The extra checkers run over tests/samples because those exercise the public API the way users do. The profile is intentionally relaxed (private access allowed, untyped test bodies allowed) so authors aren't forced into ugly over-annotation.
• Gating checkers are pyright, mypy, pyrefly, ty, and zuban — all five run by default and gate CI. zuban is the strictest of the mypy-compatible pair, so the same [tool.mypy] config yields more findings; suppress zuban-only friction with shared # type: ignore[code]. Suppress relaxed-pyright friction with # pyright: ignore[rule].
• Samples add pyright to pyrefly + ty — mypy/zuban can't resolve script-style sample layouts (numeric-prefixed dirs, duplicate main.py), but pyright handles them.
• The strict source-pyright ([tool.pyright]) enforces reportUnnecessaryTypeIgnoreComment and excludes tests/samples; the relaxed test/sample pyright configs do not flag unnecessary ignores.

Ruff Configuration

• Line length: 120
• Target: Python 3.10+
• Auto-fix enabled
• Rules: ASYNC, B, CPY, D, E, ERA, F, FIX, I, INP, ISC, Q, RET, RSE, RUF, SIM, T20, TD, W, T100, S
• Scripts directory is excluded from checks

Pyright Configuration

• Source: strict mode ([tool.pyright]), reportUnnecessaryTypeIgnoreComment = "error", excludes tests, samples, .venv, packages/devui/frontend.
• Tests: relaxed basic profile (pyrightconfig.tests.json) — private import/usage and not-required TypedDict access allowed; runs as the pyright checker in test-typing.
• Samples: relaxed basic profile (pyrightconfig.samples.json, with a py310 variant) — runs as the pyright checker in test-typing -S.

Parallel Execution

The task runner (scripts/task_runner.py) executes the cross-product of (package × task) in parallel using ThreadPoolExecutor. Single items run in-process with streaming output.

CI Workflow

CI splits into 4 parallel jobs:

1. Pre-commit hooks — lightweight hooks (SKIP=poe-check)
2. Package checks — syntax/pyright (source) via check-packages
3. Samples & markdown — check -S plus markdown-code-lint
4. Test Typing — change-detected mypy/pyrefly/ty over tests (ci-test-typing)