Где я могу найти подходящие примеры соглашений Poc 257 Docstring?

Question

PEP 257 says:

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

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

Я проверил несколько стандартных модулей, поставляемых с Python 2.6, даже специально для тех, где упоминается имя Гвидо. Но даже код Ритвельд инструмента Код обзора делает 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 

Это многострочный строка документация не имеет пустую строку перед и пустой строкой после того, как находится вне котировок закрытия ,

Этот класс от /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?

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

Answer 1

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

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

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

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

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

Answer 2

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

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

(курсив мой)

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