我在一份关于Python编码指南的文档中遇到了以下Python源文件的头文件格式:
#!/usr/bin/env python
"""Foobar.py: Description of what foobar does."""
__author__ = "Barack Obama"
__copyright__ = "Copyright 2009, Planet Earth"
这是Python世界中的标头格式吗? 我还可以在标题中放入哪些字段/信息? Python大师们分享了一些好的Python源头的指南:-)
它是Foobar模块的所有元数据。
第一个是模块的文档字符串，在Peter的回答中已经解释过了。
How do I organize my modules (source files)? (Archive) The first line of each file shoud be #!/usr/bin/env python. This makes it possible to run the file as a script invoking the interpreter implicitly, e.g. in a CGI context. Next should be the docstring with a description. If the description is long, the first line should be a short summary that makes sense on its own, separated from the rest by a newline. All code, including import statements, should follow the docstring. Otherwise, the docstring will not be recognized by the interpreter, and you will not have access to it in interactive sessions (i.e. through obj.__doc__) or when generating documentation with automated tools. Import built-in modules first, followed by third-party modules, followed by any changes to the path and your own modules. Especially, additions to the path and names of your modules are likely to change rapidly: keeping them in one place makes them easier to find. Next should be authorship information. This information should follow this format: __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" Status should typically be one of "Prototype", "Development", or "Production". __maintainer__ should be the person who will fix bugs and make improvements if imported. __credits__ differs from __author__ in that __credits__ includes people who reported bug fixes, made suggestions, etc. but did not actually write the code.
这里你有更多的信息，列出__author__， __authors__， __contact__， __copyright__， __license__， __depreced__， __date__和__version__作为公认的元数据。
如果使用非ascii字符集，也请参阅PEP 263
Abstract This PEP proposes to introduce a syntax to declare the encoding of a Python source file. The encoding information is then used by the Python parser to interpret the file using the given encoding. Most notably this enhances the interpretation of Unicode literals in the source code and makes it possible to write Unicode literals using e.g. UTF-8 directly in an Unicode aware editor. Problem In Python 2.1, Unicode literals can only be written using the Latin-1 based encoding "unicode-escape". This makes the programming environment rather unfriendly to Python users who live and work in non-Latin-1 locales such as many of the Asian countries. Programmers can write their 8-bit strings using the favorite encoding, but are bound to the "unicode-escape" encoding for Unicode literals. Proposed Solution I propose to make the Python source code encoding both visible and changeable on a per-source file basis by using a special comment at the top of the file to declare the encoding. To make Python aware of this encoding declaration a number of concept changes are necessary with respect to the handling of Python source code data. Defining the Encoding Python will default to ASCII as standard encoding if no other encoding hints are given. To define a source code encoding, a magic comment must be placed into the source files either as first or second line in the file, such as: # coding=<encoding name> or (using formats recognized by popular editors) #!/usr/bin/python # -*- coding: <encoding name> -*- or #!/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文档字符串的示例
# -*- 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' # ---------------------------------------------------------------------------
我也报告了类似的其他答案
__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"
