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 ，已经在Peter的答案中进行了解释。

如何组织模块（源文件）？ （存档）

每一个文件的第一行应该是#!/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__包括谁报告bug修复，提出建议等，但实际上并无写代码的人。

在这里，您__author__更多信息，列出__author__ __authors__ ， __contact__ __copyright__ __license__ ， __deprecated__ ， __date__ __version__ __author__ ， __authors__ __contact__ __copyright__ ， __license__ __deprecated__ ， __date__和__version__做为公认的元数据。

---

#2楼

若是使用的是非ASCII字符集，另请参阅PEP 263

抽象

该PEP建议引入一种语法，以声明Python源文件的编码。 而后，Python解析器将使用编码信息使用给定的编码来解释文件。 最值得注意的是，这加强了源代码中Unicode文字的解释，并使得能够在例如Unicode的编辑器中直接使用UTF-8编写Unicode文字。

问题

在Python 2.1中，只能使用基于Latin-1的编码“ unicode-escape”编写Unicode文字。 这使得编程环境对在许多亚洲国家这样的非拉丁1语言环境中生活和工做的Python用户而言至关不利。 程序员可使用最喜欢的编码来编写其8位字符串，可是绑定到Unicode文字的“ unicode-escape”编码。

拟议的解决方案

我建议经过在文件顶部使用特殊注释来声明该编码，从而使每一个源文件均可以看到和更改Python源代码。

为了使Python知道此编码声明，在处理Python源代码数据方面须要进行一些概念上的更改。

定义编码

若是没有其余编码提示，Python将默认使用ASCII做为标准编码。

要定义源代码编码，必须将魔术注释做为源文件的第一行或第二行放置在源文件中，例如：

# coding=<encoding name>

或（使用流行的编辑器承认的格式）

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

要么

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

...

---

#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中）。

---

#4楼

我强烈同意使用最少的文件头，个人意思是：

• hashbang（ #!行）（若是这是可执行脚本）
• 模块文档字符串
• 导入，以标准方式分组，例如：

import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule

即。 三组进口，它们之间有一个空白行。 在每一个组中，对进口进行排序。 最后一组，从本地来源进口，能够是如图所示的绝对进口，也能够是明确的相对进口。

其余全部内容都浪费时间，占用视觉空间，而且会产生误导。

若是您有法律免责声明或许可信息，它将进入一个单独的文件中。 它不须要感染每一个源代码文件。 您的版权应该是其中的一部分。 人们应该可以在您的LICENSE文件中找到它，而不是随机的源代码。

源代码控件已经维护了诸如做者身份和日期之类的元数据。 无需在文件自己中添加更详细，错误且过期的相同信息版本。

我不认为每一个人都须要将任何其余数据放入其全部源文件中。 您可能有这样作的特定要求，可是根据定义，这些事情仅适用于您。 它们在“为全部人推荐的通用标题”中没有位置。