【Python】ドキュメンテーション文字列の使い方【docstring】

この記事では、Pythonのドキュメンテーション文字列の使い方を解説します。

関数やクラスを使うときに「あれ？この関数ってどんなだっけ？」と思ったことはありませんか？普段使わないような関数はどんな機能を持っていたか忘れてしまいます。

なので、ドキュメンテーション文字列を定義して関数やクラスの目的や機能がわかるように説明文を記述しておきましょう。

ドキュメンテーション文字列を用いてテストを行うこともできます。

それでは、ドキュメンテーション文字列の使い方を見ていきましょう！

ドキュメンテーション文字列の書き方
ドキュメンテーション文字列の確認
doctestでdocstringを検証する
まとめ

ドキュメンテーション文字列の書き方

ドキュメンテーション文字列は、クラスや関数内の定義の先頭に複数行文字列を記述することで定義できます

# 関数
def func():
    """
    """

# クラス
class Cls:
    """
    """

次に記述する内容を見ていきましょう。

1行目

1行目には「目的」や「機能」を簡潔に記述します。

書き方は「大文字」で始まり「ピリオド」で終わらせる必要があります。しかし、別に日本語で書いてもエラーになったりしません。
※ ドキュメンテーション文字列には慣習的な書き方はありますが決まりはありません。

def func():
    """Test.
    """


class Cls:
    """テスト.
    """

2行目以降

さらに記述することがあるなら2行目は空白にして3行目から呼び出し規約や副作用について書きます。

def func():
    """Test.
    
    not do anything.
    """


class Cls:
    """テスト.
    
    何も定義されていません
    """

参考ドキュメンテーション文字列 — Python 3.9.0 ドキュメント

ドキュメンテーション文字列の確認

ドキュメンテーション文字列は__doc__属性に文字列として格納されます。

def func():
    """Test.
    
    not do anything.
    """

class Cls:
    """テスト.
    
    何も定義されていません
    """


print(func.__doc__)
# Test.
#     not do anything.


print(Cls.__doc__)
# テスト.
#     何も定義されていません

もちろん、組み込み関数などにも使えます。

print(abs.__doc__)
# Return the absolute value of the argument.

doctestでdocstringを検証する

doctestモジュールを使うことでドキュメンテーション文字列に記述した対話実行例の通りに動作するか検証することができます。

対話実行例の書式

docstring中に関数の呼び出しと期待される出力を記述します。3行目の>>>div(4, 2)が呼び出しで、4行目の2.0が期待される出力です。

def div(a, b):
    """
    >>> div(4, 2)
    2.0
    """
    return a / b

また、期待される出力にエラーも記述することができます。

def div(a, b):
    """
    >>> div(4, 2)
    2.0
    >>> div(0, 0)
    Traceback (most recent call last):
        ...
    ZeroDivisionError: division by zero
    """
    return a / b

doctestをチェックする

doctestを試すには同モジュール内の最後に以下のコードを記述し、

if __name__ == "__main__":
    import doctest
    doctest.testmod()

コマンドラインから直接実行します。

$ python モジュール名.py

テストしてみる

実行例が成功する場合

実行例が正しい場合のdocstringを試してみます。

div.py

def div(a, b):
    """
    >>> div(4, 2)
    2.0
    """
    return a / b


if __name__ == "__main__":
    import doctest
    doctest.testmod()

このコードをコマンドラインから実行します。

$ python div.py

実行例が成功すると何も表示されません。

実行例が失敗する場合

実行例が間違っている場合のdocstringを試してみます。

div.py

def div(a, b):
    """
    >>> div(4, 2)
    2
    """
    return a / b


if __name__ == "__main__":
    import doctest
    doctest.testmod()

このコードを実行すると、以下のような出力がされます。

$ python div.py
**********************************************************************
File "div.py", line 5, in __main__.div
Failed example:
    div(4, 2)
Expected:
    2
Got:
    2.0
**********************************************************************
1 items had failures:
   1 of   1 in __main__.div
***Test Failed*** 1 failures.

docstringに記述した期待される出力がExpectedで実際に出力された値がGotです。

参考doctest—対話的な実行例をテストする—Python 3.9.0 ドキュメント