Python文档和内联代码; “>>>”语法的含义

我在Python方面有一些经验，但直到最近才遇到了docstrings的大量使用。我经历的Financial Market Simulator (FMS)源代码，当我在PyCharm打开它，我看到下面的语法高亮（的one of the modules在FMS的代码片断的截图）：Python文档和内联代码; “>>>”语法的含义

script-screenshot01

为什么语句后“>>>”突出显示，如果他们是可执行的？从我读过的docstrings，官方文档和SO（例如here）我都认为这些语句不应该执行，但语法高亮使我困惑，导致我认为“>>>”是一个想要执行的docstring内的代码标记。或者这只是一个PyCharm'bug'？没有任何文件提到与此有关的任何事情，我担心如果我错过了什么。

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

来源

2015-07-05 avg

用>>>在docstrings中编写的语句是doctests。

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

就你而言，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

要运行的文档测试，通过-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.

注：当文档测试看到一个traceback标题行（无论是Traceback (most recent call last):或Traceback (innermost last):，这取决于Python中，你正在运行的版本），它跳过提前发现异常类型和消息，忽略了中间的线完全。
这样做是因为在回溯路径取决于其中模块安装在一个给定的系统上的文件系统中的位置，这将是不可能写便携式测试，路径会从系统更改为系统。

来源

2015-07-05 07:25:40

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

来源

2015-07-05 07:05:51 NZP

谢谢！因此，'doctest'在'>>>'后面内部运行所有内容，并将输出与在下面紧接着的行上依次给出的期望输出进行比较？另外，在我提供的示例中，是否会实际执行“Traceback ...”和“MissingParameter..'函数调用，或者只是某些文本在测试失败时打印为屏幕作为消息？ – avg

@avg不客气！是的，确切地说，'>>>'行后面的所有内容都是预期的输出。 “Traceback”和“MissingParameter”只是输出的一部分，在这种情况下是回溯。在开始时，您有回溯头，最后一行是异常类型。在例外情况下，这两行之间的所有内容都将被忽略。 – NZP

我打算接受你的答案，但是@rahul写了一个更完整的文章，所以我会接受他的答案。感谢您花时间回答。 – avg

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

的设置选项被称为“分析文档字符串Python代码”和Python Integrated Tools下提供：

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

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

在线文档详细信息如何run tests和view their results。

来源

2015-07-05 07:25:39

谢谢，我最近才开始使用PyCharm，这是非常有用的。 – avg

Python文档和内联代码; “>>>”语法的含义

回答

相关问题