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

Question

我在一篇关于Python编码准则的文档中遇到了以下Python源文件的头格式：

#!/usr/bin/env python

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

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

这是Python世界中头部的标准格式吗？ 在标题中还可以输入哪些字段/信息？ Python专家分享了您对于好的Python源头的指导原则：-）

Answer 1

上面的答案确实很完整，但是如果您想要一个快速而脏的标题来复制粘贴，请使用以下选项：

#!/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/

如果您只是在每个文件中编写一个类，您甚至不需要文档（它将进入类文档中）。

Answer 2

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

第一个是模块的docstring，这已经在Peter's answer中解释过了。

How do I organize my modules (source files)? (Archive)

The first line of each file shoud be #!/usr/bin/env python. This makes it possible to run the file as a script invoking the interpreter implicitly, e.g. in a CGI context.

Next should be the docstring with a description. If the description is long, the first line should be a short summary that makes sense on its own, separated from the rest by a newline.

All code, including import statements, should follow the docstring. Otherwise, the docstring will not be recognized by the interpreter, and you will not have access to it in interactive sessions (i.e. through obj.__doc__) or when generating documentation with automated tools.

Import built-in modules first, followed by third-party modules, followed by any changes to the path and your own modules. Especially, additions to the path and names of your modules are likely to change rapidly: keeping them in one place makes them easier to find.

Next should be authorship information. This information should follow this format:

__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"

Status should typically be one of "Prototype", "Development", or "Production". __maintainer__ should be the person who will fix bugs and make improvements if imported. __credits__ differs from __author__ in that __credits__ includes people who reported bug fixes, made suggestions, etc. but did not actually write the code.

Here您有更多信息，将__author__、__authors__、__contact__、__copyright__、__license__、__deprecated__、__date__和__version__列为可识别的元数据。

Answer 3

我强烈建议使用最少的文件头，我的意思是：

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

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

三组进口，中间只有一个空行。在每个组中，导入被排序。最后一个组“从本地源导入”可以是所示的绝对导入，也可以是显式相对导入。

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

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

源代码管理已经维护了诸如作者身份和日期之类的元数据。不需要在文件中添加相同信息的不太详细、错误和过时的版本。

我不相信每个人都需要把任何其他数据放到他们所有的源文件中。你可能有一些特殊的要求这样做，但这样的事情，根据定义，只适用于你。它们在“为所有人推荐的一般标题”中没有位置。