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

Foobar 模块的所有元数据。

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

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

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

接下来应该是带有描述的文档字符串。如果描述很长，第一行应该是一个简短的摘要，它本身就有意义，与换行休息。

所有代码，包括 import 语句，都应遵循文档字符串。 否则，解释器将无法识别文档字符串，并且您将无法在交互式会话中访问它（即通过 @987654327 @) 或使用自动化工具生成文档时。

首先导入内置模块，然后是第三方模块，然后是对路径和您自己的模块的任何更改。特别是，添加模块的路径和名称可能会变化迅速：将它们放在一个地方更容易找到。

接下来应该是作者信息。此信息应遵循以下格式：

__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__ 包括报告错误修复、提出建议等但实际上并未编写代码的人。

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

Answer 2

如果您使用的是非 ascii 字符集，另请参阅 PEP 263

摘要

本 PEP 提议引入一种语法来声明 一个 Python 源文件。然后编码信息被 Python 解析器使用给定的编码来解释文件。最多 值得注意的是，这增强了 Unicode 文字的解释 源代码并使编写 Unicode 文字成为可能 使用例如UTF-8 直接在支持 Unicode 的编辑器中。

问题

在 Python 2.1 中，Unicode 文字只能使用 基于 Latin-1 的编码“unicode-escape”。这使得 编程环境对居住的 Python 用户相当不友好 并在非拉丁 1 地区工作，例如许多亚洲人 国家。程序员可以使用 最喜欢的编码，但绑定到“unicode-escape”编码 对于 Unicode 文字。

建议的解决方案

我建议让 Python 源代码编码既可见又 可通过使用特殊注释在每个源文件的基础上进行更改 在文件顶部声明编码。

为了让 Python 知道这个编码声明，需要使用一些 关于处理的概念改变是必要的 Python 源代码数据。

定义编码

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

要定义源代码编码，必须使用魔术注释 作为第一个或第二个放入源文件中 文件中的一行，如：

      # coding=<encoding name>

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

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

或

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

...

Answer 3

我强烈支持最小的文件头，我的意思是：

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

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  from mypackage import (  # local source
      mymodule,
      myothermodule,
  )

即。三组导入，它们之间有一个空行。在每个组中，对导入进行排序。最后一组，从本地源导入，可以是如图所示的绝对导入，也可以是显式相对导入。

其他一切都是浪费时间和视觉空间，并且具有误导性。

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

作者和日期等元数据已由您的源代码管理部门维护。无需在文件本身中添加相同信息的不那么详细、错误和过时的版本。

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

Answer 4

上面的答案真的很完整，但是如果你想要一个快速而肮脏的标题来复制和粘贴，使用这个：

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

我在一些项目中使用的是 Linux 机器第一行中的这一行：

# -*- coding: utf-8 -*-

作为 DOC 和作者，我喜欢多行中的简单字符串。这是来自 Example Google Style Python Docstrings

的示例

# -*- coding: utf-8 -*-
"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

.. _Google Python Style Guide:
   http://google.github.io/styleguide/pyguide.html

"""

也可以添加：

        """
        @Author: ...
        @Date: ....
        @Credit: ...
        @Links: ...
        """

其他格式

• Meta-information markup | devguide

  """

        :mod:`parrot` -- Dead parrot access
        ===================================
  
        .. module:: parrot
           :platform: Unix, Windows
           :synopsis: Analyze and reanimate dead parrots.
        .. moduleauthor:: Eric Cleese <eric@python.invalid>
        .. moduleauthor:: John Idle <john@python.invalid>
    """
  

• /common-header-python

        #!/usr/bin/env python3  Line 1
        # -*- coding: utf-8 -*- Line 2
        #----------------------------------------------------------------------------
        # Created By  : name_of_the_creator   Line 3
        # Created Date: date/month/time ..etc
        # version ='1.0'
        # ---------------------------------------------------------------------------