python-code-quality

name python-code-quality description Code quality checks, linting, formatting, and type checking commands for the Agent Framework Python codebase. Use this when running checks, fixing lint errors, or troubleshooting CI failures. 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 uv run poe syntax -F # Format only uv run poe syntax -C # Check only uv run poe syntax -S # Samples only # Type checking # # Division of labor (see "Type checking architecture" below): # - Pyright (strict) is the source-code type checker. # - Pyright (relaxed `basic`), mypy, pyrefly, ty, zuban all check the TESTS; # pyright/pyrefly/ty also check the SAMPLES (mypy/zuban skip script-style samples). uv run poe pyright # Pyright (strict) over SOURCE, fan-out across packages uv run poe pyright -P core uv run poe pyright -A uv run poe test-typing # mypy + pyrefly + ty + zuban + pyright over each package's TESTS uv run poe test-typing -P core uv run poe test-typing -S # samples (pyrefly + ty + pyright) uv run poe test-typing -P core --checker mypy # narrow to one checker (repeatable) uv run poe test-typing -P core --checker pyright # relaxed pyright over the tests uv run poe mypy # alias: MyPy over the tests only uv run poe mypy -P core uv run poe typing # Pyright (source) + the tests checkers uv run poe typing -P core uv run poe typing -A # All package-level checks in parallel (syntax + pyright) uv run poe check-packages # Full check (packages + samples + tests + markdown) uv run poe check uv run poe check -P core # Samples only uv run poe check -S uv run poe pyright -S # Markdown code blocks uv run poe markdown-code-lint Pre-commit Hooks (prek) Prek hooks run automatically on commit. They stay lightweight and only check changed files. # Install hooks uv run poe prek-install # Run all hooks manually uv run prek run -a # Run on last commit uv run prek run --last-commit 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: Target Checker(s) Mode Config Source ( agent_framework* ) pyright strict [tool.pyright] in pyproject.toml Tests pyright, mypy, pyrefly, ty, zuban relaxed/basic pyrightconfig.tests.json , [tool.mypy] , pyrefly.toml , ty rules Samples pyright, pyrefly, ty basic pyrightconfig.samples.json , pyrefly.samples.toml , ty.samples.toml 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: Pre-commit hooks — lightweight hooks (SKIP=poe-check) Package checks — syntax/pyright (source) via check-packages Samples & markdown — check -S plus markdown-code-lint Test Typing — change-detected mypy/pyrefly/ty over tests ( ci-test-typing )