Руководство по docstring pandas

О docstring и стандартах

Python docstring — это строка, используемая для документирования модуля, класса, функции или метода Python, чтобы программисты могли понять, что он делает, не вникая в детали реализации.

Кроме того, принято автоматически генерировать онлайн-документацию (в формате html) из docstring. Для этой цели служит Sphinx.

Следующий пример даёт представление о том, как выглядит docstring:

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 is
the docstring of a very simple function.

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

Существуют стандарты для docstring, чтобы они были более удобочитаемыми и их можно было экспортировать в другие форматы, такие как html или pdf.

Первые правила, которым должен следовать любой Python docstring, определены в PEP-257.

Так как PEP-257 достаточно свободный, существуют дополнительные стандарты. В случае pandas используется соглашение о docstring numpy. Соглашение описано в этом документе:

Руководство по docstring numpydoc (которое основано на оригинальном Руководстве по документированию NumPy/SciPy)

numpydoc — это расширение Sphinx для поддержки соглашения о docstring numpy.

Стандарт использует reStructuredText (reST). reStructuredText — это язык разметки, который позволяет кодировать стили в текстовых файлах. Документацию по reStructuredText можно найти в:

Pandas имеет некоторые вспомогательные средства для совместного использования docstring между связанными классами, см. Обмен docstring.

Остальная часть этого документа обобщит вышеуказанные руководства и предоставит дополнительные соглашения, специфичные для проекта pandas.

Написание docstring

Общие правила

Docstring должны быть определены с помощью трёх двойных кавычек. Перед или после docstring не должно быть пустых строк. Текст начинается в следующей строке после открывающей кавычки. Закрывающая кавычка находится на своей строке (то есть не в конце последнего предложения).

В редких случаях в docstring будут использоваться стили 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: Краткое описание

Краткое описание — это предложение, которое кратко описывает, что делает функция.

Краткое описание должно начинаться с заглавной буквы, заканчиваться точкой и умещаться в одну строку. Оно должно описывать действие объекта, не вдаваясь в детали. Для функций и методов краткое описание должно начинаться с инфинитива.

Хорошо:

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: Подробное описание

Подробное описание предоставляет подробную информацию о том, что делает функция. Оно не должно вдаваться в детали параметров или обсуждать замечания по реализации, которые описываются в других разделах.

Между кратким и подробным описанием оставляется пустая строка. И каждое предложение в подробном описании заканчивается точкой.

Подробное описание должно описывать, почему функция полезна и какие у неё варианты использования, если она не слишком универсальна.

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: Параметры

Подробности параметров будут добавлены в этом разделе. Заголовок этого раздела — «Параметры», за которым следует строка с дефисами под каждой буквой слова «Параметры». Перед заголовком раздела оставляется пустая строка, но не после, и не между строкой со словом «Параметры» и строкой с дефисами.

После заголовка каждый параметр в сигнатуре должен быть задокументирован, включая *args и **kwargs, но не self.

Параметры определяются по имени, за которым следует пробел, двоеточие, ещё один пробел и тип (или типы). Обратите внимание, что пробел между именем и двоеточием важен. Типы не определяются для *args и **kwargs, но должны быть определены для всех остальных параметров. После определения параметра необходима строка с описанием параметра, отступленная, и она может содержать несколько строк. Описание должно начинаться с заглавной буквы и заканчиваться точкой.

Для именованных аргументов по умолчанию значение по умолчанию указывается после запятой в конце типа. Точная форма типа в этом случае будет «int, значение по умолчанию 0». В некоторых случаях может быть полезно объяснить, что означает аргумент по умолчанию, что можно добавить после запятой «int, значение по умолчанию -1, означающее все процессоры».

В случаях, когда значение по умолчанию — None, что означает, что значение не будет использоваться. Вместо «str, значение по умолчанию None» предпочтительно писать «str, необязательный». Когда None — используемое значение, мы сохраняем форму «str, значение по умолчанию None». Например, в df.to_csv(compression=None), None не является используемым значением, но означает, что сжатие необязательно, и сжатие не используется, если не указано. В этом случае мы будем использовать str, optional. Только в таких случаях, как func(value=None) и None используются так же, как 0 или foo, тогда мы укажем «str, int или None, значение по умолчанию 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):

