pandas docstring guide#
ドキュメント文字列と標準について#
Pythonのドキュメント文字列は、Pythonモジュール、クラス、関数、またはメソッドをドキュメント化するために使用される文字列であり、プログラマが実装の詳細を読むことなく、その機能について理解できるようになります。
また、ドキュメント文字列からオンライン (HTML) ドキュメントを自動的に生成するのが一般的です。Sphinxがこの目的のために使用されます。
次の例は、ドキュメント文字列がどのようなものかを示しています。
def add(num1, num2):
"""
Add up two integer numbers.
This function simply wraps the ``+`` operator, and does not
do anything interesting, except for illustrating what
the docstring of a very simple function looks like.
Parameters
----------
num1 : int
First number to add.
num2 : int
Second number to add.
Returns
-------
int
The sum of ``num1`` and ``num2``.
See Also
--------
subtract : Subtract one integer from another.
Examples
--------
>>> add(2, 2)
4
>>> add(25, 0)
25
>>> add(10, -10)
0
"""
return num1 + num2
ドキュメント文字列にはいくつかの標準が存在し、それらによって読みやすくなり、HTMLやPDFなどの他の形式に簡単にエクスポートできるようになります。
すべてのPythonドキュメント文字列が従うべき最初の規約は、PEP-257で定義されています。
PEP-257は非常に広範であるため、他のより具体的な標準も存在します。pandasの場合、NumPyのドキュメント文字列規約が採用されています。これらの規約はこのドキュメントで説明されています。
numpydocは、NumPyドキュメント文字列規約をサポートするためのSphinx拡張機能です。
この標準はreStructuredText (reST) を使用しています。reStructuredTextは、プレーンテキストファイルにスタイルをエンコードできるマークアップ言語です。reStructuredTextに関するドキュメントは以下で参照できます。
pandasには、関連するクラス間でドキュメント文字列を共有するためのヘルパーがあります。詳細については、「ドキュメント文字列の共有」を参照してください。
このドキュメントの残りの部分では、上記のすべてのガイドラインを要約し、pandasプロジェクトに固有の追加の規約を提供します。
ドキュメント文字列の記述#
一般規則#
ドキュメント文字列は3つの二重引用符で定義する必要があります。ドキュメント文字列の前後に空白行を残してはなりません。テキストは開始引用符の次の行から始まります。終了引用符は独自の行に配置されます（つまり、最後の文の終わりには配置されません）。
まれに、太字や斜体などのreSTスタイルがドキュメント文字列で使用されることがありますが、バックティックの間に表示されるインラインコードを使用するのが一般的です。以下がインラインコードと見なされます。
パラメーターの名前
Pythonコード、モジュール、関数、組み込み関数、型、リテラルなど（例：
os、list、numpy.abs、datetime.date、True）pandasクラス (形式
:class:`pandas.Series`)pandasメソッド (形式
:meth:`pandas.Series.sum`)pandas関数 (形式
:func:`pandas.to_datetime`)
注
リンク先のクラス、メソッド、または関数の最後のコンポーネントのみを表示するには、~ を前に付けます。たとえば、:class:`~pandas.Series` は pandas.Series にリンクしますが、リンクテキストとして最後の部分である Series のみを表示します。詳細については、Sphinx 相互参照構文を参照してください。
良い例
def add_values(arr):
"""
Add the values in ``arr``.
This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
Some sections are omitted here for simplicity.
"""
return sum(arr)
悪い例
def func():
"""Some function.
With several mistakes in the docstring.
It has a blank like after the signature ``def func():``.
The text 'Some function' should go in the line after the
opening quotes of the docstring, not in the same line.
There is a blank line between the docstring and the first line
of code ``foo = 1``.
The closing quotes should be in the next line, not in this one."""
foo = 1
bar = 2
return foo + bar
セクション1：短い概要#
短い概要は、関数の機能を手短に表現する単一の文です。
短い概要は、大文字で始まり、ピリオドで終わり、1行に収まる必要があります。オブジェクトが何をするかを詳細を提供せずに表現する必要があります。関数とメソッドの場合、短い概要は不定詞の動詞で始まる必要があります。
良い例
def astype(dtype):
"""
Cast Series type.
This section will provide further details.
"""
pass
悪い例
def astype(dtype):
"""
Casts Series type.
Verb in third-person of the present simple, should be infinitive.
"""
pass
def astype(dtype):
"""
Method to cast Series type.
Does not start with verb.
"""
pass
def astype(dtype):
"""
Cast Series type
Missing dot at the end.
"""
pass
def astype(dtype):
"""
Cast Series type from its current type to the new type defined in
the parameter dtype.
Summary is too verbose and doesn't fit in a single line.
"""
pass
セクション2：拡張概要#
拡張概要は、関数の機能の詳細を提供します。パラメーターの詳細や実装に関するメモは、他のセクションで扱うため、ここでは記述すべきではありません。
短い概要と拡張概要の間には空白行を1行挿入します。拡張概要の各段落はピリオドで終わります。
拡張概要では、関数が有用である理由と、あまりにも一般的でない場合はそのユースケースについて詳細に記述すべきです。
def unstack():
"""
Pivot a row index to columns.
When using a MultiIndex, a level can be pivoted so each value in
the index becomes a column. This is especially useful when a subindex
is repeated for the main index, and data is easier to visualize as a
pivot table.
The index level will be automatically removed from the index when added
as columns.
"""
pass
セクション3：パラメーター#
パラメーターの詳細は、このセクションで追加されます。このセクションには、「Parameters」というタイトルがあり、その下に「Parameters」という単語の各文字の下にハイフンが引かれた行が続きます。セクションタイトルの前に空白行を1行挿入しますが、後には挿入しません。また、「Parameters」という単語の行とハイフンの行の間にも挿入しません。
タイトルの後には、シグネチャ内の各パラメーター（*args と **kwargs を含む）を記述する必要がありますが、self は記述しません。
パラメーターは、名前、その後にスペース、コロン、別のスペース、そして型（または複数の型）を記述して定義します。名前とコロンの間のスペースが重要であることに注意してください。*args と **kwargs の型は定義しませんが、その他のすべてのパラメーターについては定義する必要があります。パラメーター定義の後には、パラメーターの説明の行が必要です。これはインデントされ、複数行にわたる可能性があります。説明は大文字で始まり、ピリオドで終わる必要があります。
デフォルト値を持つキーワード引数の場合、デフォルト値は型の末尾にコンマの後にリストされます。この場合の型の厳密な形式は「int, default 0」となります。場合によっては、デフォルト引数が何を意味するのかを説明することが有用であり、コンマの後に「int, default -1, meaning all cpus」のように追加できます。
デフォルト値が None であり、その値が使用されないことを意味する場合があります。"str, default None" の代わりに、"str, optional" と書く方が好ましいです。None が使用される値である場合は、「str, default None」の形式を維持します。たとえば、df.to_csv(compression=None) の場合、None は使用される値ではなく、圧縮がオプションであり、指定されない場合は圧縮が使用されないことを意味します。この場合、"str, optional" を使用します。func(value=None) のようなケースで、None が 0 や foo と同じ方法で使用される場合にのみ、「str, int or None, default None」と指定します。
良い例
class Series:
def plot(self, kind, color='blue', **kwargs):
"""
Generate a plot.
Render the data in the Series as a matplotlib plot of the
specified kind.
Parameters
----------
kind : str
Kind of matplotlib plot.
color : str, default 'blue'
Color name or rgb code.
**kwargs
These parameters will be passed to the matplotlib plotting
function.
"""
pass
悪い例
class Series:
def plot(self, kind, **kwargs):
"""
Generate a plot.
Render the data in the Series as a matplotlib plot of the
specified kind.
Note the blank line between the parameters title and the first
parameter. Also, note that after the name of the parameter ``kind``
and before the colon, a space is missing.
Also, note that the parameter descriptions do not start with a
capital letter, and do not finish with a dot.
Finally, the ``**kwargs`` parameter is missing.
Parameters
----------
kind: str
kind of matplotlib plot
"""
pass
パラメーターの型#
パラメーターの型を指定する際には、Pythonの組み込みデータ型を直接使用できます（冗長な「文字列」、「整数」、「ブール値」などよりもPythonの型が推奨されます）。
int
float
str
bool
複合型の場合、サブタイプを定義します。dict および tuple の場合、複数の型が存在するため、読みやすくするために括弧を使用します（dict には波括弧、tuple には通常の括弧）。
list of int
dict of {str : int}
tuple of (str, int, int)
tuple of (str,)
set of str
許可される値のセットのみがある場合は、波括弧で囲み、コンマ（その後にスペース）で区切ってリストします。値が順序があり、順序がある場合は、その順序でリストします。それ以外の場合は、デフォルト値がある場合はまずデフォルト値をリストします。
{0, 10, 25}
{‘simple’, ‘advanced’}
{‘low’, ‘medium’, ‘high’}
{‘cat’, ‘dog’, ‘bird’}
型がPythonモジュールで定義されている場合、モジュールを指定する必要があります。
datetime.date
datetime.datetime
decimal.Decimal
型がパッケージ内にある場合、モジュールも指定する必要があります。
numpy.ndarray
scipy.sparse.coo_matrix
型がpandasの型である場合、SeriesとDataFrameを除き、pandasも指定します。
Series
DataFrame
pandas.Index
pandas.Categorical
pandas.arrays.SparseArray
厳密な型が重要でないが、NumPy配列と互換性がある必要がある場合、array-likeを指定できます。反復可能な任意の型が受け入れられる場合、iterableを使用できます。
array-like
iterable
複数の型が受け入れられる場合、最後の2つの型は「or」で区切る必要があります。
int or float
float, decimal.Decimal or None
str or list of str
None が受け入れられる値の1つである場合、常にリストの最後に配置する必要があります。
軸の場合、次のような表記法を使用します。
axis : {0 or ‘index’, 1 or ‘columns’, None}, default None
セクション4：戻り値または生成値#
メソッドが値を返す場合、このセクションでドキュメント化されます。メソッドが出力を生成する場合も同様です。
セクションのタイトルは、「Parameters」と同じ方法で定義されます。「Returns」または「Yields」という名前の後に、前の単語の文字数と同じ数のハイフンが引かれた行が続きます。
戻り値のドキュメントもパラメーターと同様です。ただし、この場合、メソッドが複数の値（値のタプル）を返すか、生成する場合を除いて、名前は提供されません。
「Returns」および「Yields」の型は、「Parameters」と同じです。また、説明はピリオドで終わる必要があります。
例えば、単一の値の場合
def sample():
"""
Generate and return a random number.
The value is sampled from a continuous uniform distribution between
0 and 1.
Returns
-------
float
Random number generated.
"""
return np.random.random()
複数の値の場合
import string
def random_letters():
"""
Generate and return a sequence of random letters.
The length of the returned string is also random, and is also
returned.
Returns
-------
length : int
Length of the returned string.
letters : str
String of random letters.
"""
length = np.random.randint(1, 10)
letters = ''.join(np.random.choice(string.ascii_lowercase)
for i in range(length))
return length, letters
メソッドが値を生成する場合
def sample_values():
"""
Generate an infinite sequence of random numbers.
The values are sampled from a continuous uniform distribution between
0 and 1.
Yields
------
float
Random number generated.
"""
while True:
yield np.random.random()
セクション5：参照#
このセクションは、ユーザーに、ドキュメント化されている機能に関連するpandasの機能について知らせるために使用されます。まれに、関連するメソッドや関数が全く見つからない場合、このセクションはスキップできます。
明白な例としては、head() と tail() メソッドが挙げられます。tail() は head() と同等の処理を行いますが、Series または DataFrame の先頭ではなく末尾で行うため、ユーザーにそのことを知らせることは良いことです。
関連と見なせるものの直感を与えるために、いくつかの例を挙げます。
locとiloc。これらは同じことを行いますが、一方はインデックスを提供し、もう一方は位置を提供します。maxとmin。これらは逆の操作を行います。iterrows、itertuples、items。列を反復処理するメソッドを探しているユーザーが行を反復処理するメソッドに行き着いてしまうことが容易であるため、逆もまた然りです。fillnaとdropna。どちらのメソッドも欠損値を処理するために使用されます。read_csvとto_csv。これらは相補的です。mergeとjoin。一方がもう一方の一般化であるため。astypeとpandas.to_datetime。ユーザーが日付としてキャストする方法を知るためにastypeのドキュメントを読んでいる可能性があり、その方法はpandas.to_datetimeを使用するため。whereはnumpy.whereに関連しています。その機能がそれに基づいているためです。
関連性を判断する際には、主に常識を使用し、特に経験の少ないユーザーがドキュメントを読む際に何が役立つかを考えるべきです。
他のライブラリ（主に numpy）を参照する場合は、まずモジュール名を使用します（np のようなエイリアスは使用しません）。関数がメインモジュールではないモジュール（例：scipy.sparse）にある場合は、完全なモジュールをリストします（例：scipy.sparse.coo_matrix）。
このセクションには、「See Also」というヘッダー（SとAが大文字であることに注意）があり、その後にハイフンが引かれた行が続き、その前に空白行があります。
ヘッダーの後、関連する各メソッドまたは関数ごとに1行を追加し、その後にスペース、コロン、別のスペース、そしてこのメソッドまたは関数が何をするのか、このコンテキストでなぜ関連するのか、そしてドキュメント化された関数と参照されている関数との間の主な違いは何であるかを示す短い説明を記述します。説明もピリオドで終わる必要があります。
「Returns」および「Yields」では、説明は型の次の行に記述されますが、このセクションでは、コロンを挟んで同じ行に記述されることに注意してください。説明が同じ行に収まらない場合は、さらにインデントされた他の行に続けることができます。
例えば
class Series:
def head(self):
"""
Return the first 5 elements of the Series.
This function is mainly useful to preview the values of the
Series without displaying the whole of it.
Returns
-------
Series
Subset of the original series with the 5 first values.
See Also
--------
Series.tail : Return the last 5 elements of the Series.
Series.iloc : Return a slice of the elements in the Series,
which can also be used to return the first or last n.
"""
return self.iloc[:5]
セクション6：注記#
これは、アルゴリズムの実装に関するメモや、関数の動作に関する技術的側面を記述するためのオプションのセクションです。
アルゴリズムの実装に精通しているか、関数の例を記述する際に直感に反する動作を発見しない限り、このセクションはスキップしても構いません。
このセクションは、拡張概要セクションと同じ形式に従います。
セクション7：例#
これは、ドキュメント文字列の中で最も重要なセクションの一つです。最後の位置に配置されていますが、人々は正確な説明よりも例によって概念をよりよく理解することが多いためです。
ドキュメント文字列の例は、関数またはメソッドの使用法を示すだけでなく、特定の出力を決定論的に返す有効なPythonコードであり、ユーザーがコピーして実行できるものである必要があります。
例はPythonターミナルでのセッションとして表示されます。>>> はコードを表示するために使用されます。... は前の行から続くコードのために使用されます。出力は、出力を生成するコードの最後の行の直後に表示されます（間に空白行はありません）。例を記述するコメントは、その前後に空白行を付けて追加できます。
例の提示方法は次のとおりです。
必要なライブラリをインポートする（
numpyとpandasは除く）例に必要なデータを作成する
最も一般的なユースケースのアイデアを与える非常に基本的な例を示す
パラメーターが拡張機能にどのように使用できるかを示す説明付きの例を追加する
簡単な例は次のとおりです。
class Series:
def head(self, n=5):
"""
Return the first elements of the Series.
This function is mainly useful to preview the values of the
Series without displaying all of it.
Parameters
----------
n : int
Number of values to return.
Return
------
pandas.Series
Subset of the original series with the n first values.
See Also
--------
tail : Return the last n elements of the Series.
Examples
--------
>>> ser = pd.Series(['Ant', 'Bear', 'Cow', 'Dog', 'Falcon',
... 'Lion', 'Monkey', 'Rabbit', 'Zebra'])
>>> ser.head()
0 Ant
1 Bear
2 Cow
3 Dog
4 Falcon
dtype: object
With the ``n`` parameter, we can change the number of returned rows:
>>> ser.head(n=3)
0 Ant
1 Bear
2 Cow
dtype: object
"""
return self.iloc[:n]
例はできるだけ簡潔にする必要があります。関数の複雑さから長い例が必要な場合は、太字のヘッダーを持つブロックを使用することをお勧めします。テキストを太字にするには、**this example** のように二重のアスタリスク ** を使用します。
例の規約#
例のコードは、常にこれらの2行で始まると仮定されますが、これらは表示されません。
import numpy as np
import pandas as pd
例で使用される他のモジュールは、明示的に1行ずつインポートし（PEP 8#importsで推奨されているように）、エイリアスを避ける必要があります。過剰なインポートは避けるべきですが、必要な場合は、標準ライブラリからのインポートが最初に来て、その後にサードパーティライブラリ（matplotlibなど）が続きます。
単一の Series を使用して例を示す場合は ser という名前を使用し、単一の DataFrame を使用して例を示す場合は df という名前を使用します。インデックスには idx が推奨される名前です。均一な Series または DataFrame のセットを使用する場合は、ser1、ser2、ser3… または df1、df2、df3… のように名前を付けます。データが均一でなく、複数の構造が必要な場合は、df_main や df_to_join のように意味のある名前を付けます。
例で使用されるデータは、できるだけコンパクトにする必要があります。行数は4程度が推奨されますが、特定の例にとって意味のある数にしてください。たとえば、head メソッドでは、デフォルト値の例を示すために5より大きい必要があります。mean を行う場合、[1, 2, 3] のようなものを使用できるため、返される値が平均であることが簡単にわかります。
より複雑な例（例えばグルーピング）では、A、B、C、D…の列を持つランダムな数値行列のような解釈のないデータを使用せず、概念を理解しやすくする意味のある例を使用してください。例で特に要求されない限り、一貫性を保つために動物の名前とその数値的な特性を使用してください。
メソッドを呼び出す場合、キーワード引数 head(n=3) は位置引数 head(3) よりも推奨されます。
良い例
class Series:
def mean(self):
"""
Compute the mean of the input.
Examples
--------
>>> ser = pd.Series([1, 2, 3])
>>> ser.mean()
2
"""
pass
def fillna(self, value):
"""
Replace missing values by ``value``.
Examples
--------
>>> ser = pd.Series([1, np.nan, 3])
>>> ser.fillna(0)
[1, 0, 3]
"""
pass
def groupby_mean(self):
"""
Group by index and return mean.
Examples
--------
>>> ser = pd.Series([380., 370., 24., 26],
... name='max_speed',
... index=['falcon', 'falcon', 'parrot', 'parrot'])
>>> ser.groupby_mean()
index
falcon 375.0
parrot 25.0
Name: max_speed, dtype: float64
"""
pass
def contains(self, pattern, case_sensitive=True, na=numpy.nan):
"""
Return whether each value contains ``pattern``.
In this case, we are illustrating how to use sections, even
if the example is simple enough and does not require them.
Examples
--------
>>> ser = pd.Series('Antelope', 'Lion', 'Zebra', np.nan)
>>> ser.contains(pattern='a')
0 False
1 False
2 True
3 NaN
dtype: bool
**Case sensitivity**
With ``case_sensitive`` set to ``False`` we can match ``a`` with both
``a`` and ``A``:
>>> s.contains(pattern='a', case_sensitive=False)
0 True
1 False
2 True
3 NaN
dtype: bool
**Missing values**
We can fill missing values in the output using the ``na`` parameter:
>>> ser.contains(pattern='a', na=False)
0 False
1 False
2 True
3 False
dtype: bool
"""
pass
悪い例
def method(foo=None, bar=None):
"""
A sample DataFrame method.
Do not import NumPy and pandas.
Try to use meaningful data, when it makes the example easier
to understand.
Try to avoid positional arguments like in ``df.method(1)``. They
can be all right if previously defined with a meaningful name,
like in ``present_value(interest_rate)``, but avoid them otherwise.
When presenting the behavior with different parameters, do not place
all the calls one next to the other. Instead, add a short sentence
explaining what the example shows.
Examples
--------
>>> import numpy as np
>>> import pandas as pd
>>> df = pd.DataFrame(np.random.randn(3, 3),
... columns=('a', 'b', 'c'))
>>> df.method(1)
21
>>> df.method(bar=14)
123
"""
pass
doctestをパスさせるためのヒント#
バリデーションスクリプトで例がdoctestをパスすることは、時にトリッキーな場合があります。ここにいくつかの注意点を示します。
必要なすべてのライブラリ（pandasとNumPyを除く。これらはすでに
import pandas as pdおよびimport numpy as npとしてインポートされています）をインポートし、例で使用するすべての変数を定義します。ランダムなデータを使用しないようにしてください。ただし、確率分布を扱う関数をドキュメント化している場合や、関数の結果を意味のあるものにするために必要なデータ量が多すぎて手動で作成するのが非常に面倒な場合など、一部のケースではランダムなデータも問題ありません。そのような場合は、常に固定されたランダムシードを使用して、生成される例が予測可能になるようにしてください。例：
>>> np.random.seed(42) >>> df = pd.DataFrame({'normal': np.random.normal(100, 5, 20)})
複数行にわたるコードスニペットがある場合は、継続行に「…」を使用する必要があります。
>>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], index=['a', 'b', 'c'], ... columns=['A', 'B'])
例外が発生するケースを示すには、次のように記述できます。
>>> pd.to_datetime(["712-01-01"]) Traceback (most recent call last): OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 712-01-01 00:00:00
「Traceback (most recent call last):」を含めることが不可欠ですが、実際のエラーについてはエラー名だけで十分です。
結果の一部に変動する部分がある場合（例：オブジェクト表現内のハッシュ）、
...を使用してその部分を表すことができます。s.plot()がmatplotlibのAxesSubplotオブジェクトを返すことを示したい場合、これはdoctestに失敗します。>>> s.plot() <matplotlib.axes._subplots.AxesSubplot at 0x7efd0c0b0690>
ただし、次のように記述できます（追加する必要のあるコメントに注意してください）。
>>> s.plot() <matplotlib.axes._subplots.AxesSubplot at ...>
例のプロット#
pandasには、プロットを返すメソッドがいくつかあります。ドキュメント内の例によって生成されたプロットをレンダリングするために、.. plot:: ディレクティブが存在します。
これを使用するには、「Examples」ヘッダーの後に次のコードを配置します。ドキュメントのビルド時にプロットが自動的に生成されます。
class Series:
def plot(self):
"""
Generate a plot with the ``Series`` data.
Examples
--------
.. plot::
:context: close-figs
>>> ser = pd.Series([1, 2, 3])
>>> ser.plot()
"""
pass