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文檔和內聯代碼; 「>>>」語法的含義

回答

相關問題