Python文档字符串和内联代码; “＆gt;＆gt;＆gt;”的含义语法

Question

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

为什么“＆gt;＆gt;＆gt;”之后的陈述“突出显示好像它们是可执行的？从我对docstrings的看法，无论是官方文档还是SO（例如here），我认为这些陈述不应该执行，但语法突出显示令我困惑，让我思考那个“＆gt;＆gt;＆gt;”是docstring中想要执行的代码的标记。或者这只是一个PyCharm'bug'？没有任何文件提及与此相关的任何内容，我担心如果我遗失了什么。

PS：对于记录，查看SublimeText中的代码不会重现相同的行为。

Answer 1

在文档字符串中使用>>>编写的语句为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版本），它会跳过提前查找异常类型和消息，完全忽略干预行 这样做是因为回溯中的路径取决于给定系统上文件系统上安装模块的位置，并且由于路径将在系统之间发生变化，因此无法编写可移植测试。

Answer 2

你的直觉是正确的，他们将被执行。但不要担心，它们是doctest字符串。他们不会干扰模块的正常执行，所以一切都很好。 PyCharm只是通过识别它们来提供帮助。

Answer 3

您看到的行为是Pycharm中可用的Python测试支持的一部分。

设置选项名为“在文档字符串中分析Python代码”，可在Sinch下找到：

  

如果选中此复选框，PyCharm会突出显示代码示例和   执行语法检查和代码检查。如果未选中此复选框   选中后，文档字符串中的代码片段不会被分析。

如果您愿意，可以将其停用。

在线文档详细说明了如何Python Integrated Tools和run tests。