Python 文档字符串和内联代码； ">>>"语法的含义

Question

我有一些 Python 经验，但直到最近才广泛使用文档字符串。我正在浏览 Financial Market Simulator (FMS)源代码，当我在 PyCharm 中打开它时，我看到以下语法突出显示(FMS 中 one of the modules 的代码片段的屏幕截图):

为什么>>>后面的语句高亮显示，就好像它们是可执行的一样？根据我在官方文档和 SO 上阅读的文档字符串(例如 here )，我认为这些语句不应该执行，但语法突出显示让我感到困惑，让我认为 >>> 是文档字符串中要执行的代码的标记。或者这只是 PyCharm 的“错误”？所有文档均未提及与此相关的任何内容，我担心是否遗漏了什么。

PS:郑重声明，查看 SublimeText 中的代码不会重现相同的行为。

Answer 1

文档字符串中用>>>写的语句是doctests .

它允许您通过运行文档中嵌入的示例并验证它们是否产生预期结果来测试您的代码。它解析帮助文本以查找示例，运行它们，然后将输出文本与预期值进行比较。

在您的例子中，PyCharm 已经完成了突出显示文档字符串中的 python 代码的额外任务。它不会影响您的正常功能执行，因此您无需担心。

示例:
假设我有一个名为 doctest_simple_addition 的脚本，我在其中为 add() 函数编写了一些文档测试，其中一些测试用例提供了正确的输出，一些则引发了异常。然后我可以通过运行这些文档测试来验证我的函数是否产生了预期的结果。

doctest_simple_addition.py

def add(a,b):
    """
    >>> add(1, 2)
    3

    >>> add(5, 3)
    8

    >>> add('a', 1)
    Traceback (most recent call last):
        ...
    TypeError: cannot concatenate 'str' and 'int' objects
    """

    return a + b

要运行 doctest，请通过解释器的 -m 选项使用 doctest 作为主程序。通常，测试运行时不会产生任何输出。您可以添加 -v 选项，然后 doctest 将打印一份详细的日志，说明它正在尝试的内容，并在末尾提供摘要。

Doctest 查找以解释器提示符 >>> 开头的行，以找到测试用例的开头。测试用例以空行或下一个解释器提示结束。

$ python -m doctest -v doctest_simple_addition.py 

Trying:
    add(1, 2)
Expecting:
    3
ok
Trying:
    add(5, 3)
Expecting:
    8
ok
Trying:
    add('a', 1)
Expecting:
    Traceback (most recent call last):
        ...
    TypeError: cannot concatenate 'str' and 'int' objects
ok
1 items had no tests:
    doctest_simple_addition
1 items passed all tests:
   3 tests in doctest_simple_addition.add
3 tests in 2 items.
3 passed and 0 failed.
Test passed.

注意:当 doctest 看到 traceback 标题行(Traceback (most recent call last): 或 Traceback (innermost last):，具体取决于您运行的 Python 版本)，它会向前跳转以查找异常类型和消息，完全忽略中间行。
这样做是因为回溯中的路径取决于模块在给定系统上的文件系统上的安装位置，并且不可能编写可移植测试，因为路径会因系统而异。