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

Question

我在 Python 方面有一些经验，但直到最近才广泛使用 docstrings。我正在通过 FMS 中的 Financial Market Simulator (FMS) source code, and when I open it in PyCharm I see the following syntax highlighting (screenshot of a code snippet of one of the modules):

为什么“>>>”后面的语句高亮显示，就好像它们是可执行的一样？从我读到的 docstrings，无论是在官方文档还是在 SO 上（例如 here），我认为这些语句不应该执行，但是语法突出显示让我感到困惑，让我思考“>>>”是 docstring 中想要执行的代码的标记。或者这只是一个 PyCharm 'bug'？ None 的文档提到了与此相关的任何内容，我担心是否遗漏了什么。

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

Answer 1

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

Answer 2

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

设置选项称为 "Analyze Python code in docstrings"，可在 Python Integrated Tools:

下使用

If this check box is selected, PyCharm highlights the code example and performs syntax checks and code inspections. If this check box is not selected, the code fragments inside docstrings are not analyzed.

如果您愿意，可以禁用它。

联机文档详细说明了如何 run tests and view their results。

Answer 3

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

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

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

示例：
假设我有一个名为 doctest_simple_addition 的脚本，我在其中为 add() 函数编写了一些文档测试，其中一些测试用例提供了正确的输出，而另一些则引发了异常。然后我可以通过运行那些 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，通过解释器的 -m 选项使用 doctest 作为主程序。通常，测试运行ning 时不会产生任何输出。您可以添加 -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 header 行时（Traceback (most recent call last): 或 Traceback (innermost last):，取决于版本Python 你是运行ning)，它会向前跳转以查找异常类型和消息，完全忽略中间行。
这样做是因为回溯中的路径取决于模块在给定系统上的文件系统上的安装位置，并且不可能编写可移植测试，因为路径会因系统而异。

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

Python docstrings and inline code; meaning of the ">>>" syntax

python

docstring