2. 文档测试
    4. 阅读: 80195
    5. 如果你经常阅读Python的官方文档，可以看到很多文档都有示例代码。比如re模块就带了很多示例代码：
    7. >>> import re
    8. >>> m = re.search('(?<=abc)def', 'abcdef')
    9. >>> m.group(0)
    10. 'def'
    11. 可以把这些示例代码在Python的交互式环境下输入并执行，结果与文档中的示例代码显示的一致。
    13. 这些代码与其他说明可以写在注释中，然后，由一些工具来自动生成文档。既然这些代码本身就可以粘贴出来直接运行，那么，可不可以自动执行写在注释中的这些代码呢？
    15. 答案是肯定的。
    17. 当我们编写注释时，如果写上这样的注释：
    19. def abs(n):
    20.    '''
    21.    Function to get absolute value of number.
    23.    Example:
    25.    >>> abs(1)
    26.    1
    27.    >>> abs(-1)
    28.    1
    29.    >>> abs(0)
    30.    0
    31.    '''
    32.    return n if n >= 0 else (-n)
    33. 无疑更明确地告诉函数的调用者该函数的期望输入和输出。
    35. 并且，Python内置的"文档测试"（doctest）模块可以直接提取注释中的代码并执行测试。
    37. doctest严格按照Python交互式命令行的输入和输出来判断测试结果是否正确。只有测试异常的时候，可以用...表示中间一大段烦人的输出。
    39. 让我们用doctest来测试上次编写的Dict类：
    41. # mydict2.py
    42. class Dict(dict):
    43.    '''
    44.    Simple dict but also support access as x.y style.
    46.    >>> d1 = Dict()
    47.    >>> d1['x'] = 100
    48.    >>> d1.x
    49.    100
    50.    >>> d1.y = 200
    51.    >>> d1['y']
    52.    200
    53.    >>> d2 = Dict(a=1, b=2, c='3')
    54.    >>> d2.c
    55.    '3'
    56.    >>> d2['empty']
    57.    Traceback (most recent call last):
    58.        ...
    59.    KeyError: 'empty'
    60.    >>> d2.empty
    61.    Traceback (most recent call last):
    62.        ...
    63.    AttributeError: 'Dict' object has no attribute 'empty'
    64.    '''
    65.    def __init__(self, **kw):
    66.        super(Dict, self).__init__(**kw)
    68.    def __getattr__(self, key):
    69.        try:
    70.            return self[key]
    71.        except KeyError:
    72.            raise AttributeError(r"'Dict' object has no attribute '%s'" % key)
    74.    def __setattr__(self, key, value):
    75.        self[key] = value
    77. if __name__=='__main__':
    78.    import doctest
    79.    doctest.testmod()
    80. 运行python mydict2.py：
    82. $ python mydict2.py
    83. 什么输出也没有。这说明我们编写的doctest运行都是正确的。如果程序有问题，比如把__getattr__()方法注释掉，再运行就会报错：
    85. $ python mydict2.py
    86. **********************************************************************
    87. File "/Users/michael/Github/learn-python3/samples/debug/mydict2.py", line 10, in __main__.Dict
    88. Failed example:
    89.    d1.x
    90. Exception raised:
    91.    Traceback (most recent call last):
    92.      ...
    93.    AttributeError: 'Dict' object has no attribute 'x'
    94. **********************************************************************
    95. File "/Users/michael/Github/learn-python3/samples/debug/mydict2.py", line 16, in __main__.Dict
    96. Failed example:
    97.    d2.c
    98. Exception raised:
    99.    Traceback (most recent call last):
    100.      ...
    101.    AttributeError: 'Dict' object has no attribute 'c'
    102. **********************************************************************
    103. 1 items had failures:
    104.   2 of   9 in __main__.Dict
    105. ***Test Failed*** 2 failures.
    106. 注意到最后3行代码。当模块正常导入时，doctest不会被执行。只有在命令行直接运行时，才执行doctest。所以，不必担心doctest会在非测试环境下执行。
    108. 练习
    110. 对函数fact(n)编写doctest并执行：
    112. # -*- coding: utf-8 -*-
    114. def fact(n):
    115.    '''
    116.    Calculate 1*2*...*n
    118.    >>> fact(1)
    119.    1
    120.    >>> fact(10)
    121.    ?
    122.    >>> fact(-1)
    123.    ?
    124.    '''
    125.    if n < 1:
    126.        raise ValueError()
    127.    if n == 1:
    128.        return 1
    129.    return n * fact(n - 1)
    131. if __name__ == '__main__':
    132.    import doctest
    133.    doctest.testmod()
    134. Run
    135. 小结
    137. doctest非常有用，不但可以用来测试，还可以直接作为示例代码。通过某些文档生成工具，就可以自动把包含doctest的注释提取出来。用户看文档的时候，同时也看到了doctest。
    139. 参考源码
    141. mydict2.py