Python Docstring 风格和写法学习
什么是Python Docstring
和Java类似,Python也通过注释形式的Docstring给程序、类、函数等建立文档。通过Docstring建立的文档不仅对人来说有更好的可读性,也能够让IDE等工具自动识别使用函数、类、变量等的一些限制,从而帮助我们更好地理解程序。
Python Docstring 的三种风格
总的来说,Python Docstring有三种主要风格,分别是reST风格、Google风格和Numpy风格:
reST风格
reST的全称是reStructredText。通过以冒号开头的几个关键字来说明类、函数中的参数、返回值、异常等。
例如我们要造一个双向链表的轮子,我们新建一个DoubleLinkList.py
文件。其中包含两个类,一个是双向链表的节点类DLLNode
,一个是双向链表类DoubleLinkList
。
首先看一下DLLNode
类。
class DLLNode(object):
"""
The definition of node of double link list.
:param val: The value of a node.
:param prev: The pointer of the previous node of this node.
:param next: The pointer of the next node of this node.
:type val: Any
:type prev: DLLNode, default None
:type next: DLLNode, default None
"""
def __init__(self, val, prev=None, next=None):
self.val = val
self.prev = prev
self.next = next
我们可以看到在DLLNode
类中通过三个双引号"""
建立了对DLLNode类的docstring。注意docstring必须位于任意其他代码的开头。在类的docstring中,常见的有如下声明标记:
:param <类属性名称>: <描述>
:type <类属性名称>: <类型>
其中,类型除了基本类型,如int
,float
,str
等,还可以是列表类型List[type]
,元组类型Tuple[types]
,以及字典类型Dict[KeyType, ValueType]
等,还可以是各种模块中定义的类型。注意当类型为列表、元组或字典时与Python本身自带类型的不同。
这里我们不需要再对DLLNode
类中 __init__()
函数添加docstring。在生成文档时,Python会自动将类的docstring复制给它的__init__()
函数。
下面再看一下DoubleLinkList
类。
class DoubleLinkList(object):
"""
The definition of double link list.
:param head: The head pointer of the list.
:type head: DLLNode
"""
def __init__(self, head):
self.head = head
def insert_node(self, val, node):
"""
Insert a node before the node which data is val.
:param val: The value to be find to insert a node before it.
:param node: The node ready to insert.
:type val: Any
:type node: DLLNode
"""
pass
def remove_node(self, val):
"""
Remove a node which data is val.
:param val: The val of node to be removed.
"""
pass
def length(self):
"""
Returns the length of this link table.
:return: The length of this link table.
:rtype: int
"""
pass
def search_node(self, val):
"""
Search the first position of node which data equals val.
:param val: The value to be searched.
:return: The position of val first appeared.
:rtype: int
"""
pass
def update_node(self, position, val):
"""
Update the node in position by val.
:param position: The position of the node to be updated.
:param val: The target value of updated node.
:type position: int
:type val: Any
"""
pass
假设我们给DoubleLinkList
类设计了增删改查和求长度五个方法。我们可以看到,除了:param
和:type
外,还有几个新的标签,列举如下:
:return: <对返回值的描述>
:rtype: <返回值类型>
:raises: <可能抛出的异常列表>
当我们在docstring中为函数指定了:param
和:type
以后,如果在调用函数时给函数传入了错误的参数类型,IDE会发出warning,可以提醒我们传入正确的参数类型。
Google Style
除了reST风格,Google Style也是一种常见的docstring规范。
仍以上文的DoubleLinkList
为例。Google Style的docstring如下:
class DLLNode(object):
"""
The definition of node of double link list.
Args:
val (Any): The value of Node.
prev (DLLNode): The previous node of this node.
next (DLLNode): The next node of this node.
"""
def __init__(self, val, prev=None, next=None):
self.val = val
self.prev = prev
self.next = next
class DoubleLinkList(object):
"""
The definition of double link list.
Args:
head (DLLNode): The head pointer of the link list.
"""
def __init__(self, head):
self.head = head
def insert_node(self, val, node):
"""
Insert a node before the node which data is val.
Args:
val (Any): The value to be find to insert a node before it.
node (DLLNode): The node ready to insert.
"""
pass
def remove_node(self, val):
"""
Remove a node which data is val.
Args:
val (DLLNode): The val of node to be removed.
"""
pass
def length(self):
"""
Returns the length of this link table.
Returns:
int: The length of this link list.
"""
pass
def search_node(self, val):
"""
Search the first position of node which data equals val.
Args:
val: The value to be searched.
Returns:
int: The first position of the searched value.
"""
pass
def update_node(self, position, val):
"""
Update the node in position by val.
Args:
position (int): The position of node to be updated.
val: The new value of target.
"""
pass
与reST风格不同,Google Style将所有的参数写在Args
标签下,而所有的返回值写在Returns
标签下。我个人认为比起reST风格,Google Style的可读性要更好一些。在Args
标签下,可以在参数名称后面加 (类型)
来确定参数的类型,同样可以起到对参数类型的限制作用。
Numpy Style
Numpy是矩阵分析、科学计算、机器学习中都会用到的常见Python程序库。其文档详实完整,也是程序员们学习的典范之一。Numpy也有自己独特的Python Docstring风格。我们仍以DoubleLinkList
模块为例来说明。
class DLLNode(object):
"""
The definition of node of double link list.
Parameters
----------
val : Any
The value of node.
prev : DLLNode
The previous node of this node.
next : DLLNode
The next node of this node.
Attributes
----------
val : Any
The value of node.
prev : DLLNode
The previous node of this node.
next : DLLNode
The next node of this node.
"""
def __init__(self, val, prev=None, next=None):
self.val = val
self.prev = prev
self.next = next
class DoubleLinkList(object):
"""
The definition of double link list.
Parameters
----------
head : DLLNode
The head pointer of the link list.
Attributes
----------
head : DLLNode
The head pointer of the link list.
"""
def __init__(self, head):
self.head = head
def insert_node(self, val, node):
"""
Insert a node before the node which data is val.
Parameters
----------
val:
The value to be find to insert a node before it.
node : DLLNode
The node ready to insert.
"""
pass
def remove_node(self, val):
"""
Remove a node which data is val.
Parameters
----------
val :
The val of node to be removed.
"""
pass
def length(self):
"""
Returns the length of this link table.
Returns
-------
int
The length of this link list.
"""
pass
def search_node(self, val):
"""
Search the first position of node which data equals val.
Parameters
----------
val:
The value to be searched.
Returns
-------
int
The first position of the searched value.
"""
pass
def update_node(self, position, val):
"""
Update the node in position by val.
Parameters
----------
position :int
The position of node to be updated.
val:
The new value of target.
"""
pass
和Google Style不同,Numpy Style采用如下格式描述一个类:
"""
类描述
Parameters
----------
参数 : [类型]
参数的描述
Attributes
----------
属性 : [类型]
属性的描述
"""
其中Parameters和Attributes可以不一样。具体区别我也不是搞得很明白。
函数描述如下
"""
函数描述
Parameters
----------
参数 : [类型]
参数的描述
Returns
-------
类型
返回值的描述
Raises
------
异常名称
异常描述
Examples
--------
范例描述
Yields(仅针对生成器函数)
------
类型
生成器返回值描述
Note
----
注释内容
"""
Numpy风格的docstring似乎不能用sphinx来生成html形式的文档。
小结
本文介绍了Python程序设计中常见的三种docstring的风格,其中我个人认为Google Style相比之下是最好的一个,它既可以采用Sphinx来生成HTML格式的文档,也可以直接在命令行中通过help函数获得可读性更高的文档。但在Pycharm等IDE中,默认支持的是reST风格的。具体如何使用,就要看自己的喜好和项目要求了。
Python Docstring 风格和写法学习的更多相关文章
- python代码风格-PEP8
转载自http://www.douban.com/note/134971609/ Python 的代码风格由 PEP 8 描述.这个文档描述了 Python 编程风格的方方面面.在遵守这个文档的条件下 ...
- 【转】python代码风格-PEP8
转载自http://www.douban.com/note/134971609/ Python 的代码风格由 PEP 8 描述.这个文档描述了 Python 编程风格的方方面面.在遵守这个文档的条件下 ...
- 编写高质量代码改善python程序91个建议学习01
编写高质量代码改善python程序91个建议学习 第一章 建议1:理解pythonic的相关概念 狭隘的理解:它是高级动态的脚本编程语言,拥有很多强大的库,是解释从上往下执行的 特点: 美胜丑,显胜隐 ...
- Day1 老男孩python自动化运维课程学习笔记
2017年1月7日老男孩python自动化运维课程正式开课 第一天学习内容: 上午 1.python语言的基本介绍 python语言是一门解释型的语言,与1989年的圣诞节期间,吉多·范罗苏姆为了在阿 ...
- 如何使用 Pylint 来规范 Python 代码风格
如何使用 Pylint 来规范 Python 代码风格 转载自https://www.ibm.com/developerworks/cn/linux/l-cn-pylint/ Pylint 是什么 ...
- python实用库:PrettyTable 学习
python实用库:PrettyTable 学习 PrettyTable说明 PrettyTable 是python中的一个第三方库,可用来生成美观的ASCII格式的表格,十分实用. 以下为官方介绍: ...
- Python 编码风格指南
原文:http://python.jobbole.com/84618/ 本文超出 PEP8 的范畴以涵盖我认为优秀的 Python 风格.本文虽然坚持己见,却不偏执.不仅仅涉及语法.模块布局等问题,同 ...
- 【Python】Java程序员学习Python(三)— 基础入门
一闪一闪亮晶晶,满天都是小星星,挂在天上放光明,好像许多小眼睛.不要问我为什么喜欢这首歌,我不会告诉你是因为有人用口琴吹给我听. 一.Python学习文档与资料 一般来说文档的资料总是最权威,最全面的 ...
- 《Think Python》第16章学习笔记
目录 <Think Python>第16章学习笔记 16.1 Time 16.2 纯函数(Pure functions) 16.3 修改器(Modifiers) 16.4 原型 vs. 方 ...
随机推荐
- List、Set、Map集合的遍历方法
一.List集合遍历 public class TraversingList { /** * @author zhuxun describe: 定一个List集合并遍历 */ /** 定义一个List ...
- 2.Vue调试工具vue-devtools的安装步骤和使用
1.安装步骤: 打开谷歌浏览器设置 -->扩展程序 -->勾选开发者模式 --->加载已解压的扩展程序 --->选择“chrome扩展”文件夹即可:
- 09_Azkaban案例实践2_Command多job工作流flow
1.Command类型多job工作流flow 1.创建有依赖关系的多个job描述:第一个job:foo.job # foo.job type=command command=echo foo 2.第二 ...
- 各位大佬Python的第一部分道基础题已经整理好了,希望大家面试的时候能用的上。
Python的第一部分道基础题,希望大家面试的时候能用的上. 1.为什么学习Python? Python是目前市面上,我个人认为是最简洁.最优雅.最有前途.最全能的编程语言,没有之一. 2.通过什么途 ...
- webpac4k运行webpack .\src\main.js .\dist\bundle.js打包出错
打包的命令格式:webpack 要打包的文件的路径 打包好的输出文件的路径 运行webpack .\src\main.js .\dist\bundle.js 提示错误,错误信息如下: WARNING ...
- 【H5】 经纬度位置获取navigator.geolocation.getCurrentPosition
navigator.geolocation.getCurrentPosition(function(){})经度 : coords.longitude 纬度 : coords.latitude 准确度 ...
- oracle 12c 安装补丁报错
环境: centos 7.5 oracle 12.2.0.1 报错: 执行一下报错: 更新dba_registry_sqlpatch $ORACLE_HOME/OPatch/datapatch -ve ...
- Java并发包--线程池框架
转载请注明出处:http://www.cnblogs.com/skywang12345/p/3509903.html 线程池架构图 线程池的架构图如下: 1. Executor 它是"执行者 ...
- shiro框架的UsernamePasswordToken与对应Realm中的AuthenticationToken的一点比较(转)
这里以简单的登陆为例子 控制器对应的登陆方法: @RequestMapping(value = "/login", method = RequestMethod.GET) publ ...
- Python 2--序列