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

Question

我有一些Python的经验,但最近才发现它的广泛使用docstrings.我正在浏览金融市场模拟器(FMS)源代码,当我在PyCharm中打开它时,我看到以下语法突出显示(FMS 中其中一个模块的代码片段的屏幕截图):

为什么">>>"之后的语句突出显示为可执行文件？从我所读到的docstrings,在官方文档和SO上(例如在这里)我认为这些语句不应该执行,但语法突出显示令我感到困惑,让我认为">>>"是一个docstring要执行的代码内的代码标记.或者这只是一个PyCharm'bug'？没有任何文件提及与此相关的任何内容,我担心如果我错过了什么.

PS:对于记录,查看SublimeText中的代码不会重现相同的行为.

Answer 1

>>>在docstrings中写的语句是doctests.

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

在你的情况下,PyCharm完成了在文档字符串中突出显示python代码的额外任务.它不会影响您的正常功能执行,因此您不必担心它.

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

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

要运行doctests,请doctest通过-m解释器选项将其用作主程序.通常,测试运行时不会产生任何输出.您可以添加该-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版本),它会向前跳过以查找异常类型和消息,完全忽略插入行.
这样做是因为回溯中的路径取决于给定系统上文件系统上安装模块的位置,并且由于路径将在系统之间发生变化,因此无法编写可移植测试.