Python自編寫help文檔以及文檔測試

一 以注釋方式為類添加幫助文檔

我們知道,Python中可以使用help(模塊名)或者help(類名)的形式來查看一個模塊或者類的幫助文檔,我們也可以為自定義的類添加幫助文檔,並用help進行查看.Python中用三對雙引號可以進行多行注釋,當我們把這種注釋內容放到一個類或者函數定義的下面時,它會自動被當作該類或者函數的幫助文檔.請看下面的類:

docts.py:

[python] view plain copy

#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:

[plain] view plain copy

>>> help(docts)

[plain] view plain copy

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:

[plain] view plain copy

>>> from docts import MyMath

>>> help(MyMath)

[plain] view plain copy

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進行文檔測試

我們在上面的模塊中加入下面這段代碼:

[python] view plain copy

if __name__==__main__:

import doctest

doctest.testmod()

請注意我們寫的注釋中的下面這段內容:

[plain] view plain copy

Example:

>>> mt=MyMath()

>>> mt.add(1,2)

3

>>> mt.add(2.4,1.5)

3.9

當我們在終端中運行該模塊時,導入doctest.testmod()會自動在終端測試我們所寫的這些例子:

[plain] view plain copy

hyman@hyman-VirtualBox:~/projects/pythonTs$ python docts.py

hyman@hyman-VirtualBox:~/projects/pythonTs$

運行之後你會發現,什麼結果都沒列印,那是因為我們寫的例子是正確的,我們可以修改下例子中代碼,把運算結果改錯

[plain] view plain copy

>>> mt.add(3,-2)

0

再運行就報錯了(注意寫運行示例時,>>>和python語句之間要有一個空格,否則會出現語法錯誤.)

[plain] view plain copy

[plain] view plain copy

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.