設定例

pyproject.toml

pyfltr本体の設定（[tool.pyfltr]）と、呼び出される各ツール（ruff / mypy / pytest）の設定を1つのpyproject.tomlにまとめた例。

• preset = "latest": 主要ツールを有効化するプリセット（現在は20260411相当）。ruff-format / ruff-check / pyrightなど8ツールが有効化され、旧ツール（pyupgrade / autoflake / isort / black / pflake8）は無効化される。詳細はdocs/configuration.mdの「プリセット設定」を参照。
• pylint-args: pylintに追加で渡す引数。--load-plugins=pylint_pydanticと--enable-error-code=unused-awaitable（mypy）は自動オプションで既定有効のため個別指定不要。
• ruffの per-file-ignores: テストコード（**_test.py）とpackage init（__init__.py）のdocstring要求を除外する実用的な調整。

[dependency-groups]
dev = [
    ...
    "pyfltr",
]

...

[tool.pyfltr]
preset = "latest"
pylint-args = ["--jobs=4"]

[tool.ruff]
# https://docs.astral.sh/ruff/configuration/
line-length = 128

[tool.ruff.lint]
# https://docs.astral.sh/ruff/linter/#rule-selection
select = [
    # pydocstyle
    "D",
    # pycodestyle
    "E",
    # Pyflakes
    "F",
    # pyupgrade
    "UP",
    # flake8-bugbear
    "B",
    # flake8-simplify
    "SIM",
    # flake8-import-conventions
    "ICN",
    # isort
    "I",
]
ignore = [
    "D107", # Missing docstring in `__init__`
    "D415", # First line should end with a period
]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.per-file-ignores]
"**_test.py" = ["D"]
"**/__init__.py" = ["D104"]  # Missing docstring in public package

[tool.mypy]
# https://mypy.readthedocs.io/en/stable/config_file.html
allow_redefinition = true
check_untyped_defs = true
ignore_missing_imports = true
strict_optional = true
strict_equality = true
warn_no_return = true
warn_redundant_casts = true
warn_unused_configs = true
show_error_codes = true

[tool.pytest.ini_options]
# https://docs.pytest.org/en/latest/reference/reference.html#ini-options-ref
addopts = "--showlocals -p no:cacheprovider --maxfail=5 --durations=30 --durations-min=0.5"
log_level = "DEBUG"
xfail_strict = true
asyncio_mode = "strict"
asyncio_default_fixture_loop_scope = "session"
asyncio_default_test_loop_scope = "session"

JS/TSを併用するプロジェクトでの推奨設定

JS/TSを併用するプロジェクトでは、js-runnerをプロジェクトのパッケージマネージャーに合わせることを推奨する。 既定のpnpxはツールを都度取得するため、CIで毎回ダウンロードが発生する。 pnpmやnpmなど、プロジェクトで使用しているパッケージマネージャーを指定すれば、package.jsonで管理済みのパッケージを再利用できる。

[tool.pyfltr]
js-runner = "pnpm"

pnpm / npm / yarn / directではtextlint-packagesは無視される（package.json側でインストールする前提のため）。 textlintのプリセットやルールもpackage.jsonのdevDependenciesで管理すること。

詳細はdocs/configuration.mdの「npm系ツール」を参照。

JS/TS専用プロジェクトでの推奨設定

JS/TS専用プロジェクトでは、python = falseでPython系ツールを一括無効化し、必要なJS/TSツールを個別に有効化する。

[tool.pyfltr]
python = false
js-runner = "pnpm"
eslint = true
prettier = true
markdownlint = true
textlint = true
vitest = true

pre-commitの設定例。JS/TS専用プロジェクトではpyfltrをdev依存に含めないため、uvxで都度取得する。

  - repo: local
    hooks:
      - id: pyfltr
        name: pyfltr
        entry: uvx pyfltr fast
        types_or: [javascript, jsx, ts, tsx, json, css, yaml, markdown]
        require_serial: true
        language: system

ポイント:

• python = false: Python系ツールを一括無効化する。対象ツールの一覧はdocs/configuration.mdの「Python系ツールの一括無効化」を参照。
• uvx pyfltr fast: pyfltrをdev依存に含めないJS/TS専用プロジェクトでは、uvxで都度取得して実行する。
• types_or: プロジェクトで使用するファイルタイプを列挙する。Pythonは不要なため含めない。

.pre-commit-config.yaml

  - repo: local
    hooks:
      - id: pyfltr
        name: pyfltr
        entry: uv run --frozen pyfltr fast
        types_or: [python, markdown, toml]
        require_serial: true
        language: system

ポイント:

• --frozen: uv runが依存解決を再実行せずuv.lockをそのまま使うようにする。サプライチェーン攻撃対策として、git commitの起動経路がシェル環境変数（UV_FROZEN）に依存しなくても確実にfrozen動作させるための保険。
• fast: mypy / pylint / pytestなど重いコマンドを除外した高速サブセット。Formatterがファイルを修正しただけではフックを失敗と判定しない。pre-commitは対話的フックのため速度を優先する。
• types_or: [python, markdown, toml]: PythonだけでなくMarkdown変更時にmarkdownlint / textlintを、TOML変更時にuv-sortを実行する。
• require_serial: true: pyfltr自身が内部で並列化するため、pre-commit側での多重起動を避ける。

