プロジェクト固有チェックの追加¶
[tool.pyfltr.custom-commands]で任意のツール・独自スクリプトを追加できる。
追加したカスタムコマンドは組み込みのformatter・linter・testerと同じ実行の流れで動作する。
pyfltrは並列実行・fixステージ・severity・hints・JSON Lines出力を組み込みツールと同一に扱う。
コーディングエージェント向けの実行基盤へ、プロジェクト固有のチェックを統合する場合に利用する。
導入手順ははじめにを参照。
error-patternは名前付きグループfile / line / messageが必須、colは任意。
正規表現にこれらが含まれない場合は設定エラーとなる。
カスタムコマンドの仕様¶
[tool.pyfltr.custom-commands]で任意のツールを追加できる。
[tool.pyfltr.custom-commands.mytool]
type = "linter"
path = "mytool"
args = ["-r", "-f", "custom"]
targets = "*.py"
error-pattern = '(?P<file>[^:]+):(?P<line>\d+):(?P<col>\d+):\s*(?P<message>.+)'
config-files = [".mytoolrc", "pyproject.toml"]
fast = true
設定項目。
type（必須）:"formatter"/"linter"/"tester"- formatterは直列実行、linter/testerは並列実行
path: 実行コマンド（省略時はコマンド名）args: 追加引数（省略時は空）extend-args:argsの末尾へ追加する引数（省略時は空）。args既定値を保ったまま要素を足したい場合に使うtargets: 対象ファイルパターン（省略時は"*.py"）error-pattern: エラーパース用正規表現（省略可）fileとlineとmessageの名前付きグループが必須colは任意- 指定するとErrorsタブやエラー一覧に表示される
fast:fastサブコマンドに含めるか否か（省略時はfalse）fix-args: fix段でargsの後ろへ追加する引数（省略時はfix段の対象外）pass-filenames: ファイル引数をコマンドに渡すか否か（省略時はtrue）。 プロジェクト全体を一括チェックするツールではfalseに設定するconfig-files: このコマンドの設定ファイル候補のリスト（省略時は空）。globパターン可。 有効化したコマンドを実行するときに、どれもプロジェクトルート直下に見つからないとpyfltrが警告を発行する（ツール自体は実行する）。--commandsなどで実行対象から外したコマンドは判定しない。 pre-commit・prekなどの「設定ファイル無しでは機能しないツール」の設定不備を可視化する用途。 判定はモノレポでも起点cwd直下のみを対象とし、サブプロジェクトのディレクトリでは行わないseverity:"error"（既定）または"warning"。 詳細はseverityによる失敗の警告化を参照hints: LLM向けの追加文言（文字列の配列、省略時は空）。 詳細はhintsによるLLM向け補足を参照
ビルトインコマンド（mypy等）は自動的にエラーパースされる。
カスタムコマンドに対しても--{name}-argsやenable/disableを使用できる。
pyfltr run / pyfltr ci のように--commandsを省略したサブコマンドでは、
登録済みの有効なカスタムコマンドもビルトインと同様にデフォルトの実行対象に含まれる。
特定のツールだけを動かしたい場合は--commands=svelte-checkのように明示指定する。
カスタムコマンドでの fix モード対応¶
autofix機能を持つツールをカスタムコマンドとして登録する場合は、fix-argsを定義しておくとrun/fastのfix段に含まれる。
[tool.pyfltr.custom-commands.my-linter]
type = "linter"
path = "my-linter"
args = ["--check"]
fix-args = ["--fix"]
fixモードではargsの後にfix-argsが追加され、my-linter --check --fix <files>として実行される。
実運用例（リポジトリ固有スクリプトの統合）¶
生成ファイルの同期・エンコーディング・リンク切れなどをチェックする独自スクリプトを、
組み込みツールと並列に実行するカスタムコマンドとして登録できる。
type = "linter"かつpass-filenames = falseを指定すると、対象ファイル引数を渡さずにリポジトリ全体をチェックする。
[tool.pyfltr.custom-commands.project-check]
type = "linter"
path = "uv"
args = ["run", "--script", "scripts/check_project.py"]
targets = "*"
pass-filenames = false
Pythonセキュリティ・品質ツール¶
banditは組み込みツールとして利用する。banditの設定を参照。
deptry（未使用・不足依存の検出）¶
[tool.pyfltr.custom-commands.deptry]
type = "linter"
path = "deptry"
args = ["."]
targets = "*.py"
pass-filenames = false
vulture（未使用コードの検出）¶
[tool.pyfltr.custom-commands.vulture]
type = "linter"
path = "vulture"
args = []
targets = "*.py"
error-pattern = '(?P<file>[^:]+):(?P<line>\d+):\s*(?P<message>.+)'
fast = true
detect-secrets（シークレット検出）¶
[tool.pyfltr.custom-commands.detect-secrets]
type = "linter"
path = "detect-secrets"
args = ["scan", "--list-all-plugins"]
targets = "*.py"
pass-filenames = false
汎用ツール¶
codespell（スペルチェック）¶
fix-argsを定義するとfix段でargsの後ろに追加されて--write-changes付きで実行される。
[tool.pyfltr.custom-commands.codespell]
type = "linter"
path = "codespell"
args = []
fix-args = ["--write-changes"]
targets = ["*.py", "*.md", "*.rst", "*.txt"]
fast = true
cspell（スペルチェック、npm系）¶
js-runner対応のスペルチェッカー。package.jsonでインストールする前提で、js-runner = "pnpm"と併用する。
[tool.pyfltr]
js-runner = "pnpm"
[tool.pyfltr.custom-commands.cspell]
type = "linter"
path = "cspell"
args = ["lint", "--no-progress", "--no-summary"]
targets = ["*.py", "*.md", "*.ts", "*.js"]
error-pattern = '(?P<file>[^:]+):(?P<line>\d+):(?P<col>\d+)\s*-\s*(?P<message>.+)'
fast = true
JS/TSプロジェクト向け¶
svelte-check（Svelteの型チェック）¶
[tool.pyfltr.custom-commands.svelte-check]
type = "linter"
path = "svelte-check"
args = ["--tsconfig", "./tsconfig.json"]
targets = "*.svelte"
pass-filenames = false