web-dev-qa-db-ja.com

標準のPython docstringフォーマットは何ですか？

私はPythonでdocstringを書くいくつかの異なるスタイルを見たことがありますが、公式または「合意された」スタイルはありますか？

pythoncoding-styledocumentationdocstring
730
Noah McIlraith

フォーマット

他の記事が示したように、Pythonのdocstringはいくつかのフォーマットに従って書くことができます。しかしながら、デフォルトのSphinx docstringフォーマットは言及されておらず、 reStructuredText（reST） に基づいています。 that tuto で主なフォーマットについての情報を得ることができます。

ReSTが推奨されていることに注意してください PEP 287

Docstringの主なフォーマットは以下の通りです。

- エピテキスト

歴史的には javadoc のようなスタイルが普及していたので、 Epydoc のベースとして（Epytextフォーマットで）文書を生成するために採用されました。

例：

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- 残り

今日では、おそらくもっと普及しているフォーマットは reStructuredText （reST）フォーマットで、これは Sphinx によってドキュメントを生成するために使用されます。注：これはJetBrains PyCharmでデフォルトで使用されます（メソッドを定義した後に三重引用符を入力してEnterキーを押します）。それはPymentの出力フォーマットとしてもデフォルトで使われています。

例：

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

グーグルは彼ら自身の フォーマット を持っていますそれはしばしば使われます。また、Sphinx（つまり Napoleonプラグイン を使用）でも解釈できます。

例：

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

さらに もっと例を見る

- Numpydoc

NumpyはGoogleフォーマットに基づいてSphinxで使用可能な独自の numpydoc に従うことをお勧めします。

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

変換/生成

Pyment のようなツールを使用して、まだ文書化されていないPythonプロジェクトに文書文字列を自動的に生成したり、既存の文書文字列（複数の形式を混在させることができる）をある形式から別の形式に変換できます。

注：例は Pymentの資料 から取られています。

808
daouzli

Googleスタイルガイド には、優れたPythonスタイルガイドが含まれています。それは 読みやすいdocstring構文のための規約 を含み、これはPEP-257より良いガイダンスを提供します。例えば：

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

この Sphinxドキュメントチュートリアル で説明されているように、引数に型情報も含めるようにこれを拡張したいと思います。例えば：

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass
310
Nathan

文書化規則は PEP-257 にあり、PEP-8よりもはるかに詳細です。

しかし、docstringは他のコード分野よりはるかに個人的なようです。プロジェクトごとに独自の標準があります。

Docstringを常に含める傾向があります。なぜなら、それらは関数の使い方とそれが非常に素早く行うことを示す傾向があるからです。

文字列の長さに関係なく、物事の一貫性を保つことを好みます。インデントとスペーシングが一致しているときのコードの見方が好きです。つまり、私は以下を使います。

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

以上：

def sq(n):
    """Returns the square of n."""
    return n * n

そして長いdocstringの最初の行にコメントを残す傾向があります：

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

つまり、このように始まるdocstringはめちゃくちゃです。

def sq(n):
    """Return the squared result. 
    ...
222
Tim McNamara

明らかに誰もそれを言及しなかった：あなたはまた Numpy Docstring Standard を使うことができる。それは科学界で広く使われています。

Googleスタイルのドキュメント文字列を解析するためのNapolean sphinx拡張機能（@Nathanの回答で推奨）も、Numpyスタイルのドキュメント文字列をサポートし、両方の短い 比較 を作成します。

そして最後にそれがどのように見えるかについての考えを与えるための基本的な例：

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True
48
joris

PEP-8 は公式のpythonコーディング標準です。それは PEP-257を参照するdocstringsのセクションを含んでいます - docstringsのための完全な仕様。

12
bstpierre

Vladimir Keleshevの pep257 Pythonプログラムを使用して、 PEP-257 および Numpy Docstring Standard と照らし合わせてパラメータ、戻り値などを確認することをお勧めします。

pep257は標準からの逸脱を報告し、pylintやpep8のように呼ばれます。

5
Finn Årup Nielsen

それはPythonです。 何でもあり 。 ドキュメントの公開方法 を検討してください。ドキュメント文字列はあなたのソースコードの読者以外は見えません。

人々は本当にWeb上でドキュメントを閲覧したり検索したりするのが好きです。それを実現するには、ドキュメンテーションツール Sphinx を使います。これはPythonプロジェクトを文書化するための事実上の標準です。製品はきれいです - https://python-guide.readthedocs.org/ja/latest/ をご覧ください。ウェブサイト ドキュメントを読む あなたのドキュメントを無料でホストします。

5
Colonel Panic

Pythonの公式スタイルは PEP-8 にリストされています。

0
Amber