.markdownlint-cli2.yaml

markdownlint-cli2が読み込む設定ファイル。$schema を指定してエディタ補完を有効化する。 日本語ドキュメントでは行長制限が実用的でないため、line-length チェックのみ無効化している。

$schema: https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/v0.20.0/schema/markdownlint-cli2-config-schema.json
config:
  line-length: false

.textlintrc.yaml

textlintで技術文書向けの複数プリセットと誤用語チェックを併用する例。 preset-ja-technical-writing / preset-jtf-style / ja-no-abusage を組み合わせる。 原則はデフォルトルールに従い、誤検出や技術文書に合わないルールのみ個別に無効化する。

無効化しているルールと理由は以下の通り。

• ja-no-mixed-period: ラベル型見出し（「ポイント」「例」など）が多用されるため
• no-doubled-joshi: 技術文書で避けられない自然な助詞連結が頻出するため
• sentence-length: 既定の100文字制限を120文字へ緩和する（完全無効化はしない）
• no-mix-dearu-desumasu: 本文・リストを常体（である調）に固定する（プリセット既定は本文が敬体）
• 1.1.3.箇条書き: 箇条書きに句点を付けない方針のため
• 4.2.7.コロン(：): コロン終端のラベル記法を多用するため

対応するtextlint-packagesの設定例はtextlint-packagesのカスタマイズを参照。

rules:
  preset-ja-technical-writing:
    # ラベル型見出し ("ポイント:", "例:" など) が多用されるため、文末句点の強制を無効化する
    ja-no-mixed-period: false
    # 技術文書における自然な助詞連結 (「〜かどうかを検討するか」など) が頻出するため無効化する
    no-doubled-joshi: false
    # 引用文や詳細な技術説明で100文字超過が避けられないため緩和する
    sentence-length:
      max: 120
    # ドキュメントを常体（である調）で統一する方針のため
    no-mix-dearu-desumasu:
      preferInHeader: ""
      preferInBody: "である"
      preferInList: "である"
      strict: false
  preset-jtf-style:
    "1.1.3.箇条書き":
      shouldUsePoint: false # 箇条書きは「。」をつけない
    # コロン終端のラベル記法を多用するため無効化する
    "4.2.7.コロン(：)": false
  ja-no-abusage: true

textlint-packagesのカスタマイズ

追加のtextlintプリセットを使う場合は textlint-packages にパッケージ名を列挙する（pnpx / npx起動時に --package / -p として展開される）。

[tool.pyfltr]
textlint-packages = [
    "textlint-rule-preset-ja-technical-writing",
    "textlint-rule-preset-jtf-style",
    "textlint-rule-ja-no-abusage",
]

共通のコマンドライン引数を追加したい場合は textlint-args を使う。 lint専用のオプション（--format compact など）は textlint-lint-args に分離する。

[tool.pyfltr]
textlint-args = []
textlint-lint-args = ["--format", "compact"]

旧版のtextlint-args = ["--format", "compact", ...]をそのまま引き継いでもクラッシュしない。 pyfltrはpyfltr fix実行時にfix段階の起動コマンドから--formatペアを自動除去するため。 ただし新規設定ではtextlint-lint-argsに書くことを推奨する。

CI

GitHub ActionsでpyfltrをPythonバージョンのmatrixで実行する構成の例。

env:
  # 開発モード: DeprecationWarningなどの隠れた問題を早期検出する
  PYTHONDEVMODE: "1"
  # サプライチェーン攻撃対策: uvがlockfileを常に尊重する
  UV_FROZEN: "1"

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12", "3.13", "3.14"]
    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@v8
        with:
          python-version: ${{ matrix.python-version }}
          enable-cache: true

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: "lts/*"

      - name: Setup pnpm
        uses: pnpm/action-setup@v5
        with:
          version: latest

      - name: Configure pnpm security
        run: pnpm config set minimum-release-age 1440 --global

      - name: Install dependencies
        run: uv sync --all-extras --all-groups

      - name: Test with pyfltr
        run: uv run pyfltr ci

      - name: Prune uv cache for CI
        run: uv cache prune --ci

ポイント:

• env.PYTHONDEVMODE: "1": Pythonの開発モードを有効化する。DeprecationWarningの表示や各種デバッグチェックが有効になり、隠れた問題を早期に検出できる。
• env.UV_FROZEN: "1": サプライチェーン攻撃対策として、ワークフロー全体でuv sync/uv runがuv.lockを尊重するよう強制する。意図しない再resolveでロックファイルが書き換わるリスクを抑える。
• actions/setup-node + pnpm/action-setup: markdownlint-cli2とtextlintをpnpx経由で呼び出すため、PythonだけでなくNode.js環境も必要になる。
• pnpm config set minimum-release-age 1440: サプライチェーン攻撃対策として、公開から24時間（1440分）未満のパッケージのインストールを拒否する。
• uv sync --all-extras --all-groups: pyfltrを含むdev依存をすべて同期し、uv run pyfltrから対応ツール群を解決できるようにする。UV_FROZEN=1下でもuv.lockをそのまま使うため問題なく動作する。
• uv cache prune --ci: CIキャッシュを軽量化するための後処理。