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:

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)