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

Question

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

#!/usr/bin/env python

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

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

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

Answer 1

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

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

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

Первая строка каждого файла должна быть #!/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__ включает людей, которые сообщили об исправлениях ошибок, внесли предложения и т. Д., Но фактически не написали код.

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

Answer 2

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

• hashbang (#! строка), если это исполняемый скрипт
• Модуль документации
• Импорт, сгруппированный стандартным способом, например:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

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

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

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

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

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

Answer 3

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

#!/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/

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

Answer 4

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

Аннотация

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

Задача

В Python 2.1 литералы Unicode могут быть написаны только с использованием Латинская-1 кодировка "Unicode-escape". Это делает среда программирования довольно недружественная для пользователей Python, которые живут и работать в не-Latin-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> :

...