＠IT
AI IoT

［Python入門］docstringの書き方：Python入門

docstringを使うと、Pythonのコードを書きながら、同時にそのドキュメントも作成できる。関数のdocstringを例にその基本的な書き方を見ていく。

» 2019年12月06日 05時00分公開

[かわさきしんじ，Deep Insider編集部]

連載目次

　Pythonの関数を例に、docstringの書き方について見ていこう。

今回の目次

docstringとは

　本連載の第5回「文字列の基本」の「トリプルクオート文字列」でも触れたが、Pythonではシングルクオート「'」またはダブルクオート「"」を3つ連続して並べた三重引用符で文字列を表現できる。

　三重引用符で囲まれた「トリプルクオート文字列」は改行コードを含んだ文字列などを記述するのに便利に使えるが、これがよく使われる場面がもう一つある。それがdocstringと呼ばれる使い方だ（「ドックストリング」「ドキュメント文字列」「ドキュメンテーション文字列」などとも呼ばれる）。

　docstringは、関数などの仕様（例えば、何をして何を戻り値とするのか、呼び出すのに必要なパラメーターは何かなど）をその利用者に対して説明するために、その定義に埋め込んだ形で記述する。

　以下に関数にdocstringを記述した例を示す。三重引用符にはシングルクオートとダブルクオートのどちらを使ってもよいが、慣習的にdocstringではダブルクオートが使われているので以下ではダブルクオートを使用する。

def hello(whom):
"""Returns f'Hello, {whom}'."""
return f'Hello, {whom}'

docstringの例

　この関数の1行目にはトリプルクオート文字列を使って、docstringが書かれている（関数の動作自体は、パラメーターに受け取った値を含んだハローメッセージを返送するだけだ）。これを例にdocstringについて見ていこう。

docstringは文字列

　分かりきったことではあるが、docstringは文字列（文字列リテラル）である。つまり、上に示したdef文の本体では、冒頭に文字列リテラル（docstring）が1つ置かれ、次にreturn文があるということだ。文字列リテラルは式であり、式が単独でPythonのコード中に記述されると、それは式文として扱われる。このとき、その式文は値が評価され、文字列リテラルそのものが得られるが、それはどこにも保存されずに捨てられるだけだ。よって、単独のdocstringを書いてもコードの実行には特に支障がない。このことを利用して、Pythonの関数定義などに直接ドキュメントを記述しようというのがdocstringだ。

　なお、Pythonのドキュメント「関数定義」には「関数の本体の最初の文として現れる文字列リテラルは、その関数の __doc__ 属性に変換され、その関数のドキュメンテーション文字列になります」という注釈がある。__doc__属性とは、関数（やクラス、モジュールなど）が持つ属性の一つで、その仕様を説明するdocstringを保持するものだ。このことから、関数（やクラス）の冒頭に置かれた文字列リテラルはdocstringとして特別扱いされていることも分かる。

　少し試してみよう。上の関数を定義して、以下のコードを実行してみる。

help(hello)

hello関数のヘルプを表示

　これを実行すると次のようになる。

実行結果

　上に書いたdocstringがドキュメントとして利用されているのが分かるはずだ。では、次を実行するとどうなるだろう。

print(hello.__doc__)

hello関数の__doc__属性を表示

　この場合は次のようになる。

実行結果

　こちらでは、docstringとして記述した文字列だけが__doc__属性に含まれていることが分かる。

docstringの書き方

　上の例では、docstringは1行のみだった。トリプルクオート文字列はその内部に改行を含むようなときでも、それをうまく取り扱ってくれる。そのため、docstringを使って複数行のドキュメントを関数などに記述することも可能だ。実際、Pythonのドキュメント「ドキュメンテーション文字列」には、「最初の行は、常に対象物の目的を短く簡潔にまとめたものでなくてはなりません」「ドキュメンテーション文字列中にさらに記述すべき行がある場合、二行目は空行にし、まとめの行と残りの記述部分を視覚的に分離します」とある。

　1行のみのdocstringはその関数やメソッドが「何をするのか」や「何を返すのか」を「Do ……」や「Returns ……」のような形式で簡潔に書くことが求められている。関数のシグネチャ（関数名、パラメーターの名前と型、戻り値の型など）を書くのではなく、それが何をするのかを、使用者に分かるように明確に記述することが重要になる。このとき、docstringを囲む三重引用符は概要と同じ行に記述する。

　一方、複数行のdocstringでは、1行のみのdocstringと同じ概要行を書き、空行を挟んで、詳細な説明（その振る舞い、パラメーターに受け取る値として期待されるもの、戻り値などの説明）を続ける。このとき、docstringを始める三重引用符と概要行は同じ行に書いてもよいし、別々の行としてもよい。また、docstringを終える三重引用符は単独の行として記述する。

　docstringと関数本体の定義の間には改行を含めない。これは1行のみのdocstringでも、複数行のdocstringでも同様だ。

　1行のdocstringは既に見たので、以下に複数行のdocstringの例を示す。

