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源头指南:-)

597152 次浏览
小开
最佳答案

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

第一个是模块的docstring，已经在彼得的回答中解释过了。

我如何组织我的模块(源文件)?(归档)< / >

这使得可以将文件作为脚本运行，隐式调用解释器，例如在CGI上下文中。

如果描述很长，第一行应该是一个简短的总结，它本身是有意义的，用换行符与其余部分分开。

否则，解释器将无法识别文档字符串，并且您将无法在交互会话(即通过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__应该是修复bug并在导入后进行改进的人。__credits__与__author__的不同之处在于，__credits__包括报告错误修复、提出建议等，但实际上并没有编写代码的人。

在这里您有更多的信息，列出__author__， __authors__， __contact__， __copyright__， __license__， __deprecated__， __date__和__version__作为识别的元数据。

小开

如果使用非ascii字符集，也请参阅PEP 263

摘要

这个PEP建议引入一个语法来声明的编码 Python源文件。编码信息然后由 Python解析器使用给定的编码来解释文件。大多数 值得注意的是，这增强了在中的Unicode字面量的解释 源代码，并使它可以编写Unicode文字 在Unicode感知编辑器中直接使用例如UTF-8

问题

在Python 2.1中，Unicode字面值只能使用 基于Latin-1的编码"unicode-escape"。这使得 编程环境对Python用户非常不友好 在非拉丁地区工作，比如很多亚洲地区 国家。方法编写8位字符串 喜欢的编码，但都绑定到“unicode-转义”编码

建议的解决方案

我建议使Python源代码编码既可见又 通过使用特殊注释，可以在每个源文件的基础上更改

.在文件的顶部声明编码 为了让Python知道这个编码声明，需要使用一些 概念的改变对于处理是必要的 Python源代码数据

定义编码

如果没有其他编码，Python将默认使用ASCII作为标准编码

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

      # coding=<encoding name>

或者(使用流行编辑器认可的格式)

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

或

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

.．.

小开

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

  • 如果是可执行脚本，则使用hashbang (#!行)
  • 模块有
  • 按标准方式分组的进口，例如:
  import os    # standard library
import sys


import requests  # 3rd party packages


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

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

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

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

像作者和日期这样的元数据已经由源代码控制系统维护。没有必要在文件本身中添加相同信息的不太详细、错误和过时的版本。

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

小开

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

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

如果你只是在每个文件中写一个类，你甚至不需要文档(它会在类文档中)。

小开

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

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

作为DOC &作者署名，我喜欢简单的串在多行。下面是一个来自示例谷歌样式Python文档字符串 . xml的例子

# -*- 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: ...
"""

额外的格式

  • < p > # EYZ0

    “““

          :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>
"""
  • < p > # EYZ0

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

提交答案