список целых чисел
словарь {строка : целое число}
кортеж (строка, целое число, целое число)
кортеж (строка,)
множество строк

В случае, когда допустим только набор значений, перечислите их в фигурных скобках и разделите запятыми (за которыми следует пробел). Если значения упорядочены и имеют порядок, перечислите их в этом порядке. В противном случае перечислите значение по умолчанию первым, если оно есть:

{0, 10, 25}
{'простой', 'сложный'}
{'низкий', 'средний', 'высокий'}
{'кот', 'собака', 'птица'}

Если тип определяется в Python-модуле, модуль должен быть указан:

datetime.date
datetime.datetime
decimal.Decimal

Если тип находится в пакете, модуль также должен быть указан:

numpy.ndarray
scipy.sparse.coo_matrix

Если тип — тип pandas, укажите pandas, за исключением Series и DataFrame:

Series
DataFrame
pandas.Index
pandas.Categorical
pandas.SparseArray

Если точный тип не важен, но должен быть совместим с массивом numpy, можно указать массив-подобный. Если принимается любой тип, который можно проитерировать, можно использовать итерируемый:

массив-подобный
итерируемый

Если принимается более одного типа, разделите их запятыми, за исключением двух последних типов, которые нужно разделить словом «или»:

целое число или вещественное число
вещественное число, decimal.Decimal или None
строка или список строк

Если None — одно из принимаемых значений, оно всегда должно быть последним в списке.

Для оси соглашение состоит в том, чтобы использовать что-то вроде:

axis : {0 или 'индекс', 1 или 'колонки', None}, значение по умолчанию None

Раздел 4: Возвращаемые значения или значения-генераторы

Если метод возвращает значение, оно будет задокументировано в этом разделе. Также если метод генерирует выходные данные.

Заголовок раздела будет определён так же, как и «Параметры». С именами «Возвращаемое значение» или «Значение-генератор», за которыми следует строка с таким количеством дефисов, как букв в предшествующем слове.

Документация возвращаемого значения также похожа на документацию параметров. Но в этом случае не будет указано имя, если метод возвращает или генерирует более одного значения (кортеж значений).

Типы для «Возвращаемое значение» и «Значение-генератор» такие же, как и для «Параметры». Также описание должно заканчиваться точкой.

Например, с одним значением:

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 и iteritems, так как пользователю, ищущему метод для итерации по столбцам, легко попасть в метод для итерации по строкам, и наоборот
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).

Этот раздел, как и предыдущий, также имеет заголовок «См. также» (обратите внимание на заглавные S и A). После заголовка следует строка с дефисами, а перед ней — пустая строка.

После заголовка мы добавим строку для каждого связанного метода или функции, после которой следует пробел, двоеточие, еще один пробел и краткое описание, иллюстрирующее, что делает этот метод или функция, почему он/она релевантен/на в данном контексте и каковы ключевые различия между документированной функцией и той, на которую делается ссылка. Описание также должно заканчиваться точкой.

Обратите внимание, что в разделах «Возвращает» и «Выдает» описание находится в следующей строке после типа. Но в этом разделе оно расположено в той же строке, разделено двоеточием. Если описание не помещается в одну строку, оно может продолжаться на следующих, но должно быть отступать на них.

