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

Pythonのdocstringとは？

docstringとは、Pythonで関数やクラスなどのオブジェクトを定義するときに、そのオブジェクトに関するコメントを書くための文法規則のことです。docstring内では、関数やクラスの説明、引数と戻り値の説明、例などを記述することができます。docstringはドキュメンテーション文字列とも呼ばれます。

docstringは、Sphinxのようなドキュメンテーションジェネレータの解析に使われたり、IDEやエディタが使用方法のヘルプとして参照したりするなど、特定のフォーマットで記述することによってコーディングに役立つ機能になります。

関数とクラスでのdocstringの基本的な書き方

docstringはシングルクォートかダブルクォートを三つ続けたもの（'''もしくは"""）で囲むことで記述できます。docstringは関数やクラスの定義の直後に記述し、1行でも複数行でも書くことができます。

関数やクラス内の処理よりも先に記述しなければdocstringとして扱われないので注意してください。

# 関数とクラスでのdocstringの基本的な書き方

# docstringを複数行書く場合
def print_function(string):
    """ここがdocstringになります
    1行目
    2行目
    3行目
    """
    print(string)


# 1行しか使わない場合
def print_function(string):
    """ここがdocstringになります"""
    print(string)


# クラスでも同様に定義できる
class sample_class:
    """クラスでもdocstringを
    定義できます
    """
    pass


# docstringは関数などの処理よりも先に記述する必要がある
def print_function(string):
    print(string)
    """これはdocstringとして扱われない"""

docstringの表示方法（__doc__属性）

docstringは、記述した関数やクラスの__doc__属性に文字列として格納されています。そのため、docstringを確認したければ、__doc__属性を呼び出せば良いです。

ためしに、先ほど定義した関数とクラスのdocstringを呼び出してみます。

# __doc__属性にdocstringが格納されている

print(print_function.__doc__)
# ここがdocstringになります
#     1行目
#     2行目
#     3行目


print(sample_class.__doc__)
# クラスでもdocstringを
#     定義できます

doctestでdocstringのテストを行う

標準モジュールのdoctestでは、docstringの中に記述された入出力の例をもとに、テストを実行することができます。docstringが最新のものであるかどうかを確かめたり、プログラム全体の回帰テストとして利用することができます。

# doctest_sample_pass.py

# 正しく記述した場合のdoctestの例
def add(num1, num2):
    '''
    >>> add(10, 5)
    15
    >>> add(-3, -5)
    -8
    '''
    return num1 + num2

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

このファイル（doctest_sample_pass.py）を実行すると、何の出力もされません。doctestでは、テストが正常に終了すれば、アウトプットが出ないようになっています。

逆に、テストがうまくいっていない場合を試してみます。

# doctest_sample_fail.py

# 間違えて引き算を返した場合（テストで期待する値を返していない）
def add(num1, num2):
    '''
    >>> add(10, 5)
    15
    >>> add(-3, -5)
    -8
    '''
    return num1 - num2  # 戻り値を間違えて定義している

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

このファイルでは、足し算を期待したテストを書いているのに、引き算を戻り値として設定してしまっています。そのため、テストが失敗し、doctestによるエラーが表示されます。

doctest_sample_fail.pyを実行すると以下のような結果になります。

# doctestでテストが失敗したパターン

$ python doctest_sample_fail.py

File "doctest_sample_fail.py", line 7, in __main__.add
Failed example:
    add(10, 5)
Expected:
    15
Got:
    5
**********************************************************************
File "doctest_sample_fail.py", line 9, in __main__.add
Failed example:
    add(-3, -5)
Expected:
    -8
Got:
    2
**********************************************************************
1 items had failures:
   2 of   2 in __main__.add
***Test Failed*** 2 failures.

このように、docstringは関数やクラスの使い方のドキュメントとしてだけではなく、テストとしても利用することができます。Sphinxのような、docstringを活用した便利なツールもあるので、積極的に利用するようにしましょう。