python-code-quality

Python のコード品質

クイックコマンド

すべてのコマンドは python/ ディレクトリから実行します。

# 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

Poe と pytest ツールチェーンは、複数バージョンに対応する開発環境内に置きます。Ruff と型チェッカーは、バージョンを固定した tooling/requirements-*.txt ファイルを使用します。prek は必要な場合に限り、tool-hooks 依存関係グループから選択されます。

プレコミットフック（prek）

prek フックはコミット時に自動実行されます。軽量に保ち、変更されたファイルのみをチェックします。

# Install hooks
uv run poe prek-install

# Run all hooks manually
uv run --group tool-hooks prek run -a

# Run on last commit
uv run --group tool-hooks prek run --last-commit

変更されたパッケージの構文フォーマットとチェックを行います。また、Markdown ファイルの変更時のみ Markdown コードのリンティングを、samples/ 配下のファイルの変更時のみサンプルの構文リンティングと pyright を実行します。 ワークスペース全体の pyright や mypy は、意図的にデフォルトでは実行しません。

型チェックのアーキテクチャ

「型チェッカーが多すぎる」アプローチに従い、型チェッカーを対象ごとに分けています。

対象	チェッカー	モード	設定
ソース（agent_framework*）	pyright	strict	pyproject.toml の [tool.pyright]
テスト	pyright、mypy、pyrefly、ty、zuban	relaxed/basic	pyrightconfig.tests.json、[tool.mypy]、pyrefly.toml、ty ルール
サンプル	pyright、pyrefly、ty	basic	pyrightconfig.samples.json、pyrefly.samples.toml、ty.samples.toml

• ソースコードを strict モードでチェックするのは pyright のみです。また、テストとサンプルでは relaxed な basic プロファイルでも実行されます（顧客がコピーする箇所は、pyright を含むすべてのチェッカーで検証されます）。MyPy はソースから削除され、[tool.mypy] ブロックはテストとサンプルのみで使用する relaxed プロファイルになりました。
• 追加のチェッカーをテストとサンプルに適用するのは、これらがユーザーと同じ方法でパブリック API を使用するためです。プロファイルは意図的に緩やかに設定しており（プライベートなアクセスを許可し、型注釈のないテスト本体も許可）、作成者に不自然なほど多くの型注釈を強いることはありません。
• ゲートとなるチェッカーは pyright、mypy、pyrefly、ty、zuban です。5 つすべてがデフォルトで実行され、CI のゲートになります。mypy 互換の 2 つのチェッカーのうち、zuban は最も厳格なため、同じ [tool.mypy] 設定でもより多くの指摘が見つかります。zuban 固有の問題は、共通の # type: ignore[code] で抑制します。relaxed-pyright 固有の問題は、# pyright: ignore[rule] で抑制します。
• サンプルでは、pyrefly と ty に加えて pyright も実行します。mypy/zuban はスクリプト形式のサンプルレイアウト（数字で始まるディレクトリ、重複する main.py）を解決できませんが、pyright なら処理できます。
• pyrefly.samples.toml では、単独で使われる兄弟モジュールのインポートを解決できるよう、フォールバック検索を有効にしています。ty のサンプルプロファイルでは、PEP 723 の兄弟ヘルパー用にファーストパーティの root = ["."] を使用し、既存のサンプルでの自動的な追加パス検索を維持します。
• strict なソース用 pyright（[tool.pyright]）では reportUnnecessaryTypeIgnoreComment を適用し、テストとサンプルを除外します。relaxed なテスト用およびサンプル用の pyright 設定では、不要な ignore を指摘しません。

Ruff の設定

• 行の長さ：120
• 対象：Python 3.10 以降
• 自動修正を有効化
• ルール：ASYNC、B、CPY、D、E、ERA、F、FIX、I、INP、ISC、Q、RET、RSE、RUF、SIM、T20、TD、W、T100、S
• スクリプトディレクトリはチェック対象から除外

Pyright の設定

• ソース：strict モード（[tool.pyright]）、reportUnnecessaryTypeIgnoreComment = "error" を設定し、tests、samples、.venv、packages/devui/frontend を除外します。
• テスト：relaxed な basic プロファイル（pyrightconfig.tests.json）を使用します。プライベートなインポート／使用と、必須ではない TypedDict へのアクセスを許可します。test-typing の pyright チェッカーとして実行されます。
• サンプル：relaxed な basic プロファイル（py310 用の設定を含む pyrightconfig.samples.json）を使用します。test-typing -S の pyright チェッカーとして実行されます。

並列実行

タスクランナー（scripts/task_runner.py）は、（パッケージ × タスク）の組み合わせを ThreadPoolExecutor を使用して並列実行します。項目が 1 つの場合は、出力をストリーミングしながらプロセス内で実行します。

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)