一 以注释方式为类添加帮助文档
我们知道,Python中可以使用help('模块名')或者help(类名)的形式来查看一个模块或者类的帮助文档,我们也可以为自定义的类添加帮助文档,并用help进行查看.Python中用三对双引号可以进行多行注释,当我们把这种注释内容放到一个类或者函数定义的下面时,它会自动被当作该类或者函数的帮助文档.请看下面的类:
docts.py:
#coding:utf-8
class MyMath:
"""
A class with math operator
"""
def add(self,x,y):
"""
Function to get the sum of x and y.
Example:
>>> mt=MyMath()
>>> mt.add(1,2)
3
>>> mt.add(3,-2)
1
>>> mt.add(2.4,1.5)
3.9
"""
return x+y
我们用三对双引号对类和其成员函数add进行了注释,那么我们就可以通过下面的方式查看该模块和类的帮助.
查看模块docts.py:
>>> help('docts')
Help on module docts:
NAME
docts - #coding:utf-8
FILE
/home/hyman/projects/pythonTs/docts.py
CLASSES
MyMath
class MyMath
| A class with math operator
|
| Methods defined here:
|
| add(self, x, y)
| Function to get the sum of x and y.
| Example:
| >>> mt=MyMath()
| >>> mt.add(1,2)
| 3
| >>> mt.add(3,-2)
查看类MyMath:
>>> from docts import MyMath
>>> help(MyMath)
Help on class MyMath in module docts:
class MyMath
| A class with math operator
|
| Methods defined here:
|
| add(self, x, y)
| Function to get the sum of x and y.
| Example:
| >>> mt=MyMath()
| >>> mt.add(1,2)
| 3
| >>> mt.add(3,-2)
| 1
| >>> mt.add(2.4,1.5)
| 3.9
(END)
二 利用doctest进行文档测试
我们在上面的模块中加入下面这段代码:
if __name__=='__main__':
import doctest
doctest.testmod()
请注意我们写的注释中的下面这段内容:
Example:
>>> mt=MyMath()
>>> mt.add(1,2)
3
>>> mt.add(2.4,1.5)
3.9
当我们在终端中运行该模块时,导入doctest.testmod()会自动在终端测试我们所写的这些例子:
hyman@hyman-VirtualBox:~/projects/pythonTs$ python docts.py
hyman@hyman-VirtualBox:~/projects/pythonTs$
运行之后你会发现,什么结果都没打印,那是因为我们写的例子是正确的,我们可以修改下例子中代码,把运算结果改错
>>> mt.add(3,-2)
0
再运行就报错了(注意写运行示例时,>>>和python语句之间要有一个空格,否则会出现语法错误.)
hyman@hyman-VirtualBox:~/projects/pythonTs$ python docts.py ********************************************************************** File "docts.py", line 13, in __main__.MyMath.add Failed example: mt.add(3,-2) Expected: 0 Got: 1 ********************************************************************** 1 items had failures: 1 of 4 in __main__.MyMath.add ***Test Failed*** 1 failures.