Python文件的常见标头格式是什么?


508

在有关Python编码准则的文档中,我遇到了以下Python源文件的头格式:

#!/usr/bin/env python

"""Foobar.py: Description of what foobar does."""

__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

这是Python世界中标头的标准格式吗?我还可以在标题中添加哪些其他字段/信息?Python专家分享了有关好的Python源标头的指南:-)


这是一个不错的起点:PEP 257,它讨论Docstrings,并链接到其他一些相关文档。
彼得

41
对于那些阅读不同的答案的人来说,一个有用的指南可能是考虑他们期望这些文件头用于什么目的。如果您有一个具体的用例(例如,我的律师说,由于开发人员未能在每个文件中都添加版权信息,法院案件就败了。)然后添加并维护该用例所需的信息。否则,您只会沉迷于OCD恋物癖。
乔纳森·哈特利

哈哈太棒了@JonathanHartley!正如我所说的,对于我自己的项目,“我沉迷于OCD恋物癖”。hahaaha stackoverflow.com/a/51914806/1896134
JayRizzo

Answers:


577

它是Foobar模块的所有元数据。

第一个是docstring模块的,已经在Peter的答案中进行了解释。

如何组织模块(源文件)?(存档)

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

接下来应该是带有说明的文档字符串。如果描述很长,那么第一行应该是一个简短的摘要,该摘要应具有其自身的意义,并以换行符分隔其余部分。

所有代码(包括import语句)都应遵循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__ = "rob@spot.colorado.edu"
__status__ = "Production"

状态通常应为“原型”,“开发”或“生产”之一。__maintainer__应该是将修复错误并进行改进(如果导入)的人。__credits__不同之处在于__author__,这些__credits__人报告了错误修复,提出了建议等,但实际上并未编写代码。

在这里你有更多的信息,上市__author____authors____contact____copyright____license____deprecated____date____version__作为公认的元数据。


7
头信息的创建可以某种方式自动地用于新文件吗?
Hauke

184
我认为导入后的所有这些元数据都是一个坏主意。源控件已经跟踪了适用于单个文件的该元数据部分(例如作者,日期)。在文件本身中放置错误且过时的相同信息副本对我来说似乎是错误的。适用于整个项目的部分(例如许可证,版本控制)似乎更好地位于项目级别,位于其自己的文件中,而不是位于每个源代码文件中。
乔纳森·哈特利

28
完全同意乔纳森·哈特利(Jonathan Hartley)的观点。下一位继承该代码的人有以下三种选择:1)每次编辑代码时都对其进行更新2)保留它,在这种情况下将是不准确的3)删除所有该代码。选项1浪费了他们的时间,特别是因为他们对元数据在收到时是最新的状态绝对没有信心。选项2和3意味着浪费您放在第一位的时间。解决方案:节省每个人的时间,不要放在那儿。
spookylukey 2012年

77
大多数Python文件没有理由使用shebang行。
Mike Graham

15
根据PEP 8,__version__需要紧跟在主文档字符串之后,前后带有空白行。此外,最佳做法是立即在shebang下定义您的字符集# -*- coding: utf-8 -*-
Dave Lasley 2014年

179

我强烈赞成使用最少的文件头,我的意思是:

  • #!如果是可执行脚本,则使用hashbang(行)
  • 模块文档字符串
  • 导入,以标准方式分组,例如:
  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

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

其他所有内容都浪费时间,占用视觉空间,并且会产生误导。

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

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

我不认为每个人都需要将任何其他数据放入其所有源文件中。您可能有这样做的特定要求,但是根据定义,这种情况仅适用于您。它们在“为所有人推荐的通用标题”中没有位置。


23
不能完全同意-在多个位置复制代码是一个罪过,所以为什么对标头信息也这样做。将其放在单个位置(项目根目录),避免在许多文件中维护此类信息的麻烦。
Graeme

13
虽然我同意源代码控制倾向于提供更多有效的作者信息,但有时作者仅分发源代码而没有访问存储库的权限,或者这仅仅是分发工作的方式,例如:从pypi进行集中安装。因此,将作者信息嵌入为模块头仍然是有益的。
婴儿车

6
嘿,普拉姆。我在设想一个实际有用的用例时遇到了麻烦。我可以想象有人想要了解整个项目的作者信息,并且他们可以从一个集中的主要贡献者列表(例如项目的README或docs)中获得价值。但是谁会(a)想知道各个文件的作者身份,以及(b)不能访问源存储库,并且(c)不在乎永远不会有办法判断信息是否不正确或过时了吗?
乔纳森·哈特利2013年

12
许多许可证要求您出于非常充分的理由在每个文件中包括许可证样板。如果有人拿了一个或两个文件而没有许可证就将其重新分发,则接收该文件的人将不知道该文件所使用的许可证,因此必须对其进行追溯(假设他们是出于诚意)。
nyuszika7h 2015年

3
但是,许多模块(scipy,numpy,matplotlib)都具有__version__元数据,我认为这很好,因为程序应该可以访问它并在交互式解释器中快速进行检查。但是,作者和法律信息属于不同的文件。除非您有以下情况的用例if 'Rob' in __author__:
endolith

34

上面的答案确实很完整,但是如果您想要一个快速且脏的标题来复制粘贴,请使用以下命令:

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


5
>“如今,每个文件都必须具有关联的编码。” 这似乎具有误导性。utf8是默认编码,因此最好不指定它。
乔纳森·哈特利

23

如果使用的是非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> :

...


15
值得注意的是,自Python 3起,默认字符集为UTF-8。
nyuszika7h 2015年
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.