Какой стандартный формат Python DocString? [закрыто

StackOverflow https://stackoverflow.com/questions/3898572

Вопрос

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

Это было полезно?

Решение

Форматы

Python Docstrings можно писать после нескольких форматов, как показали другие посты. Однако формат Docstring по умолчанию не был упомянут и основан на реструктурныйтекст (отдых). Анкет Вы можете получить информацию о основных форматах в что туто.

Обратите внимание, что остальные рекомендуются PEP 287.

Следуется основные использованные форматы для DocStrings.

- Epytext

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

- остальное

В наши дни, вероятно, более распространенные формат является реструктурированный текст (отдых) формат, который используется Сфинкс генерировать документацию. ПРИМЕЧАНИЕ. По умолчанию используется по умолчанию в Jetbrains Pycharm (Type Triple Quotes после определения метода и нажмите 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
"""

Преобразование/генерирование

Можно использовать инструмент, как Пристальный Чтобы автоматически генерировать Docstrings в проект Python, еще не задокументированный, или для преобразования существующих Docstrings (можно смешивать несколько форматов) из формата на другой.

Примечание. Примеры взяты из Документация

Другие советы

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

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

Тем не менее, Docstrings кажутся гораздо более личными, чем другие области кода. Различные проекты будут иметь свой собственный стандарт.

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

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

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

Над:

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

Как очевидно, никто не упомянул об этом: вы также можете использовать Numpy Docstring Standard. Анкет Он широко используется в научном сообществе.

Расширение Sphinx Sphinx для анализа 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

Pep-8. является официальным стандартом кодирования Python. Содержит раздел на DocStrings, который относится к PEP-257 - полная спецификация для Docstrings.

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

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

Я предлагаю использовать Владимир Келешева Pep257. Программа Python, чтобы проверить ваши Docstrings против PEP-257 и то Numpy Docstring Standard Для описания параметров, возврата и т. Д.

PEP257 сообщит о дивергенции, которое вы делаете из стандарта и называется Pylint и PEP8.

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top