Я встретил следующий формат заголовка для исходных файлов 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 модуля, который уже объясняется в Питере.
Как организовать мои модули (исходные файлы)? (Архив)
Первая строка каждого файла 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__ в качестве признанных метаданных.
Я сильно одобряю минимальные заголовки файлов, под которыми я подразумеваю только:
#!), если это исполняемый файл scriptВсе остальное - пустая трата времени, визуальное пространство и активно вводит в заблуждение.
Если у вас есть правовые оговорки или информация о лицензировании, он переходит в отдельный файл. Он не должен заражать каждый файл исходного кода. Ваши авторские права должны быть частью этого. Люди должны иметь возможность найти его в вашем файле LICENSE, а не в случайном исходном коде.
Метаданные, такие как авторство и даты, уже поддерживаются вашим исходным контролем. Нет необходимости добавлять менее подробную, ошибочную и устаревшую версию той же самой информации в самом файле.
Я не верю, что есть какие-то другие данные, которые каждый должен поместить во все исходные файлы. У вас может быть какое-то особое требование сделать это, но такие вещи применяются, по определению, только вам. У них нет места в "общих заголовках, рекомендованных для всех".
Здесь хорошее место для начала: PEP 257, в котором говорится о Docstrings и ссылки на несколько других соответствующих документов.
Также смотрите 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> :...
Ответы, приведенные выше, действительно полны, но если вам нужен быстрый и грязный заголовок для копирования, используйте это:
#!/usr/bin/env python
# # -*- coding: utf-8 -*-
"""Module documentation goes here
"""
Почему это хорошо:
Если вы просто пишете класс в каждом файле, вам даже не нужна документация (она войдет в класс doc).