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源文件头部的建议 :-)
5 个回答
上面的回答已经很全面了，但如果你想要一个简单易用的头部代码，可以直接复制粘贴，使用这个：
#!/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/
如果你每个文件只写一个类，其实就不需要这个文档说明（说明可以写在类的文档里）。
我非常支持简洁的文件头，也就是说，只需要包含以下内容：
#!/usr/bin/env python # [1]
"""\
This script foos the given bars [2]
Usage: myscript.py BAR1 BAR2
"""
import os # standard library, [3]
import sys
import requests # 3rd party packages
import mypackage # local source
[1]如果这个文件可以直接执行，比如你可以用myscript.py或myscript来运行它，或者用python myscript.py来执行，那么就需要加上一个叫做“哈希bang”的东西。虽然在最后一种情况下不需要用到哈希bang，但加上它可以让用户选择怎么执行这个文件。如果这个文件只是一个模块，供其他Python文件使用，那就不需要加哈希bang。[2]模块的文档字符串[3]导入的模块，按照标准的方式分组，也就是分成三组，每组之间留一行空行。在每组内部，导入的模块要排序。最后一组是从本地源导入的，可以是绝对导入，也可以是明确的相对导入。
其他的内容都是浪费时间——对作者和后续的维护者来说都是如此。这样会占用文件顶部宝贵的视觉空间，放一些更适合在其他地方记录的信息，而且这些信息很容易过时，甚至可能会误导人。
如果你有法律声明或许可信息，应该放在一个单独的文件里，不需要在每个源代码文件中都出现。你的版权信息也应该包含在这个文件里。人们应该能在你的 LICENSE 文件中找到这些信息，而不是在随机的源代码中。
像作者和日期这样的元数据已经由你的源代码管理工具维护了。没有必要在文件中添加一个不够详细、可能错误且过时的版本。
我认为没有其他数据是每个人都需要放在所有源文件中的。你可能有一些特定的要求，但这些要求只适用于你自己。它们不应该出现在“推荐给所有人的通用文件头”中。
这段内容是关于Foobar模块的所有元数据。
第一个是模块的docstring，这个在Peter的回答中已经解释过了。
我该如何组织我的模块（源文件）？（存档）
每个文件的第一行应该是
#!/usr/bin/env python。 这样可以让你在某些情况下直接运行这个文件，就像在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__ = "rob@spot.colorado.edu" __status__ = "Production"状态通常应该是“Prototype”（原型）、“Development”（开发）或“Production”（生产）。
__maintainer__应该是负责修复bug和进行改进的人。如果有其他人报告了bug修复、提出建议等，但没有实际编写代码，他们的信息应该放在__credits__中，这和__author__是不同的。
这里有更多信息，列出了__author__、__authors__、__contact__、__copyright__、__license__、__deprecated__、__date__和__version__等被认可的元数据。