Существуют ли соглашения для комментариев модуля Python?

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

Однако, я видел следующее в комментариях и docstrings:

__author__ = "..."
__version__ = "..."
__date__ = "..."

Где правильное место для размещения таких предметов? Какие другие переменные __[name]__ являются общими для списка в верхней части модулей?

Ответы

Ответ 1

Это просто конвенции, хотя и довольно широко используемые соглашения. См. это описание набора требований метаданных Python.

__version__ упоминается в Руководство по стилю Python.

Что касается docstrings, там PEP только для вас!

Докшлинк для модуля должен обычно перечисляют классы, исключения и функции (и любые другие объекты) которые экспортируются модулем, с однострочное резюме каждого. (Эти резюме обычно дают меньше деталей чем сводная строка в объекте docstring.) Докшрин для пакета (то есть, докшрин пакет init.py) должен также перечислять модули и подпакеты экспортируется пакетом.

Ответ 2

Вы могли бы взглянуть на:

Epydoc, точнее его предопределенный fields.
Pydoc

Ответ 3

Я бы посоветовал не беспокоиться о __author__, __version__ и т.д. Эти атрибуты все равно обрабатываются любой системой управления версиями. Добавляйте их только в том случае, если вам нужна эта информация в производственной системе, где исходный код уже экспортирован из системы управления версиями.