Каков стандартный формат docstring Python?

Я видел несколько разных стилей написания docstrings в Python, есть ли официальный или "согласованный" стиль?

Ответ 1

Форматы

Строки документации Python могут быть написаны в нескольких форматах, как показано в других сообщениях. Однако формат строки документа Sphinx по умолчанию не был упомянут и основан на reStructuredText (reST). Вы можете получить информацию об основных форматах в этой записи блога.

Обратите внимание, что reST рекомендуется PEP 287

.Ниже приведены основные используемые форматы строк документации.

- Эпитекст

Исторически 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
"""

- reST

В настоящее время, вероятно, более распространенным форматом является формат 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

У Google есть свой собственный формат, который часто используется. Это также может быть интерпретировано Сфинксом (т.е. с использованием плагина Наполеона).

Пример:

"""
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 рекомендует следовать своему собственному numpydoc на основе формата Google и может использоваться Sphinx.

"""
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.

Ответ 2

Руководство по стилю 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

Ответ 3

Соглашения Docstring находятся в PEP-257 с гораздо большей детализацией, чем PEP-8.

Однако, докстры, похоже, гораздо более личны, чем другие области кода. У разных проектов будет свой собственный стандарт.

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

Я предпочитаю сохранять согласованность, независимо от длины строки. Мне нравится, как выглядит код, когда отступы и интервалы согласованы. Это означает, что я использую:

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

Over:

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

И, как правило, не следует комментировать первую строку в более длинных docstrings:

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

Значение Я нахожу docstrings, которые начинаются как это, чтобы быть грязным.

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

Ответ 4

В качестве apparantly никто не упомянул об этом: вы также можете использовать Стандарт Docstring > . Он широко используется в научном сообществе.

спецификация формата от numpy вместе с example
У вас есть расширение sphinx для его отображения: numpydoc
И пример того, как может выглядеть красивая рендерная docstring: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Расширение сфинкса Napolean для разбора docstrings в стиле Google (рекомендуется в ответ @Nathan) также поддерживает docstring в стиле 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

Ответ 5

PEP-8 является официальным стандартом кодирования питона. Он содержит раздел о docstrings, который ссылается на PEP-257 - полную спецификацию для docstrings.

Ответ 6

Это Python; все идет. Подумайте, как опубликовать свою документацию. Докстоны невидимы, за исключением читателей вашего исходного кода.

Люди действительно любят просматривать и искать документацию в Интернете. Для этого используйте инструмент документации Sphinx. Это де-факто стандарт для документирования проектов Python. Продукт красив - посмотрите https://python-guide.readthedocs.org/en/latest/. На веб-сайте Прочитать Документы будут бесплатно размещены ваши документы.

Ответ 7

Я предлагаю использовать pep257 Python-программу Владимира Келешева для проверки ваших строк документации на соответствие PEP-257 и стандарту Numpy Docstring для описания параметров, возвратов и т.д.

pep257 сообщит о расхождении, которое вы производите от стандарта, и называется pylint и pep8.

Ответ 8

Официальные стили Python перечислены в PEP-8.