この記事では、Pythonの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 / bdoctestをチェックする
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 ドキュメント
まとめ
この記事では、Pythonのドキュメンテーション文字列について解説しました。
自作したクラスや関数にドキュメンテーション文字列を書いて、誰もが使いやすいコードを作成しましょう！また、使い方がイマイチわからない関数やクラスがあったら、ドキュメンテーション文字列を見て確認することができます。
それでは今回の内容はここまでです。ではまたどこかで〜( ・∀・)ﾉ