def add(x, y):
    """Returns sum of x and y

    Parameters:
    ----------
    x : int
        operand1 of addition
    y : int
        operand2 of addition

    Returns:
    ----------
    int
        sum of x and y
    """
    return x + y

複数行のdocstring

　docstringの1行目では、このadd関数がする概要を示し、空行を挟んで、そのパラメーターと戻り値についての説明をしている。docstringを閉じる三重引用符は単独行として記述して、docstringと次の行の間には改行を含んでいない。

　ここで注意したいのは、Pythonは関数に渡される引数の型を前もってチェックすることがないため、add関数の2つのパラメーターには実際には整数でも浮動小数点数でも、文字列でも、リストでも同じ型同士の加算演算子をサポートしているものであれば何でも渡せることだ（なお、Pythonでも「型ヒント」と呼ばれる機構が導入され、パラメーターに受け取る値の型や、関数の戻り値の型などに関する情報をコード中に記述できるようになっている。ただし、Pythonの処理系自体はこれを強制せずに、関数に渡される値の型チェックなどは外部ツールで行われるようになっている。型ヒントについては、上級編の連載で取り上げる予定だ）。

　上のコードでは、docstringにはパラメーターに受け取れる値として整数（int）のみを記している。docstringの形で、コードを書いた側の意図を明確にできる。上のコードであれば、浮動小数点数を渡しても期待した値が得られるが、それはコードを書いた側の意図した動作ではない。他の人が書いたコードを利用して何か問題があったときに、docstringで述べられている仕様と自分がしていることに差があれば、それは呼び出す側の問題だと分かる。コード中にdocstringとしてドキュメントを記述することにはこのようなメリットもある。

PEP 8とPEP 257で定められているdocstringの形式

　PythonのコーディングスタイルガイドであるPEP 8と、docstringのスタイルガイドであるPEP 257では、これまでに述べてきたことを含めておおよそ次のようなことが定められている。

docstringの1行の長さは（半角英数字で）72文字まで
import文はモジュールのdocstring（やコメント）の直後に記述する
docstringに使用するトリプルクオート文字列では三重引用符として「"""」を利用する
外部に公開されているモジュール、関数、クラス、メソッドではdocstringを記述する
docstringには概要のみを記した1行バージョンと、さらに詳細な説明をしている複数行バージョンがある
複数行のdocstringでは、それを閉じる三重引用符「"""」は単独の行として記述する
1行のdocstringおよび複数行のdocstringの1行目では、それが何をするかを簡潔に記述する
複数行のdocstringでは、空行を挟んで、より詳細な説明を行う
docstringと関数定義やメソッド定義の本体の間には空行を挟まない
クラス冒頭にdocstringを記述したときには、docstringとメソッド定義の間に空行を挟む
複数行のdocstringは使い方を示すメッセージやリファレンスとしても有用なものとする
モジュールのdocstringは、それが公開するクラス、例外、関数などについて1行の説明を付けて一覧する
関数やメソッドのdocstringは、それが何をするのかの概要、パラメーター、戻り値、発生する例外などについて説明する
クラスのdocstringは、それが何をするクラスなのかの概要、外部に公開するメソッドやインスタンス変数などを記述する

　詳細は上記のPEP 8およびPEP 257を参照されたい。

　これらはおおまかな書き方を記したものであり、具体的なdocstringの書き方にはまた幾つかの流儀もある。例えば、先ほど記したadd関数のdocstringはNumPyのdocstringのスタイルに沿ったものである。これ以外にもGoogleで定められているdocstringのスタイルもある。これらについては以下を参照してほしい。

「Google Python Style Guide」の「3.8 Comments and Docstrings」
「numpydoc docstring guide」

まとめ

　今回はdocstringの基礎についてまとめた。docstringを使えば、Pythonのコードを書きながらそのドキュメントをコード内に含めることができるので、コードは書いたけど、ドキュメントを書くのが面倒といった事態を避けるのに役立つはずだ。ある程度の規模のプロジェクトで、複数人が自分のコードを利用する、あるいは外部のユーザーに自分のコードを使ってもらうというときには、他者（あるいは、後の自分）がそのコードを使うときにリファレンスとしても役立つようなdocstringを用意しておくのがよいだろう。

今回のまとめ

docstringは三重引用符「"""」で囲まれた文字列リテラルを使って、モジュール、関数、クラス、メソッドの振る舞いや関数／メソッドが受け取る値と戻り値をコードに記述したもの
docstringには1行だけのものと、複数行のものがある
1行だけのdocstringには、それが何をするのかの概要を簡潔に記述する
複数行のdocstringには、1行のだけのdocstringの内容に加えて、より詳細な説明を加える。概要行と詳細な説明の間には空行を入れる
PythonのコーディングスタイルガイドであるPEP 8と、docstringのスタイルガイドであるPEP 257では、docstringを記述すべきところ、docstringに記述する内容などについて定められている
具体的な記述の仕方にはNumPyのdocstringガイドやGoogle Python Style Guideで定められたものなど、幾つかの流儀がある