【Python语法】Python中为自定义类编写help文档以及进行文档测试

一 以注释方式为类添加帮助文档

        我们知道,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.