Help us understand the problem. What is going on with this article?

GoogleスタイルのPython Docstringの入門

More than 1 year has passed since last update.

前置き

本記事では、Googleスタイル形式でのPython Docstringの書き方について必要最低限に絞って説明する。

これから、Python Docstringを覚えようとしているエンジニアの参考になれば、幸いである。

Python Docstringとは

Pythonにおけるクラスや、メソッド(関数)についての説明を記載したコメント文のこと。

Docstringは、__doc__という変数に格納されている。

以下は、printメソッドのDocstringを表示させたもの。

>>> print(print.__doc__)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file:  a file-like object (stream); defaults to the current sys.stdout.
sep:   string inserted between values, default a space.
end:   string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

自作したクラスや、メソッドにDocstringを記載しておくと、
IDE上に補足情報として表示させることや、Sphinxを使用して、ソースコードの仕様書を自動作成することが可能になる。


Sphinxとは

Sphinxは、reStructuredTextという形式で記載されたテキストををHTML、
PDFやepubなどの様々な形式へ変換することができるOSSのドキュメント生成ツール。

Pythonの公式ドキュメントはSphinxを使って書かれている。

Sphinxを用いると、Pythonのソースコード上からPython Docstringのコメント文を抽出して、
ソースコード仕様書を自動生成することが可能。

Sphixを使用した、Docstringの活用方法は下記を参照。
https://qiita.com/futakuchi0117/items/4d3997c1ca1323259844


Googleスタイル

Googleが提唱したDocstringの記法の一つ。
Docstringの記法にはreStructuredTextスタイル,Numpyスタイル,Googleスタイルの3つがある。

本記事では、Googleスタイルについて説明する。


GoogleスタイルのPython Docstring

Sphinxのサンプルコード

SphinxのHPから、Googleスタイル形式で記載されたサンプルコードを閲覧することができる。

上記のソースコードをSphinxでhtmlに変換すると下記のようになる。


日本語のサンプルコード

先程のサンプルコードを元に、要点のみを抜粋した日本語のサンプルコードと、ソースコードをSphinxでhtmlに変換したものを下記に記す。

#!/usr/bin/python
# -*- coding: utf-8 -*-
"""モジュールの説明タイトル

     * ソースコードの一番始めに記載すること
     * importより前に記載する

Todo:
   TODOリストを記載
    * conf.pyの``sphinx.ext.todo`` を有効にしないと使用できない
    * conf.pyの``todo_include_todos = True``にしないと表示されない

"""

import json
import inspect

class testClass() :
    """クラスの説明タイトル

     クラスについての説明文

    Attributes:
        属性の名前 (属性の型): 属性の説明
        属性の名前 (:obj:`属性の型`): 属性の説明.

    """

    def print_test(self, param1, param2) :
        """関数の説明タイトル

         関数についての説明文

        Args:
            引数の名前 (引数の型): 引数の説明
            引数の名前 (:obj:`引数の型`, optional): 引数の説明.

        Returns:
           戻り値の型: 戻り値の説明 (例 : True なら成功, False なら失敗.)

        Raises:
            例外の名前: 例外の説明 (例 : 引数が指定されていない場合に発生 )

        Yields:
           戻り値の型: 戻り値についての説明

        Examples:

            関数の使い方について記載

            >>> print_test ("test", "message")
               test message

        Note:
            注意事項などを記載

        """
        print("%s %s" % (param1, param2) )

if __name__ == '__main__':

    test_object = testClass()
    test_object.print_test("test", "message")

基本的なコメントの書き方

  • コメントを複数行のコメントブロック「"""」で囲む
  • 「"""」の右隣にタイトルを記載する
  • Docstringの対象となるのは、 モジュール、クラス、関数(メソッド)の3つ

モジュールの記載方法

ソースコードの冒頭に、ソースコード全体つまり、モジュールの説明を記載する。

注意点としては、コメント文を除いたソースコードの一番始めに記載する必要がある。
※ importより前に記載する必要がある。

#!/usr/bin/python
# -*- coding: utf-8 -*-
"""モジュールの説明タイトル

   モジュールの説明

"""

クラスの記載方法

下記のように、クラス定義の下の行に記載する。

class testClass() :
    """クラスの説明タイトル

     クラスについての説明文

    """

関数(メソッド)の記載方法

下記のように関数定義の下の行に記載する。

def print_test(self, param1, param2) :

    """関数の説明タイトル

     関数についての説明文
    """


セクションの説明

Googleスタイルでは、Attributes, Args、Returns、Yieds、Raises、Examples、Note、Todoという用途別に定義されたセクションがある。

Attributesセクション

クラスの属性の型、名前など、クラスの属性の説明を記載する。

Attributes:
    属性の名前 (属性の型): 属性の説明
    属性の名前 (:obj:`属性の型`): 属性の説明.

Argsセクション

引数の名前、型、optional(省略可能)かどうかなど、引数の説明を記載するセクション。

  • インスタンスを示すselfは、Argsセクションには記載せず、省略する
  • 省略可能な引数は、下記のようにoptionalを記載する
  • Sphinxでhtmlファイルに変換すると、Args → Parametersに変更される
Args:
    引数の名前 (引数の型): 引数の説明
    引数の名前 (:obj:`引数の型`, optional): 引数の説明.

Returnsセクション

retrun文を使用した関数の戻り値を記載するセクション。

Returns:
   戻り値の型: 戻り値の説明 ( : True なら成功, False なら失敗.)

Yieldsセクション

yeild文を使用した関数の戻り値を記載するセクション。

Yields:
   戻り値の型: 戻り値についての説明

Raisesセクション

例外処理に対する説明を記載するセクション。

Raises:
    例外の名前: 例外の説明 (例 : 引数が指定されていない場合に発生 )

Examplesセクション

関数、クラスの実行例について記載するセクション。

Examples:
    関数の使い方について記載

    >>> print_test ("test", "message")
       test message
  • Examplesだけでなく、Exampleでも可
  • クラス、メソッド以外の箇所で使用する場合は、下記のように::でコードブロックにする必要がある
  • \はエスケープ文字なので、コードブロック中に\を表示させる場合、\\と記載する
Example:
    関数の使い方について記載

    ::

        $ python main.py \\
            "arg1" \\
            "args2" \\

Noteセクション

注釈について記載するセクション。
例えば、「このコードは、Python2系では動作しません」などのような注意事項を記載するといいだろう。

Note:
   注意事項などを記載

Todoセクション

Todoリストを記載するためのセクション。
実装予定の処理など、後から実施する作業などはここに記載する。

Todo:
   TODOリストを記載
    * conf.pyの``sphinx.ext.todo`` を有効にしないと使用できない
    * conf.pyの``todo_include_todos = True``にしないと表示されない

Shphixで変換後のドキュメントに表示させるには、
Sphinxの設定ファイルconf.pyを編集し、下記のように、
拡張機能[sphinx.ext.todo]を有効にする必要がある。

extensions = [ 'sphinx.ext.todo' ]

todo_include_todos = True
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away