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模块的,已经在彼得的答案中解释过了.

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

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

接下来应该是带有描述的docstring.如果描述很长,则第一行应该是一个简单的摘要,它自己有意义,通过换行符与其余部分分开.

所有代码(包括import语句)都应遵循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"

状态通常应为"原型","开发"或"生产"之一.__maintainer__应该是那些将修复错误并在导入时进行改进的人.__credits__不同之处__author__在于__credits__包括报告错误修复,提出建议等但实际上没有编写代码的人.

在这里你有更多的信息,上市__author__,__authors__,__contact__,__copyright__,__license__,__deprecated__,__date__和__version__作为公认的元数据.

Answer 2

我强烈支持最小的文件头,我的意思是:

• #!如果这是一个可执行脚本,则为hashbang(行)
• 模块docstring
• 以标准方式分组的进口,例如:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

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

其他一切都是浪费时间,视觉空间,并且积极误导.

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

源控件已经保留了作者身份和日期等元数据.无需在文件本身中添加相同信息的不太详细,错误和过时的版本.

我不相信每个人都需要在其所有源文件中添加任何其他数据.您可能有一些特殊要求,但根据定义,这些内容仅适用于您.他们没有"为每个人推荐的通用标题".

Answer 3

上面的答案非常完整,但是如果你想要一个快速而脏的标题来复制'粘贴,请使用:

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

Answer 4

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

抽象

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

问题

在Python 2.1中,Unicode文字只能使用基于Latin-1的编码"unicode-escape"编写.这使得编程环境对在非拉丁语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> :

...

Answer 5

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

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

作为文档和作者信用，我喜欢多行中的简单字符串。这是示例 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: ...
        """

附加格式

• 元信息标记| 开发指南

  ”“”

        :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'
        # ---------------------------------------------------------------------------
  

我也与其他答案类似地报告

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