Pythonコードのコメントと題した以前の記事ですでに指摘したように、ソフトウェア開発のプロセスにおいてドキュメントは不可欠であり、継続的なステップであることを学びました。
上記の記事では、Pythonコードのドキュメントをコード内から作成する方法である、docstringsの概念を簡単に紹介しました。
このコード内ドキュメントは、モジュール、クラス、メソッド、関数に対して機能し、すべてのPythonコードのドキュメントを作成するための好ましい方法です。
この記事でこのテーマについて詳しく見ていきましょう。
docstringを正しく書くための規約や、実際に使われているさまざまなdocstringフォーマット、そしてPythonスクリプトからdocstringにアクセスする方法について説明します。
そして最後に、docstringを利用したり評価したりするためのツールを紹介します。
Docstringsに飛び込む
docstring という用語は documentation string の略で、ソースコード、つまり関数、モジュール、クラスが何を行うかを記述します。
関数、モジュール、クラス、メソッドの頭のすぐ下に、通常のコメントとして追加されます。
典型的な例は次のようなもので、温度、湿度、風速を測定するモバイルセンサーなどの測定デバイスを扱うPythonのクラスから引用しています。
リスト1: 1行のdocstringを含むPythonのコード
class Device:
def __init__(self, temp=0.0):
"Initialize the Device object with the given temperature value."
self.set_temperature(temp)
return
docstringを正しく書くためには、いくつかの規則に従わなければなりません。
これらの規約は、Python Enhancement Proposalの略であるPEP 257でより詳細に説明されています。
1行の文書文字列
リスト 1 で使用されている docstring は、シンプルにするために 1 行のコメントとして用意されています。
docstring のテキストを大文字で始め、ピリオドで終わらせることに注意してください。
コードは通常、書かれたものよりも頻繁に読まれるという事実に基づいて、文書化された構造がどのように行われるかではなく、コマンドの一種として何を行うかを記述することが推奨されます。
呼び出し側にどのような値が返されるかに言及することは、関数やメソッドの結果を理解するのに役立ちます。
リスト1のメソッドのdocstringは、シングルダブルクオートで囲まれていることにお気づきでしょうか。
Pythonは引用符の始まりと終わりが同じであれば、非常に寛容で、3つのシングルクオートを使っても、3つのダブルクオートを使ってもかまいません。
def get_temperature(self):
'''Return the stored temperature value as a float value.'''
return self.temperature
def set_temperature(self, temp):
"""Set the temperature value."""
self.temperature = float(temp)
return
終了引用符が開始引用符と同じ行にあることを確認してください。
また、docstringのテキストの前後に空行を追加しないでください。
複数行のDocstring
さらに、docstringは複数行のコメントとして記述することもできます。
複数行のコメントを使用する場合、2つのことが変わります – docstringのカプセル化は、トリプルシングルまたはダブルクォートで書かなければなりません、そしてdocstringの構造自体は、テキスト全体に割り当てられる深い意味を持ちます。
docstringの最初の行は、抽象、または短い説明として解釈され、一行のdocstringと同じように書くことが推奨されています。
その後に続く空行は、アブストラクトとその下の完全な説明の間のセパレーターとして解釈されます。
リスト 2 はリスト 1 を拡張したもので、後述するように説明文に特定の書式を使用してはいません。
リスト2: 複数行の docstring
def set_temperature(self, temp):
"""Set the temperature value.
The value of the temp parameter is stored as a value in
the class variable temperature. The given value is converted
into a float value if not yet done.
"""
self.temperature = float(temp)
return
自動インデックス作成ツールはこれらのテキストを評価するため、ブロックオーダーに従うことを強くお勧めします。
Docstringの形式
あなたは、バインディングのdocstringフォーマットは一つしかないと思っているかもしれません。
残念ながら、1つ以上の形式があり、これらの形式はすべて複数行のdocstringで動作します。
- reStructured text (reST) / Sphinx: これはPythonの公式ドキュメンテーションの標準です。これは軽量マークアップ言語reStructured text (reST)の構文を使用しており、Markdownと使い方が似ています。
- Google Docstrings。Googleのdocstringのスタイル
- NumPy/SciPy Docstrings: NumPy/SciPy Docstrings: ReStructured Text (reST) と Google Docstrings を組み合わせたものです。Sphinxでも使用可能で、かなり冗長です。
リスト3は、reSTを使ったdocstringの書き方を示しています。
使用できるキーワードは以下の通りです。
-
paramとtypeです。パラメータとその変数の型 -
returnとrtype: 関数やメソッドの戻り値や型を指定する。 -
...also::を参照してください。参考文献 -
... notes::: 注意書きを追加する -
... warning::: 警告を追加
エントリーの順番は固定ではありませんが、プロジェクト全体を通して同じ順番になるようにしましょう。
seealso、notes、warning`のエントリはオプションです。
リスト3: reSTデータを含む複数行のdocstring
def set_temperature(self, temp):
"""Set the temperature value.
The value of the temp parameter is stored as a value in
the class variable temperature. The given value is converted
into a float value if not yet done.
:param temp: the temperature value
:type temp: float
:return: no value
:rtype: none
"""
self.temperature = float(temp)
return
Googleのdocstringを理解するために、リスト4を見てみましょう。
このフォーマットはより密度が低く、より多くの水平スペースが使われています。
リスト4: 複数行の docstring (Google フォーマット)
def set_temperature(self, temp):
"""Set the temperature value.
The value of the temp parameter is stored as a value in
the class variable temperature. The given value is converted
into a float value if not yet done.
Args:
temp (float): the temperature value
Returns:
no value
"""
self.temperature = float(temp)
return
最後に、リスト5は、同じメソッドをNumPyのdocstringフォーマットで表示しています。
縦方向のスペースがより多く使われ、元のフォーマットよりも読みやすくなっています。
リスト5：複数行の docstring (NumPy フォーマット)
def set_temperature(self, temp):
"""Set the temperature value.
The value of the temp parameter is stored as a value in
the class variable temperature. The given value is converted
into a float value if not yet done.
Parameters
----------
temp : float
the temperature value
Returns
-------
no value
"""
self.temperature = float(temp)
return
Docstringsへのアクセス
Pythonの対話型ヘルプシステムでは、docstringは __doc__ 属性を介して利用できます。
リスト 6 は、ドキュメント文字列にアクセスするためのコードの使い方を示しています。
この例では、リスト 1 をベースにしています。
リスト6: docstringの値にアクセスする
>>> def set_temperature (self, temp):
... """Set the temperature value."""
... temperature = float(temp)
... return
...
>>> print(set_temperature.__doc__)
Set the temperature value.
Docstringsを使用するためのツール
Sphinx, Epydoc, Doxygen, PyDoc, pdoc, and the autodoc extension for Sphinxなど、docstringからドキュメントを自動生成するツールは数多くあります。
それらのほとんどは、ローカルで使うためのHTMLドキュメントを生成します。
PydocはPythonの配布物の一部で、モジュールに関する情報をコンソールやウェブブラウザ、またはHTMLドキュメントとして出力します。
Pythonシェルでは、モジュール、関数、クラス、メソッドについてより詳しく知るために、 help() 関数を使用します。
図1は、リスト1のdocstringをPythonのヘルプシステムで表示したものです。
図1: 抽出されたdocstring
ローカルにインストールされているすべてのPythonモジュールの組み込みドキュメントを見るには、ローカルのWebサーバーとしてpydocを実行します。
パラメータ -p に続けてポート番号を指定すると、指定されたポートを使ってアクセスできる小さなウェブサーバを起動します。
リスト 7 はポート 1234 で pydoc サーバーを起動し、図 2 は pydoc によって抽出され利用可能になった情報を示しています。
リスト 7: pydoc を Web サーバーとして実行する
$ pydoc3 -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server>
...
図 2: ローカルの Web サーバー上で抽出された docstring
結論
ドキュメンテーションのガイドラインに従うことは、あなたや他の人がソースコードを今日、そして後日理解するのに役立ちます。
Docstringsはそれ以外にも、例えばマニュアルの生成などにも使われます。
この考えを念頭に置くことで、より大きなスケールでのプロジェクトが可能になります。