Python'标准发行版包含'Doctest'模块.该模块的功能使得搜索看起来像交互式Python会话的文本片段成为可能，并执行这些会话以查看它们是否完全如图所示.
Doctest在以下内容中非常有用以下场景 :
通过验证所有交互式示例是否仍然有效来检查模块的文档字符串是否是最新的记录.
通过验证测试文件或测试对象中的交互式示例是否按预期工作来执行回归测试.
编写包的教程文档，用输入输出示例进行说明
在Python中，'docstring'是一个字符串文字，它作为类，函数或模块中的第一个表达式出现.执行套件时会忽略它，但编译器会识别它并将其放入封闭类，函数或模块的 __ doc __ 属性中.由于它是通过内省提供的，因此它是文档对象的规范位置.
通常的做法是将Python代码的不同部分的示例用法放在docstring中. doctest模块允许验证这些文档字符串是否与代码中的间歇性修订保持同步.
在下面的代码中，定义了一个阶乘函数，其中插入了示例用法.为了验证示例用法是否正确，请在doctest模块中调用testmod()函数.
"""
This is the "example" module.
The example module supplies one function, factorial(). For example,
>>> factorial(5)
120
"""
def factorial(x):
"""Return the factorial of n, an exact integer >= 0.
>>> factorial(-1)
Traceback (most recent call last):
...
ValueError: x must be >= 0
"""
if not x >= 0:
raise ValueError("x must be >= 0")
f = 1
for i in range(1,x+1):
f = f*i
return f
if __name__ == "__main__":
import doctest
doctest.testmod()输入并保存上述脚本作为FactDocTest.py并尝试从命令行执行此脚本.
Python FactDocTest.py
除非示例失败，否则不会显示任何输出.现在，将命令行更改为以下 :
Python FactDocTest.py –v
控制台现在将显示以下输出 :
C:\Python27>python FactDocTest.py -v Trying: factorial(5) Expecting: 120 ok Trying: factorial(-1) Expecting: Traceback (most recent call last): ... ValueError: x must be >= 0 ok 2 items passed all tests: 1 tests in __main__ 1 tests in __main__.factorial 2 tests in 2 items. 2 passed and 0 failed. Test passed.
另一方面，如果factorial()函数的代码没有在docstring中给出预期结果，则会显示失败结果.例如，在上面的脚本中更改f = 2代替f = 1并再次运行doctest.结果如下:
Trying: factorial(5) Expecting: 120 ********************************************************************** File "docfacttest.py", line 6, in __main__ Failed example: factorial(5) Expected: 120 Got: 240 Trying: factorial(-1) Expecting: Traceback (most recent call last): ... ValueError: x must be >= 0 ok 1 items passed all tests: 1 tests in __main__.factorial ********************************************************************** 1 items had failures: 1 of 1 in __main__ 2 tests in 2 items. 1 passed and 1 failed. ***Test Failed*** 1 failures.
doctest的另一个简单应用是测试文本文件中的交互式示例.这可以通过testfile()函数完成.
以下文本存储在名为'example.txt'的文本文件中.
Using ''factorial'' ------------------- This is an example text file in reStructuredText format. First import ''factorial'' from the ''example'' module: >>> from example import factorial Now use it: >>> factorial(5) 120
文件内容被视为docstring.为了验证文本文件中的示例，请使用doctest模块的testfile()函数.
def factorial(x):
if not x >= 0:
raise ValueError("x must be >= 0")
f = 1
for i in range(1,x+1):
f = f*i
return f
if __name__ == "__main__":
import doctest
doctest.testfile("example.txt")与testmod()一样，除非示例，testfile()不会显示任何内容失败.如果示例失败，那么失败的示例和失败的原因将打印到控制台，使用与testmod()相同的格式.
在大多数情况下，交互式控制台会话的复制和粘贴工作正常，但doctest不会尝试对任何特定的Python shell进行精确模拟.
任何预期的输出必须紧跟在最后的'>>>之后'或'...'包含代码的行，预期的输出(如果有的话)延伸到下一个'>>> '或所有空白行.
预期输出不能包含全空行，因为这样的行被用来表示预期输出的结束.如果预期输出确实包含空行，请将< BLANKLINE>在你的doctest示例中，每个地方都需要一个空行.
