【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:
    """テスト.
    
    何も定義されていません
    """

ドキュメンテーション文字列は、docstringとも呼ばれる

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

ドキュメンテーション文字列は、__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中に関数の呼び出しと期待される出力を記述します。>>>div(4, 2)が呼び出しで、その下の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です。