Первая строка каждого файла должна быть #!/usr/bin/env python
. Это позволяет запускать файл как скрипт, неявно вызывающий интерпретатор, например, в контексте CGI.
Далее должна быть строка документации с описанием. Если описание длинное, первая строка должна быть краткой, которая имеет смысл сама по себе, отделенная от остальных новой строкой.
Весь код, включая операторы импорта, должен следовать за строкой документации. В противном случае строка документации не будет распознаваться интерпретатором, и вы не сможете получить к ней доступ в интерактивных сеансах (т. Е. Через obj.__doc__
) или при создании документации с помощью автоматизированных инструментов.
Сначала импортируйте встроенные модули, затем сторонние модули, затем любые изменения пути и ваших собственных модулей. В частности, дополнения к пути и именам ваших модулей, вероятно, быстро изменятся: хранение их в одном месте облегчает их поиск.
Далее должна быть информация об авторстве. Эта информация должна соответствовать следующему формату:
__author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell"
__copyright__ = "Copyright 2007, The Cogent Project"
__credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley",
"Matthew Wakefield"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Rob Knight"
__email__ = "rob@spot.colorado.edu"
__status__ = "Production"
Статус обычно должен быть «Прототип», «Разработка» или «Производство». __maintainer__
должен быть человек, который будет исправлять ошибки и вносить улучшения в случае импорта. __credits__
отличается от того, __author__
что __credits__
включает людей, которые сообщили об исправлениях ошибок, внесли предложения и т. д., но на самом деле не написали код.