Где я могу найти подходящие примеры конвенций PEP 257 Docstring?

PEP 257 говорит:

Вставьте пустую строку до и после всех docstrings (однострочный или многострочные), которые документируют класс - вообще говоря, класс методы отделены друг от друга одной пустой линией, а docstring должен быть смещен от первого метода пустой строкой; для симметрии, поставьте пустую строку между заголовком класса и строка документации.

Но я не могу найти какой-либо код, который действительно реализует это.

Я проверил несколько стандартных модулей, поставляемых с Python 2.6, даже специально для тех, где упоминается имя Guido. Но даже код кода для проверки кода rietveld IMHO не соответствует (см., Например, http://code.google.com/p/rietveld/source/browse/upload.py):

class CondensedHelpFormatter(optparse.IndentedHelpFormatter):
   """Frees more horizontal space by removing indentation from group
      options and collapsing arguments between short and long, e.g.
      '-o ARG, --opt=ARG' to -o --opt ARG"""

   def format_heading(self, heading):
     return "%s:\n" % heading

В этой многострочной docstring нет пустой строки, и пустая строка после закрытия закрывается.

Этот класс из /usr/lib64/python2.6/site.py не имеет пустой строки раньше, но имеет пустую строку до и после закрывающих кавычек.

class _Helper(object):
    """Define the built-in 'help'.
    This is a wrapper around pydoc.help (with a twist).

    """

    def __repr__(self):

Есть ли примеры для демонстрации PEP 257?

Заранее спасибо

Ответы

Ответ 1

Не прямой ответ, но если вы хотите выполнить PEP257, вы можете использовать инструмент, который я написал: https://github.com/halst/pep257

Я тоже был потрясен, увидев, сколько кода (также в стандартной библиотеке) даже не пытается выполнить PEP257.

Вероятно, большинство людей думает, что их стиль docstring имеет смысл, и я также думал, что есть что-то неудобное для стиля PEP257, но после его использования в течение некоторого времени я влюбился в него, и подумайте, что это самый красивый способ писать докстры. Я всегда следую PEP257 во всех аспектах, которые я могу, и написал инструмент, чтобы больше людей могли видеть, как они могут улучшить свой стиль.

В качестве примера у меня был забавный опыт работы с PEP8 и pep8 tool: когда я впервые прочитал PEP8, мне понравилось и подумал, что я следую ему, но когда я попробовал свой код на pep8 Я был шокирован тем, насколько далеко от PEP8 я и насколько лучше мой код выглядит после того, как я исправил эти ошибки стиля.

Я надеюсь, что люди будут иметь схожий опыт с pep257 и с радостью последовать за PEP257.

Ответ 2

Насколько я вижу, в документе, который вы указали, говорится:

Вставьте пустую строку после всех docstrings (однострочных или многострочных), которые документируют класс - вообще говоря, методы класса отделены друг от друга одной пустой строкой и docstring должен быть смещен от первого метода пустой строкой.

(акцент мой)

Итак, приведенные вами примеры правильны, поскольку у них есть пустая строка после docstring, тем самым отделяя следующее объявление метода пустой строкой.