Python Document String (Docstring) は、モジュール、関数、クラス、またはメソッドの最初のステートメントである文字列リテラルです。
How to Define Python Docstring?
Pythonのdocstringは三重のダブルクォート(“”)で囲まれます。
docstringを定義する例をいくつか見てみましょう。
1. Python 関数 Docstring の例
def multiply(a, b):
"""This method multiplies the given two numbers.
Input Arguments: a, b must be numbers.
Returns: Multiplication of a and b.
"""
return a * b
|
2. PythonクラスDocstringの例
class Employee:
"""Employee class is used to hold employee object data.
Methods:
__init__(self, emp_id, emp_name)
print()
"""
def __init__(self, emp_id, emp_name):
"""Employee Class Constructor to initialize the object.
Input Arguments: emp_id must be int, emp_name must be str
"""
self.id = emp_id
self.name = emp_name
def print(self):
"""This method prints the employee information in a user friendly way."""
print(f'Employee[{self.id}, {self.name}]')
|
3. Python モジュールの Docstring の例
上記の関数とクラスが docstrings.py ファイルに定義されているとします。
すべてのPythonスクリプトはモジュールでもあります。
このモジュールのdocstringは次のように定義できます。
"""This module shows some examples of Python DocstringsClasses: EmployeeFunctions: multiply(a, b)""" |
How to Access Python Docstrings?
docstringの値には、特別な属性(attribute)である “we can access “があります。
それでは、上記で定義されたdocstringの値にアクセスする方法を説明します。
1. Python 関数 Docstring へのアクセス
print(multiply.__doc__)
|
結果は以下の通りです。
print(Employee.__doc__)
print(Employee.__init__.__doc__)
print(Employee.print.__doc__)
|
2. Python クラスとメソッドの文字列へのアクセス
$ python lsdocstrings.py$ python $ python python3.7
Python 3.7.3 (v3.7.3:ef4ec6ed12, Mar 25 2019, 16:52:21)
[Clang 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> >>> import docstrings
>>> >>> docstrings.__doc__'>>> >>> docstrings.Employee.__doc__'Employee class is used to hold employee object data.
>>> >>> >>> docstrings.multiply.__doc__'This method multiplies the given two numbers.
>>> >>> >>> docstrings.Employee.print.__doc__
'This method prints the employee information in a user friendly way.'>>> |
結果は以下の通りです。
def reverse_str(s):
"""Reverses the input string and returns it."""
pass
|
3. PythonモジュールDocstringへのアクセス
docstringsモジュールをインポートする必要があります。
そして、そのDocstringの値には _doc___attribute を使ってアクセスすることができます。
print()文が実行されないように、docstringsモジュールをインポートする前に、上記のprint文をコメントアウトしています。
Python ワンライナー Docstring
- Python の docstring が一行で定義されている場合、one-liner docstring と呼びます。
- 開始引用符と終了引用符が同じ行にある。
- docstringの値の前後に空白行はありません。
- docstringの末尾にピリオドを打つのがベストプラクティスです。
- 多くのことを指定する必要がない、小さなユーティリティ関数に最適です。
- 関数の詳細と出力を指定するために、意味のあるdocstringを提供します。例えば
Python 複数行のDocstring
- Docstring の値が複数の行にまたがる場合、複数行の docstring と呼ばれます。
- 複数行の docstring のベストプラクティスは、最初にサマリー行を置き、その後に空白行を置き、さらに詳細な説明をすることです。
- 複数行のdocstringのベストプラクティスは、要約行で始まり、空白行の後に詳細な説明が続くことです。
- 複数行のdocstring全体は、その最初の行で引用符と同じようにインデントされます。
Python Docstring のベストプラクティス
- Python スクリプトの docstring は、そのスクリプトの使用方法を指定する必要があります。これは、スクリプトを実行する際に、パラメータがなかったり、間違っていたりした場合に表示されるべきものです。
-
- Pythonモジュールのdocstringは、すべてのクラス、関数、例外、他のモジュールへの依存をリストアップする必要があります。
-
- Python関数のdocstringは、動作、入力引数、戻り値の型、および例外を指定する必要があります。もし、その関数を呼び出すことができる特定の制限がある場合は、関数docstringで指定する必要があります。
-
- クラスの docstring は、すべてのメソッドと属性を列挙すること。スーパークラスから継承している場合は、その詳細を記載すること。
-
- クラスのメソッドがスーパークラスのメソッドをオーバーライドしている場合は、その旨を明記すること。
- Pythonは大文字と小文字を区別します。そのため、関数の引数名は関数定義と全く同じにすること。
なぜ Python Docstring Guidelines に従うべきなのか？
Pythonのdocstringは “guidelines “でアクセスすることができます。
docstringを解析して、プロジェクトのモジュール、クラス、関数のドキュメントを生成するシステムを構築するのはとても簡単です。
そのため、PEP-257で示されたdocstringのガイドラインに従うとよいでしょう。
Docstring を複数行のコメントに使うことはできますか？
docstring が複数行のコメントを提供するために悪用される例を多く見てきました。
Pythonは複数行のコメントをサポートしていません。
コメントを複数行に分散させたい場合は、各行をハッシュ文字で始めてください。
Python Docstringを悪用しないようにしましょう。