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

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

  • Импорт модулей в Python - лучшая практика
  • Экстренные пробелы при печати
  • Вкладки и пробелы в программировании на Python
  • Недопустимое имя пользователя Pylint
  • Автозагрузка в Python
  • Как вы возвращаете несколько значений в Python?
  • 8 Solutions collect form web for “Каков стандартный формат docstring Python?”

    Форматы

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

    Обратите внимание, что reST рекомендуется 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 """ 

    – отдых

    В настоящее время, вероятно, более распространенным форматом является формат 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, для автоматического создания docstrings в проекте Python, который еще не задокументирован, или для преобразования существующих docstrings (может смешивать несколько форматов) из формата в другой.

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

    Руководство по стилю 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, потому что они склонны демонстрировать, как использовать функцию и что она делает очень быстро.

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

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

    Над:

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

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

     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 

    Смысл: я нахожу докстры, которые начинаются так, как будто это беспорядочно.

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

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

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

    Наполеанское расширение сфинкса для разбора докстронгов в стиле 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 является официальным стандартом кодирования питона. Он содержит раздел о docstrings, который относится к PEP-257 – полной спецификации для докстерий.

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

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

    pep257 сообщит о дивергенции, которую вы делаете со стандартного, и называется как pylint и pep8.

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

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

    Python - лучший язык программирования в мире.