Каков общий формат заголовков файлов Python?

Ответ 1

Все его метаданные для модуля Foobar.

Первым из них является docstring модуля, который уже объясняется в Питере.

Как организовать мои модули (исходные файлы)? (Архив)

Первая строка каждого файла shoud будет #!/usr/bin/env python.. Это позволяет запускать файл как script, вызывающий интерпретатор неявно, например. в контексте CGI.

Далее должна быть docstring с описанием. Если описание длинное, первая строка должна содержать краткое резюме, которое имеет смысл само по себе, отделенное от остальных символом новой строки.

Весь код, включая операторы импорта, должен следовать за docstring. В противном случае docstring не будет распознаваться интерпретатором, и у вас не будет доступа к нему в интерактивных сеансах (т.е. через 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__ = "[email protected]"
__status__ = "Production"

Статус обычно должен быть одним из "Prototype", "Development" или "Production". __maintainer__ должен быть человеком, который исправит ошибки и внесет улучшения при импорте. __credits__ отличается от __author__ тем, что __credits__ включает людей, которые сообщили об ошибках исправлений, внесенных предложениях и т.д., но на самом деле не написал код.

Здесь у вас есть дополнительная информация, в которой перечислены __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__ и __version__ в качестве признанных метаданных.

Ответ 2

Я сильно одобряю минимальные заголовки файлов, под которыми я подразумеваю только:

• hashbang (строка #!), если это исполняемый файл script
• Модуль docstring
• Импорт, сгруппированный, как описано в ответе voyager.

Все остальное - пустая трата времени, визуальное пространство и активно вводит в заблуждение.

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

Метаданные, такие как авторство и даты, уже поддерживаются вашим исходным контролем. Нет необходимости добавлять менее подробную, ошибочную и устаревшую версию той же самой информации в самом файле.

Я не верю, что есть какие-то другие данные, которые каждый должен поместить во все исходные файлы. У вас может быть какое-то особое требование сделать это, но такие вещи применяются, по определению, только вам. У них нет места в "общих заголовках, рекомендованных для всех".

Ответ 3

Здесь хорошее место для начала: PEP 257, в котором говорится о Docstrings и ссылки на несколько других соответствующих документов.

Ответ 4

Также смотрите PEP 263, если вы используете не-ascii-символы

Аннотация

Этот PEP предлагает ввести синтаксис для объявления кодировки     исходный файл Python. Затем информация о кодировании используется     Python для интерпретации файла с использованием данной кодировки. Наиболее     в частности, это усиливает интерпретацию литератур Юникода в     исходный код и позволяет писать литералы в формате Unicode     с использованием, например, UTF-8 непосредственно в редакторе, поддерживающем Unicode.

Проблема

В Python 2.1 литералы Unicode могут быть написаны только с помощью     Кодировка на основе латинского языка "unicode-escape". Это делает     среда программирования довольно недружественна для пользователей Python, которые живут     и работать в не латинских-1 местах, таких как многие азиатские     страны. Программисты могут писать свои 8-битные строки, используя     любимая кодировка, но связаны с кодировкой "unicode-escape"     для литералов Юникода.

Предлагаемое решение

Я предлагаю сделать кодировку исходного кода Python видимой и     сменяемый на основе исходного файла, используя специальный комментарий     в верхней части файла, чтобы объявить кодировку.

Чтобы Python знал об этом объявлении кодировки,     изменения концепции необходимы в отношении обработки     Данные исходного кода Python.

Определение кодировки

Python по умолчанию будет использовать ASCII в качестве стандартной кодировки, если не будет другого     даны подсказки кодирования.

Чтобы определить кодировку исходного кода, волшебный комментарий должен     помещаться в исходные файлы либо в качестве первого, либо второго     в файле, например:

      # coding=<encoding name>

или (используя форматы, распознаваемые популярными редакторами)

      #!/usr/bin/python
      # -*- coding: <encoding name> -*-

или

      #!/usr/bin/python
      # vim: set fileencoding=<encoding name> :

...

Ответ 5

Ответы, приведенные выше, действительно полны, но если вам нужен быстрый и грязный заголовок для копирования, используйте это:

#!/usr/bin/env python
# # -*- coding: utf-8 -*-

"""Module documentation goes here
"""

Почему это хорошо:

• Первая строка предназначена для пользователей * nix. Он выберет интерпретатор Python в пути пользователя, поэтому автоматически выберет предпочтительный интерпретатор пользователя.
• Второй - это кодировка файла. В настоящее время каждый файл должен иметь связанную кодировку. UTF-8 будет работать везде. Только старые проекты будут использовать другую кодировку.
• И очень простая документация. Он может заполнять несколько строк.

Если вы просто пишете класс в каждом файле, вам даже не нужна документация (она войдет в класс doc).