【Python】Ruffでdocstringsのスタイルをチェックする

※記事内に商品プロモーションを含むことがあります。

はじめに

PythonのリンターRuffのpydocstyleプラグインを使い、docstringsのスタイルをチェックする方法を調査しました。

検証環境は以下の通りです。

Windows 10 Home 22H2
Python 3.13.1
Ruff 0.11.0

Ruffとpydocstyle

RuffはPythonのリンター機能やフォーマッタ機能を持つツールです。
リンターとはソースコードの潜在的なバグやコーディングスタイルの違反がないかチェックするツールで、フォーマッタとはコーディングスタイルに合わせてコードを整形するツールです。

pydocstyleとは、もともとPythonのdocstringsがルールに合わせて記述されているかチェックするツールとして開発されていました。
しかし、2023年に開発が終了し、現在はRuffに1オプションとして組み込まれています。

pydocstyle機能を使う

Ruffの以下のコマンドを実行すると、pydocstyleのプラグインを使ってdocstringsのスタイルをチェックできます（設定ファイルを使用すると--select Dオプションは省略可能）。
スタイルの違反がある場合、エラーの内容とともに表示されます。

1

ruff check --select D foo.py

foo.pyは対象のスクリプトファイルやフォルダに変更して下さい。

さらに--fixオプションを付けると、自動で修正可能な違反については修正されます。

1

ruff check --fix --select D foo.py

ファイルを変更せずに差分をターミナルに表示したい場合、以下のように--diffオプションを付けます。

1

ruff check --diff --select D foo.py

pydocstyle機能の設定

Ruffの設定をpyproject.tomlに記述することができます。例を以下に示します。

1
2
3
4
5
6


[tool.ruff.lint]
select = ["D"]
ignore = ["D415"]

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

selectはRuffのリンター機能で有効にするプラグインを示します。
そのため、select = ["D"]とするとpydocstyle以外のリンター機能は無効になります。
デフォルトのリンター機能を有効にしたままpydocstyleを追加する場合、select = ["E4", "E7", "E9", "F", "B", "D"]として下さい。

ignoreには無効にするエラー番号を定義します（複数定義可能）。

conventionには、docstringsのスタイルを指定します。
"google" | "numpy" | "pep257"から選択します。
指定するconventionによって、一部ルールの有効・無効が変化します。

pydocstyleのエラー番号

Ruffのpydocstyle機能には約50個のルールが定義されています。
いずれもD203のように、Dと100～419の3桁の整数で表現されます。
これらは以下のように百の位でグループ分けされています。

D100番台：docstringの未定義
D200番台：docstring内や前後の改行・インデントに関連
D300番台：docstringを囲むトリプルクォート"""に関連
D400番台：句読点や大文字・小文字、コロンなどの記法に関連

先ほどignoreで無効にするエラー番号を指定しましたが、例えばD4のように指定すると、D400やD415などD4から始まるエラーは全て無効になります。
D41としても同様に、D41から始まるエラーは全て無効になります。

pydocstyle機能のエラー番号の一覧は以下にあります。

Rules - Ruff

D100番台を見ると、パブリックメソッドにはdocstringが必要ですが、プライベートメソッドには必須ではありません。

また、docstringを日本語で書く場合、無効にすることを検討したいルールには以下があります。

D400: docstringの1行目が.で終わっていない（NumPy, pep257スタイルのみ有効）
D415: docstringの1行目が., !, ?などで終わっていない（Googleスタイルのみ有効）

参考

【Python】Linter・Formatter決定版 Ruffの詳細設定