Каков общий формат заголовка файлов 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 :-)

Это все метаданные для 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__признанные метаданные.

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

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

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

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

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

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

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

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

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

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

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

Аннотация

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

проблема

В Python 2.1 литералы Unicode могут быть написаны только с использованием кодировки на основе Latin-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> :

...