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

я наткнулся на следующий формат заголовка для исходных файлов Python в документе о руководящих принципах кодирования Python:

#!/usr/bin/env python

"""Foobar.py: Description of what foobar does."""

__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

Это стандартный формат заголовков в мире Python? Какие еще поля / информацию я могу поместить в заголовок? Гуру Python поделитесь своими рекомендациями для хороших заголовков источников Python: -)

4 ответов


его все метаданные для элемента Foobar модуль.

первое-это docstring модуля, что уже объясняется в Петровская.

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

первая строка каждого файла shoud быть #!/usr/bin/env python. это позволяет запускать файл как скрипт, вызывающий интерпретатор неявно, например, в контексте 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__ = "rob@spot.colorado.edu"
__status__ = "Production"

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

здесь у вас есть больше информации, листинг __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__ и __version__ как признанные метаданные.


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

  • hashbang (#! line) если это исполняемый скрипт
  • модуль docstring
  • импорт, сгруппированный, как описано в путешественник’ы ответ.

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

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

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


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

Аннотация

этот ОПТОСОЗ предлагает ввести синтаксис для объявления кодировки исходный файл Python. Информация о кодировке затем используется Python parser для интерпретации файла с использованием данной кодировки. Наиболее в частности, это улучшает интерпретацию литералов Unicode в исходный код и позволяет писать литералы Unicode использование, например, UTF-8 непосредственно в Редакторе Unicode.

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

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

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

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

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

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

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

      # coding=<encoding name>

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

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

или

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

...


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

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

"""Module documentation goes here
   and here
   and ...
"""

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

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

см. также:https://www.python.org/dev/peps/pep-0263/

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