Python doctest：如何跳过整个代码块？

Question

我有一个Python模块，其中类方法里有文档字符串，而模块的文档字符串里有一个真实的例子。两者的区别在于，方法里的文档字符串是经过精心设计的，可以完全重复的测试，而真实的例子只是从Linux命令行复制粘贴过来的历史记录——刚好调用了Python解释器。

比如：

"""
Real-world example:

# python2.5
Python 2.5 (release25-maint, Jul 20 2008, 20:47:25)
[GCC 4.1.2 20061115 (prerelease) (Debian 4.1.1-21)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from packagename import module
>>> module.show_real_world_usage()
'Hello world!'
"""

class SomeClass(object):
    def someMethod(self):
        """
        >>> 1 == 1
        True
        """

我想在SomeClass.someMethod中运行doctest，但不想在模块的文档字符串中运行。

doctest的+SKIP指令只能逐行使用，这意味着我得在我的真实例子中添加十几行代码。太难看了！

有没有办法让doctest跳过整个代码块？有点像HTML中的<!-- ... -->那样？

Answer 1

如果这并不是一个真正的文档测试，你可以直接把值赋给一个变量。例如，

example_usage = """
Real-world example:

# python2.5
...
"""

这样做会让那个“测试”不被执行。

使用 __example_usage__（或者其他用双下划线包围的名字）可能会更好，这样可以明确表示这是一个“魔法”变量，而不是在脚本中要使用的普通变量。

Answer 2

把这个例子放到一个函数里，然后就可以跳过调用这个函数了：

"""
>>> def example():
...    from packagename import module
...    module.show_real_world_usage()
...
>>> example() # doctest: +SKIP
'Hello world!'
"""

Answer 3

我的解决办法是把我希望 doctest 跳过的那三个字符的 >>> 和 ... 去掉，变成两个字符。

所以

"""
>>> from packagename import module
>>> module.show_real_world_usage()
'Hello world!'
"""

变成了

"""
>> from packagename import module
>> module.show_real_world_usage()
'Hello world!'
"""

Epydoc 显示这个的效果没有 doctest 好，但我能接受。不过，如果 doctest 能有个“跳过，直到另行通知”的指令就更好了。