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语句）都应遵循docstring。否则，解释器将无法识别docstring，并且您无法在交互式会话中访问它（即通过{{ 1}}）或使用自动化工具生成文档时。

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

接下来应该是作者信息。此信息应遵循以下格式：
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__包括报告错误修复，提出建议等但实际上并未编写代码的人。

Here您有更多信息，列有__credits__，__author__，__authors__，__contact__，__copyright__，__license__， __deprecated__和__date__作为已识别的元数据。

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”。这使得       编程环境对生活的Python用户不太友好       并且在非拉丁语1区域工作，例如许多亚洲人       国家。程序员可以使用。编写8位字符串       最喜欢的编码，但是绑定到“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> :
...

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

4 个答案:

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

摘要

问题

提议的解决方案

定义编码