文档章节

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

j
 javail
发布于 01/19 18:43
字数 1542
阅读 262
收藏 1

在有关Python编码准则的文档中,我遇到了以下Python源文件的头格式:

#!/usr/bin/env python

"""Foobar.py: Description of what foobar does."""

__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

这是Python世界中标头的标准格式吗? 我还可以在标题中添加哪些其他字段/信息? Python专家分享了有关好的Python源标头的指南:-)


#1楼

Foobar模块的所有元数据。

第一个是模块的docstring ,已经在Peter的答案中进行了解释。

如何组织模块(源文件)? (存档)

每个文件的第一行应该是#!/usr/bin/env python 这样就可以将文件作为脚本运行,例如在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__应该是修复错误并进行改进(如果导入)的人。 __credits__不同于__author____credits__包括谁报告bug修复,提出建议等,但实际上并没有写代码的人。

在这里,__author__更多信息,列出__author__ __authors____contact__ __copyright__ __license____deprecated____date__ __version__ __author____authors__ __contact__ __copyright____license__ __deprecated____date____version__作为公认的元数据。


#2楼

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

抽象

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

问题

在Python 2.1中,只能使用基于Latin-1的编码“ unicode-escape”编写Unicode文字。 这使得编程环境对在许多亚洲国家这样的非拉丁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> :

...


#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中)。


#4楼

我强烈赞成使用最少的文件头,我的意思是:

  • hashbang( #!行)(如果这是可执行脚本)
  • 模块文档字符串
  • 导入,以标准方式分组,例如:
  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

即。 三组进口,它们之间有一个空白行。 在每个组中,对进口进行排序。 最后一组,从本地来源进口,可以是如图所示的绝对进口,也可以是明确的相对进口。

其他所有内容都浪费时间,占用视觉空间,并且会产生误导。

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

源代码控件已经维护了诸如作者身份和日期之类的元数据。 无需在文件本身中添加更详细,错误且过时的相同信息版本。

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

本文转载自:https://el.sofbug.com/question/6OJP

j
粉丝 5
博文 1155
码字总数 0
作品 0
深圳
私信 提问
HTTPie 2.0.0 发布,命令行的 HTTP 工具包

HTTPie 是一个开源的命令行的 HTTP 工具包,提供命令行交互方式来访问 HTTP 服务。HTTPie 2.0.0 现已发布,该版本具体更新内容如下: 删除了对 Python 2.7 的支持(现在需要 Python 3.6+)。...

白开水不加糖
01/14
1.6K
2
为什么有头文件和.cpp文件? [关闭]

7年前关闭。 为什么C ++具有头文件和.cpp文件? #1楼 这是声明接口的预处理器方式。 您将接口(方法声明)放入头文件中,并将实现放入cpp中。 使用您的库的应用程序只需要知道接口,就可以通...

javail
01/22
8
0
python数据存储--JSON

HTML正文存储为两种格式:JSON和CSV。 存储为JSON: 首先利用Requests访问http://seputu.com获取HTML文档: 取每章节 接下来将数据存储为JSON。 python对JSON文件的操作分为编码和解码,通过...

guguobao
2018/08/21
0
0
使用 Black 自由格式化 Python

在我们覆盖 7 个 PyPI 库的系列文章中了解解决 Python 问题的更多信息。 Python 是当今使用最多的流行编程语言之一,因为:它是开源的,它有广泛的用途(例如 Web 编程、业务应用、游戏、科学...

作者: Moshe Zadka
2019/05/16
0
0
Tengine + uwsgi + django平台搭建

环境介绍: [root@localhost opsdev]# nginx -vTengine version: Tengine/2.0.3 (nginx/1.4.7)[root@localhost opsdev]# cat /etc/redhat-release CentOS release 6.4 (Final)[root@localhos......

lovelace521
2018/06/26
0
0

没有更多内容

加载失败,请刷新页面

加载更多

乳山哪里可以开医院门诊发票-中国新闻网

乳山哪里可以开医院门诊发票【152 * 9б 28 * 21 б9】陈生,诚、信、合、作,保、真、售、后、保、障、长、期、有、效。adb的全称为Android Debug Bri...

18281711164
今天
54
0
庄河哪里可以开医院门诊发票-中国新闻网

庄河哪里可以开医院门诊发票【152 * 9б 28 * 21 б9】陈生,诚、信、合、作,保、真、售、后、保、障、长、期、有、效。adb的全称为Android Debug Bri...

18249433684
今天
55
0
IntelliJ 如何找到项目中 Deprecated 的方法

在一个项目中,如果我们标记了某些元素为 Deprecated 的话,如何让我们能够快速找到? 简单来说,你可以对项目进行 Code Inspection。 选择 Analyze > Inspect Code 在弹出的对话框中,对整个...

honeymoose
今天
85
0
Java中的排序算法:冒泡排序

学习了一种新的排序算法:冒泡排序,冒泡排序是一种交换排序,指比较相邻的两个元素,如果前者比后者大,就交换位置,继续进行比较。 通过例子来实现: import java.util.Arrays; public cl...

北芷南姜
今天
73
0
OSChina 周五乱弹 —— 你不仅要背负工作,还要背负领导

Osc乱弹歌单(2020)请戳(这里) 【今日歌曲】 @薛定谔的兄弟 :分享洛神有语创建的歌单「我喜欢的音乐」: 《Cold Rain》- AniFace 手机党少年们想听歌,请使劲儿戳(这里) @明月依稀 :露...

小小编辑
今天
267
2

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部