什么是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 ,在Peter的答案中已经解释过了。

我如何组织我的模块(源文件)? (归档)

每个文件的第一行应该是#!/usr/bin/env python 这使得可以将文件作为隐式地调用解释器的脚本来运行,例如在CGI上下文中。

接下来应该是带有说明的文档string。 如果描述很长,第一行应该是一个简短的摘要,这个摘要是有意义的,通过换行符与其余部分分开。

所有的代码,包括import语句,都应该跟在文档string之后。 否则,解释器将无法识别文档string,并且在交互式会话中(即通过obj.__doc__ )或者在使用自动化工具生成文档时,您将无法访问它。

首先导入内置模块,然后导入第三方模块,随后对path和自己的模块进行任何更改。 尤其是,模块path和名称的添加可能会迅速改变:将它们保存在一个地方使得它们更容易find。

接下来应该是作者信息。 这些信息应该遵循以下格式:

 __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__应该是修复bug并在导入时进行改进的人员。 __credits____credits__不同之处在于__credits__包括报告错误修复,提出build议等的人员,但实际上并没有编写代码。

在这里你有更多的信息,列出__author__ __authors____contact__ __copyright__ __license____deprecated____date__ __version__ __author____authors__ __contact__ __copyright____license__ __deprecated____date____version__作为识别的元数据。

我非常喜欢最小的文件头,我的意思是:

  • hashbang( #!行),如果这是一个可执行的脚本
  • 模块文档string
  • import,按航海家的答案中所述分组。

其他一切都是浪费时间,视觉空间,而且是积极的误导。

如果您有合法的免责声明或许可信息,则会将其归入单独的文件。 它不需要感染每个源代码文件。 你的版权应该是这个的一部分。 人们应该能够在你的LICENSE文件中find它,而不是随机的源代码。

元数据(如作者身份和date)已由源代码pipe理员维护。 没有必要在文件本身中添加相同信息的较不详细的,错误的和过时的版本。

我不相信每个人都需要在其所有源文件中join任何其他数据。 你可能有一些特殊的要求,但这样的事情只适用于你。 他们在“为大家推荐的一般标题”中没有地位。

这里是一个很好的开始: PEP 257 ,其中谈到Docstrings,并链接到其他几个相关的文件。

如果您使用的是非ASCII字符集,请参阅PEP 263

抽象

这个PEPbuild议引入一个语法来声明一个Python源文件的编码。 编码信息然后被Pythonparsing器用来使用给定的编码解释文件。 最值得注意的是,这增强了对源代码中Unicode文字的解释,并且使得可以使用例如UTF-8直接在Unicode感知编辑器中编写Unicode文字。

问题

在Python 2.1中,只能使用基于Latin-1的编码“unicode-escape”编写Unicode字面值。 这使得编程环境对于生活和工作在非拉丁语-1语言环境(如亚洲许多国家/地区)的Python用户来说相当不友善。 程序员可以使用喜欢的编码来编写他们的8位string,但绑定到Unicode文字的“unicode-escape”编码。

build议的解决scheme

我build议通过使用文件顶部的特殊注释来声明编码,使每个源文件基础上的Python源代码编码可见且可更改。

为了使Python知道这个编码声明,需要对Python源代码数据的处理进行一些概念上的改变。

定义编码

如果没有给出其他编码提示,Python将默认为ASCII作为标准编码。

要定义源代码编码,必须将魔术注释作为文件的第一行或第二行放入源文件,例如:

  # coding=<encoding name> 

或者(使用stream行编辑认可的格式)

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

要么

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