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