Например:

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 the whole 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
        --------
        >>> s = pd.Series(['Ant', 'Bear', 'Cow', 'Dog', 'Falcon',
        ...                'Lion', 'Monkey', 'Rabbit', 'Zebra'])
        >>> s.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:

        >>> s.head(n=3)
        0   Ant
        1   Bear
        2   Cow
        dtype: object
        """
        return self.iloc[:n]

Примеры должны быть максимально лаконичными. В тех случаях, когда сложность функции требует длинных примеров, рекомендуется использовать блоки с заголовками. Используйте двойные звёзды ** для выделения текста жирным шрифтом, как в **this example**.

Советы по прохождению тестов примеров

Прохождение тестов примеров в скрипте проверки может быть сложным. Вот несколько важных моментов:

Импортируйте все необходимые библиотеки (кроме 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, это приведёт к неудаче доктэста
```
>>> s.plot()
<matplotlib.axes._subplots.AxesSubplot at 0x7efd0c0b0690>
```
Однако вы можете сделать так (обратите внимание на комментарий, который необходимо добавить)
```
>>> s.plot()  
<matplotlib.axes._subplots.AxesSubplot at ...>
```

Диаграммы в примерах

В pandas есть некоторые методы, возвращающие диаграммы. Для отображения диаграмм, сгенерированных примерами в документации, существует директива .. plot::.

Для её использования разместите следующий код после заголовка «Примеры», как показано ниже. Диаграмма будет автоматически сгенерирована при построении документации.

class Series:
    def plot(self):
        """
        Generate a plot with the `Series` data.

        Examples
        --------

        .. plot::
            :context: close-figs

            >>> s = pd.Series([1, 2, 3])
            >>> s.plot()
        """
        pass

Каждая общая документация функции будет иметь базовый шаблон с переменными, например, %(klass)s. Переменные заполняются позже с помощью декоратора Substitution.

В итоге, документации функций можно добавлять с помощью декоратора Appender.

В этом примере мы создадим родительскую документацию функции стандартным образом (это похоже на pandas.core.generic.NDFrame. Затем у нас будут два дочерних класса (например, pandas.core.series.Series и pandas.core.frame.DataFrame). Мы заменим имена классов дочерних классов в этой документации функции.

class Parent:
    def my_function(self):
        """Apply my function to %(klass)s."""
        ...


class ChildA(Parent):
    @Substitution(klass="ChildA")
    @Appender(Parent.my_function.__doc__)
    def my_function(self):
        ...


class ChildB(Parent):
    @Substitution(klass="ChildB")
    @Appender(Parent.my_function.__doc__)
    def my_function(self):
        ...

Полученные документации функций:

>>> print(Parent.my_function.__doc__)
Apply my function to %(klass)s.
>>> print(ChildA.my_function.__doc__)
Apply my function to ChildA.
>>> print(ChildB.my_function.__doc__)
Apply my function to ChildB.

Обратите внимание на два момента:

Мы «добавляем» родительскую документацию к документациям дочерних функций, которые изначально пустые.
Декораторы Python применяются снаружи вовнутрь. Следовательно, порядок — Добавление, затем Подстановка, даже если Подстановка идёт первой в файле.

Наши файлы часто содержат модульную _shared_doc_kwargs с некоторыми общими значениями подстановки (такими как klass, axes, и т. д).

Можно заменить и добавить в одном действии с помощью чего-то вроде

@Appender(template % _shared_doc_kwargs)
def my_function(self):
    ...

где template может исходить из модульного _shared_docs словаря, сопоставляющего имена функций с документациями. В тех случаях, когда это возможно, мы предпочитаем использовать Appender и Substitution, поскольку процесс написания документации функций немного ближе к обычному.

См. pandas.core.generic.NDFrame.fillna для примера шаблона и pandas.core.series.Series.fillna и pandas.core.generic.frame.fillna для заполненных версий.

© 2008–2012, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData Development Team
Licensed under the 3-clause BSD License.
https://pandas.pydata.org/pandas-docs/version/0.24.2/development/contributing_docstring.html

Руководство по docstring pandas

О docstring и стандартах

Написание docstring

Общие правила

Раздел 1: Краткое описание

Раздел 2: Подробное описание

Раздел 3: Параметры

Типы параметров

Раздел 4: Возвращаемые значения или значения-генераторы

Раздел 5: См. также

Раздел 6: Примечания

Раздел 7: Примеры

Рекомендации для примеров

Советы по прохождению тестов примеров

Диаграммы в примерах

Обмен документацией функций