Python doctest

>>> def median(pool):
    '''Statistical median to demonstrate doctest.
    >>> median([2, 9, 9, 7, 9, 2, 4, 5, 8])
    7
    ''' #代码的文档，功能说明。如果运行以上参数，期望结果是7
    copy = sorted(pool)
    size = len(copy)
    if size % 2 == 1:
        return copy[(size-1)/2]
    else :
        return (copy[size/2-1] + copy[size/2])/2

    
>>> if __name__ == '__main__':
    import doctest
    doctest.testmod()

运行结果：
TestResults(failed=0, attempted=1)
如果我把上面的7改为8，运行结果如下：
**********************************************************************
File "__main__", line 3, in __main__.median
Failed example:
    median([2, 9, 9, 7, 9, 2, 4, 5, 8])
Expected:
    8
Got:
    7
**********************************************************************
1 items had failures:
   1 of   1 in __main__.median
***Test Failed*** 1 failures.
*** DocTestRunner.merge: '__main__.median' in both testers; summing outcomes.
*** DocTestRunner.merge: '__main__' in both testers; summing outcomes.
TestResults(failed=1, attempted=1)

doctest模块在程序说明中寻找看起来像python交互程序的字符串，然后把这些字符串作为python代码运行，验证他们运行后是否得到想要的结果。这里有3种需求会用到doctest。
1. 验证模块（例如，方法）中的文档或说明书是否得及时更新。
2. 执行回归测试（regression test）。
3. 写培训文档，或说明文档，有点程序可读性测试的味道。
总之，doctest按文档中的指令执行，其实就是按照预先给定的参数执行该模块，然后对比实际输出结果是否与说明中的结果一致。其结果就反映了以上3个方面，1，有可能程序正确，文档说明没有及时更新；2，修改后的程序有bug；3，由于程序的执行结果与文档说明中的不一致，很可能导致读者困惑，程序可读性受影响。
下面举一个小例子，麻雀虽小五脏俱全。
def factorial (n):
    '''Return the factorial of n, an exact integer >= 0.
    If the result is small enough to fit in an int, return an int.
    Else return a long.
    >>> [factorial(n) for n in range(6)] #看看python的语法就是这么简洁
    [1, 1, 2, 6, 24, 120]
    >>> [factorial(long(n)) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(30)
    265252859812191058636308480000000L
    >>> factorial(30L)
    265252859812191058636308480000000L
    >>> factorial(-1)
    Traceback (most recent call last):
    ...
    ValueError: n must be >= 0
    
    Factorials of floats are OK, but the float must be an exact integer:
    >>> factorial(30.1)
    Traceback (most recent call last):
    ...
    ValueError: n must be exact integer
    >>> factorial(1e100)
    Traceback (most recent call last):
    ...
    OverflowError: n too large
    ''' #三引号引起来的字都是说明
    
    import math
    if not n>=0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n: # cache a value like le300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor
        factor += 1
    return result
    
if __name__ == "__main__":
    import doctest
    doctest.testmod()
以上代码需要保存到C:\Python26\Lib\site-packages\win32\test\example.py。然后再命令行里直接运行它：
>python example.py
>
没有输出，那就对了，意味着所有的例子多是正确的。如果命令行后加参数-v，doctest将会把详细的记录打印出来，做一个总结。