はじめに #
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オプションは省略可能）。
スタイルの違反がある場合、エラーの内容とともに表示されます。
ruff check --select D foo.py
foo.pyは対象のスクリプトファイルやフォルダに変更して下さい。
さらに--fixオプションを付けると、自動で修正可能な違反については修正されます。
ruff check --fix --select D foo.py
ファイルを変更せずに差分をターミナルに表示したい場合、以下のように--diffオプションを付けます。
ruff check --diff --select D foo.py
pydocstyle機能の設定 #
Ruffの設定をpyproject.tomlに記述することができます。例を以下に示します。
[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機能のエラー番号の一覧は以下にあります。
D100番台を見ると、パブリックメソッドにはdocstringが必要ですが、プライベートメソッドには必須ではありません。
また、docstringを日本語で書く場合、無効にすることを検討したいルールには以下があります。
- D400: docstringの1行目が
.で終わっていない（NumPy, pep257スタイルのみ有効） - D415: docstringの1行目が
.,!,?などで終わっていない（Googleスタイルのみ有効）
