doctest --- 測(cè)試交互性的Python示例?

哪些文件串被檢查了？?

模塊的文檔串以及所有函數(shù)、類(lèi)和方法的文檔串都將被搜索。 導(dǎo)入模塊的對(duì)象不被搜索。

此外，如果 M.__test__ 存在并且 "為真值"，則它必須是一個(gè)字典，其中每個(gè)條目都將一個(gè)（字符串）名稱映射到一個(gè)函數(shù)對(duì)象、類(lèi)對(duì)象或字符串。 從 M.__test__ 找到的函數(shù)和類(lèi)對(duì)象的文檔字符串會(huì)被搜索，而字符串會(huì)被當(dāng)作文檔字符串來(lái)處理。 在輸出時(shí)，每個(gè)鍵 K 在 M.__test__ 中都顯示為其名稱

<name of M>.__test__.K

任何發(fā)現(xiàn)的類(lèi)都會(huì)以類(lèi)似的方式進(jìn)行遞歸搜索，以測(cè)試其包含的方法和嵌套類(lèi)中的文檔串。

文檔串的例子是如何被識(shí)別的？?

在大多數(shù)情況下，對(duì)交互式控制臺(tái)會(huì)話的復(fù)制和粘貼功能工作得很好，但是 doctest 并不試圖對(duì)任何特定的 Python shell 進(jìn)行精確的模擬。

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print("yes")
... else:
...     print("no")
...     print("NO")
...     print("NO!!!")
...
no
NO
NO!!!
>>>

任何預(yù)期的輸出必須緊隨包含代碼的最后 '>>> ' 或 '... ' 行，預(yù)期的輸出（如果有的話）延伸到下一 '>>> ' 行或全空白行。

fine輸出：

• 預(yù)期輸出不能包含一個(gè)全白的行，因?yàn)檫@樣的行被認(rèn)為是預(yù)期輸出的結(jié)束信號(hào)。 如果預(yù)期的輸出包含一個(gè)空行，在你的測(cè)試?yán)又?，在每一個(gè)預(yù)期有空行的地方加上``<BLANKLINE>``。

• 所有硬制表符都被擴(kuò)展為空格，使用 8 列的制表符。由測(cè)試代碼生成的輸出中的制表符不會(huì)被修改。 因?yàn)闃颖据敵鲋械娜魏斡仓票矸紩?huì)被擴(kuò)展，這意味著如果代碼輸出包括硬制表符，文檔測(cè)試通過(guò)的唯一方法是 NORMALIZE_WHITESPACE 選項(xiàng)或者 指令 是有效的。 另外，測(cè)試可以被重寫(xiě)，以捕獲輸出并將其與預(yù)期值進(jìn)行比較，作為測(cè)試的一部分。這種對(duì)源碼中標(biāo)簽的處理是通過(guò)試錯(cuò)得出的，并被證明是最不容易出錯(cuò)的處理方式。通過(guò)編寫(xiě)一個(gè)自定義的 DocTestParser 類(lèi)，可以使用一個(gè)不同的算法來(lái)處理標(biāo)簽。

• 向stdout的輸出被捕獲，但不向stderr輸出（異常回溯通過(guò)不同的方式被捕獲）。

• 如果你在交互式會(huì)話中通過(guò)反斜線續(xù)行，或出于任何其他原因使用反斜線，你應(yīng)該使用原始文件串，它將完全保留你輸入的反斜線:

  >>>

  >>> def f(x):
  ...     r'''Backslashes in a raw docstring: m\n'''
  >>> print(f.__doc__)
  Backslashes in a raw docstring: m\n
  

  否則，反斜杠將被解釋為字符串的一部分。例如，上面的``n``會(huì)被解釋為一個(gè)換行符。 另外，你可以在doctest版本中把每個(gè)反斜杠加倍（而不使用原始字符串）:

  >>>

  >>> def f(x):
  ...     '''Backslashes in a raw docstring: m\\n'''
  >>> print(f.__doc__)
  Backslashes in a raw docstring: m\n
  

• 起始列并不重要:

  >>>

  >>> assert "Easy!"
        >>> import math
            >>> math.floor(1.9)
            1
  

  并從預(yù)期的輸出中剝離出與開(kāi)始該例子的初始 '>>> ' 行中出現(xiàn)的同樣多的前導(dǎo)空白字符。

什么是執(zhí)行上下文？?

默認(rèn)情況下，每次 doctest 找到要測(cè)試的文檔串時(shí)，它都會(huì)使用 M 的*淺層副本*，這樣運(yùn)行測(cè)試就不會(huì)改變模塊的真正全局變量，而且 M 的一個(gè)測(cè)試也不會(huì)留下臨時(shí)變量，從而意外地讓另一個(gè)測(cè)試通過(guò)。這意味著例子可以自由地使用 M 中的任何頂級(jí)定義的名字，以及正在運(yùn)行的文檔串中早期定義的名字。用例不能看到其他文檔串中定義的名字。

你可以通過(guò)將``globs=your_dict``傳遞給 testmod() 或 testfile() 來(lái)強(qiáng)制使用你自己的dict作為執(zhí)行環(huán)境。

異常如何處理？?

沒(méi)問(wèn)題，只要回溯是這個(gè)例子產(chǎn)生的唯一輸出：只要粘貼回溯即可。1 由于回溯所包含的細(xì)節(jié)可能會(huì)迅速變化（例如，確切的文件路徑和行號(hào)），這是doctest努力使其接受的內(nèi)容具有靈活性的一種情況。

簡(jiǎn)單實(shí)例:

>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list

如果 ValueError 被觸發(fā)，該測(cè)試就會(huì)成功，list.remove(x): x not in list 的細(xì)節(jié)如圖所示。

異常的預(yù)期輸出必須以回溯頭開(kāi)始，可以是以下兩行中的任何一行，縮進(jìn)程度與例子中的第一行相同:

Traceback (most recent call last):
Traceback (innermost last):

回溯頭的后面是一個(gè)可選的回溯堆棧，其內(nèi)容被doctest忽略。 回溯堆棧通常是省略的，或者從交互式會(huì)話中逐字復(fù)制的。

回溯堆棧的后面是最有用的部分：包含異常類(lèi)型和細(xì)節(jié)的一行（幾行）。 這通常是回溯的最后一行，但如果異常有多行細(xì)節(jié)，則可以延伸到多行:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: multi
    line
detail

最后三行（以 ValueError 開(kāi)頭）將與異常的類(lèi)型和細(xì)節(jié)進(jìn)行比較，其余的被忽略。

最佳實(shí)踐是省略回溯棧，除非它為這個(gè)例子增加了重要的文檔價(jià)值。 因此，最后一個(gè)例子可能更好，因?yàn)?

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
    ...
ValueError: multi
    line
detail

請(qǐng)注意，回溯的處理方式非常特別。 特別是，在重寫(xiě)的例子中，... 的使用與 doctest 的 ELLIPSIS 選項(xiàng)無(wú)關(guān)。 該例子中的省略號(hào)可以不寫(xiě)，也可以是三個(gè)（或三百個(gè)）逗號(hào)或數(shù)字，或者是一個(gè)縮進(jìn)的 Monty Python 短劇的劇本。

有些細(xì)節(jié)你應(yīng)該讀一遍，但不需要記?。?/p>

• Doctest 不能猜測(cè)你的預(yù)期輸出是來(lái)自異?；厮葸€是來(lái)自普通打印。 因此，例如，一個(gè)期望 ValueError: 42 is prime 的用例將通過(guò)測(cè)試，無(wú)論 ValueError 是真的被觸發(fā)，或者該用例只是打印了該回溯文本。 在實(shí)踐中，普通輸出很少以回溯標(biāo)題行開(kāi)始，所以這不會(huì)產(chǎn)生真正的問(wèn)題。

• 回溯堆棧的每一行（如果有的話）必須比例子的第一行縮進(jìn)， 或者 以一個(gè)非字母數(shù)字的字符開(kāi)始?；厮蓊^之后的第一行縮進(jìn)程度相同，并且以字母數(shù)字開(kāi)始，被認(rèn)為是異常細(xì)節(jié)的開(kāi)始。當(dāng)然，這對(duì)真正的回溯來(lái)說(shuō)是正確的事情。

• 當(dāng) IGNORE_EXCEPTION_DETAIL doctest 選項(xiàng)被指定時(shí)，最左邊的冒號(hào)后面的所有內(nèi)容以及異常名稱中的任何模塊信息都被忽略。

• 交互式 shell 省略了一些 SyntaxError 的回溯頭行。但 doctest 使用回溯頭行來(lái)區(qū)分異常和非異常。所以在罕見(jiàn)的情況下，如果你需要測(cè)試一個(gè)省略了回溯頭的 SyntaxError，你將需要手動(dòng)添加回溯頭行到你的測(cè)試用例中。

• For some exceptions, Python displays the position of the error using ^ markers and tildes:

  >>>

  >>> 1 + None
    File "<stdin>", line 1
      1 + None
      ~~^~~~~~
  TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
  

  由于顯示錯(cuò)誤位置的行在異常類(lèi)型和細(xì)節(jié)之前，它們不被doctest檢查。 例如，下面的測(cè)試會(huì)通過(guò)，盡管它把``^``標(biāo)記放在了錯(cuò)誤的位置:

  >>>

  >>> 1 + None
    File "<stdin>", line 1
      1 + None
      ^~~~~~~~
  TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
  

選項(xiàng)標(biāo)記?

一系列選項(xiàng)旗標(biāo)控制著 doctest 的各方面行為。 旗標(biāo)的符號(hào)名稱以模塊常量的形式提供，可以一起 bitwise ORed 并傳遞給各種函數(shù)。 這些名稱也可以在 doctest directives 中使用，并且可以通過(guò) -o 選項(xiàng)傳遞給 doctest 命令行接口。

第一組選項(xiàng)定義了測(cè)試語(yǔ)義，控制doctest如何決定實(shí)際輸出是否與用例的預(yù)期輸出相匹配方面的問(wèn)題。

doctest.DONT_ACCEPT_TRUE_FOR_1?

默認(rèn)情況下，如果一個(gè)預(yù)期的輸出塊只包含 1，那么實(shí)際的輸出塊只包含 1 或只包含 True 就被認(rèn)為是匹配的，同樣，0 與 False 也是如此。 當(dāng) DONT_ACCEPT_TRUE_FOR_1 被指定時(shí)，兩種替換都不允許。 默認(rèn)行為是為了適應(yīng) Python 將許多函數(shù)的返回類(lèi)型從整數(shù)改為布爾值；期望 "小整數(shù)" 輸出的測(cè)試在這些情況下仍然有效。 這個(gè)選項(xiàng)可能會(huì)消失，但不會(huì)在幾年內(nèi)消失。

doctest.DONT_ACCEPT_BLANKLINE?

默認(rèn)情況下，如果一個(gè)預(yù)期輸出塊包含一個(gè)只包含字符串 <BLANKLINE> 的行，那么該行將與實(shí)際輸出中的一個(gè)空行相匹配。 因?yàn)橐粋€(gè)真正的空行是對(duì)預(yù)期輸出的限定，這是傳達(dá)預(yù)期空行的唯一方法。 當(dāng) DONT_ACCEPT_BLANKLINE 被指定時(shí)，這種替換是不允許的。

doctest.NORMALIZE_WHITESPACE?

當(dāng)指定時(shí)，所有的空白序列（空白和換行）都被視為相等。預(yù)期輸出中的任何空白序列將與實(shí)際輸出中的任何空白序列匹配。默認(rèn)情況下，空白必須完全匹配。 NORMALIZE_WHITESPACE 在預(yù)期輸出非常長(zhǎng)的一行，而你想把它包在源代碼的多行中時(shí)特別有用。

doctest.ELLIPSIS?

當(dāng)指定時(shí)，預(yù)期輸出中的省略號(hào)（...）可以匹配實(shí)際輸出中的任何子串。這包括跨行的子串和空子串，所以最好保持簡(jiǎn)單的用法。復(fù)雜的用法會(huì)導(dǎo)致與``.*``在正則表達(dá)式中容易出現(xiàn)的 "oops, it matched too much!"相同的意外情況。

doctest.IGNORE_EXCEPTION_DETAIL?

When specified, doctests expecting exceptions pass so long as an exception of the expected type is raised, even if the details (message and fully-qualified exception name) don't match.

For example, an example expecting ValueError: 42 will pass if the actual exception raised is ValueError: 3*14, but will fail if, say, a TypeError is raised instead. It will also ignore any fully-qualified name included before the exception class, which can vary between implementations and versions of Python and the code/libraries in use. Hence, all three of these variations will work with the flag specified:

>>>

>>> raise Exception('message')
Traceback (most recent call last):
Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
builtins.Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
__main__.Exception: message

Note that ELLIPSIS can also be used to ignore the details of the exception message, but such a test may still fail based on whether the module name is present or matches exactly.

在 3.2 版更改: IGNORE_EXCEPTION_DETAIL 現(xiàn)在也忽略了與包含被測(cè)異常的模塊有關(guān)的任何信息。

doctest.SKIP?

當(dāng)指定時(shí)，完全不運(yùn)行這個(gè)用例。 這在doctest用例既是文檔又是測(cè)試案例的情況下很有用，一個(gè)例子應(yīng)該包括在文檔中，但不應(yīng)該被檢查。例如，這個(gè)例子的輸出可能是隨機(jī)的；或者這個(gè)例子可能依賴于測(cè)試驅(qū)動(dòng)程序所不能使用的資源。

SKIP標(biāo)志也可用于臨時(shí) "注釋" 用例。

doctest.COMPARISON_FLAGS?

一個(gè)比特或運(yùn)算將上述所有的比較標(biāo)志放在一起。

第二組選項(xiàng)控制測(cè)試失敗的報(bào)告方式：

doctest.REPORT_UDIFF?

當(dāng)指定時(shí)，涉及多行預(yù)期和實(shí)際輸出的故障將使用統(tǒng)一的差異來(lái)顯示。

doctest.REPORT_CDIFF?

當(dāng)指定時(shí)，涉及多行預(yù)期和實(shí)際輸出的故障將使用上下文差異來(lái)顯示。

doctest.REPORT_NDIFF?

當(dāng)指定時(shí)，差異由``difflib.Differ``來(lái)計(jì)算，使用與流行的:file:ndiff.py`工具相同的算法。這是唯一一種標(biāo)記行內(nèi)和行間差異的方法。 例如，如果一行預(yù)期輸出包含數(shù)字``1`，而實(shí)際輸出包含字母``l``，那么就會(huì)插入一行，用圓點(diǎn)標(biāo)記不匹配的列位置。

doctest.REPORT_ONLY_FIRST_FAILURE?

當(dāng)指定時(shí)，在每個(gè) doctest 中顯示第一個(gè)失敗的用例，但隱藏所有其余用例的輸出。 這將防止 doctest 報(bào)告由于先前的失敗而中斷的正確用例；但也可能隱藏獨(dú)立于第一個(gè)失敗的不正確用例。 當(dāng) REPORT_ONLY_FIRST_FAILURE 被指定時(shí)，其余的用例仍然被運(yùn)行，并且仍然計(jì)入報(bào)告的失敗總數(shù)；只是輸出被隱藏了。

doctest.FAIL_FAST?

當(dāng)指定時(shí)，在第一個(gè)失敗的用例后退出，不嘗試運(yùn)行其余的用例。因此，報(bào)告的失敗次數(shù)最多為1。這個(gè)標(biāo)志在調(diào)試時(shí)可能很有用，因?yàn)榈谝粋€(gè)失敗后的用例甚至不會(huì)產(chǎn)生調(diào)試輸出。

doctest命令行接受選項(xiàng)``-f``作為``-o FAIL_FAST``的簡(jiǎn)潔形式。

3.4 新版功能.

doctest.REPORTING_FLAGS?

一個(gè)比特或操作將上述所有的報(bào)告標(biāo)志組合在一起。

還有一種方法可以注冊(cè)新的選項(xiàng)標(biāo)志名稱，不過(guò)這并不有用，除非你打算通過(guò)子類(lèi)來(lái)擴(kuò)展 doctest 內(nèi)部。

doctest.register_optionflag(name)?

用給定的名稱創(chuàng)建一個(gè)新的選項(xiàng)標(biāo)志，并返回新標(biāo)志的整數(shù)值。 register_optionflag() 可以在繼承 OutputChecker 或 DocTestRunner 時(shí)使用，以創(chuàng)建子類(lèi)支持的新選項(xiàng)。 register_optionflag() 應(yīng)始終使用以下方式調(diào)用:

MY_FLAG = register_optionflag('MY_FLAG')

指令?

Doctest指令可以用來(lái)修改單個(gè)例子的 option flags 。 Doctest指令是在一個(gè)用例的源代碼后面的特殊Python注釋。

directive             ::=  "#" "doctest:" directive_options
directive_options     ::=  directive_option ("," directive_option)\*
directive_option      ::=  on_or_off directive_option_name
on_or_off             ::=  "+" \| "-"
directive_option_name ::=  "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...

+ 或 - 與指令選項(xiàng)名稱之間不允許有空格。 指令選項(xiàng)名稱可以是上面解釋的任何一個(gè)選項(xiàng)標(biāo)志名稱。

一個(gè)用例的 doctest 指令可以修改 doctest 對(duì)該用例的行為。 使用 + 來(lái)啟用指定的行為，或者使用 - 來(lái)禁用它。

For example, this test passes:

>>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

Without the directive it would fail, both because the actual output doesn't have two blanks before the single-digit list elements, and because the actual output is on a single line. This test also passes, and also requires a directive to do so:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]

Multiple directives can be used on a single physical line, separated by commas:

>>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

If multiple directive comments are used for a single example, then they are combined:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
...                         # doctest: +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

As the previous example shows, you can add ... lines to your example containing only directives. This can be useful when an example is too long for a directive to comfortably fit on the same line:

>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
[0, ..., 4, 10, ..., 19, 30, ..., 39]

請(qǐng)注意，由于所有的選項(xiàng)都是默認(rèn)禁用的，而指令只適用于它們出現(xiàn)的用例，所以啟用選項(xiàng) (通過(guò)指令中的 +) 通常是唯一有意義的選擇。 然而，選項(xiàng)標(biāo)志也可以被傳遞給運(yùn)行測(cè)試的函數(shù)，建立不同的默認(rèn)值。 在這種情況下，通過(guò)指令中的 - 來(lái)禁用一個(gè)選項(xiàng)可能是有用的。

警告?

doctest 是嚴(yán)格地要求在預(yù)期輸出中完全匹配。 如果哪怕只有一個(gè)字符不匹配，測(cè)試就會(huì)失敗。 這可能會(huì)讓你吃驚幾次，在你確切地了解到 Python 對(duì)輸出的保證和不保證之前。 例如，當(dāng)打印一個(gè)集合時(shí)，Python 不保證元素以任何特定的順序被打印出來(lái)，所以像:

>>> foo()
{"Hermione", "Harry"}

是不可靠的！一個(gè)變通方法是用:

>>> foo() == {"Hermione", "Harry"}
True

來(lái)取代。另一個(gè)是使用

>>> d = sorted(foo())
>>> d
['Harry', 'Hermione']

還有其他的問(wèn)題，但你會(huì)明白的。

Another bad idea is to print things that embed an object address, like

>>> id(1.0)  # certain to fail some of the time  
7948648
>>> class C: pass
>>> C()  # the default repr() for instances embeds an address   
<C object at 0x00AC18F0>

The ELLIPSIS directive gives a nice approach for the last example:

>>> C()  # doctest: +ELLIPSIS
<C object at 0x...>

浮點(diǎn)數(shù)在不同的平臺(tái)上也會(huì)有小的輸出變化，因?yàn)镻ython在浮點(diǎn)數(shù)的格式化上依賴于平臺(tái)的C庫(kù)，而C庫(kù)在這個(gè)問(wèn)題上的質(zhì)量差異很大。:

>>> 1./7  # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857

形式``I/2.**J``的數(shù)字在所有的平臺(tái)上都是安全的，我經(jīng)常設(shè)計(jì)一些測(cè)試的用例來(lái)產(chǎn)生該形式的數(shù):

>>> 3./4  # utterly safe
0.75

簡(jiǎn)單的分?jǐn)?shù)也更容易讓人理解，這也使得文件更加完善。

DocTest 對(duì)象?

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)?

應(yīng)該在單一命名空間中運(yùn)行的doctest用例的集合。構(gòu)造函數(shù)參數(shù)被用來(lái)初始化相同名稱的屬性。

DocTest 定義了以下屬性。 它們由構(gòu)造函數(shù)初始化，不應(yīng)該被直接修改。

examples?

一個(gè) Example 對(duì)象的列表，它編碼了應(yīng)該由該測(cè)試運(yùn)行的單個(gè)交互式 Python 用例。

globs?

例子應(yīng)該運(yùn)行的命名空間（又稱 globals ）。這是一個(gè)將名字映射到數(shù)值的字典。例子對(duì)名字空間的任何改變（比如綁定新的變量）將在測(cè)試運(yùn)行后反映在 globs 中。

name?

識(shí)別 DocTest 的字符串名稱。 通常情況下，這是從測(cè)試中提取的對(duì)象或文件的名稱。

filename?

這個(gè) DocTest 被提取的文件名；或者為``None``，如果文件名未知，或者 DocTest 沒(méi)有從文件中提取。

lineno?

filename 中的行號(hào)，這個(gè) DocTest 開(kāi)始的地方，或者行號(hào)不可用時(shí)為``None``。 這個(gè)行號(hào)相對(duì)于文件的開(kāi)頭來(lái)說(shuō)是零的。

docstring?

從測(cè)試中提取的字符串，或者如果字符串不可用，或者為 None ，如果測(cè)試沒(méi)有從字符串中提取。

Example 對(duì)象?

class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)?

單個(gè)交互式用例，由一個(gè) Python 語(yǔ)句及其預(yù)期輸出組成。 構(gòu)造函數(shù)參數(shù)被用來(lái)初始化相同名稱的屬性。

Example 定義了以下屬性。 它們由構(gòu)造函數(shù)初始化，不應(yīng)該被直接修改。

source?

一個(gè)包含該用例源碼的字符串。 源碼由一個(gè) Python 語(yǔ)句組成，并且總是以換行結(jié)束；構(gòu)造函數(shù)在必要時(shí)添加一個(gè)換行。

want?

運(yùn)行這個(gè)用例的源碼的預(yù)期輸出（可以是 stdout ，也可以是異常情況下的回溯）。 want 以一個(gè)換行符結(jié)束，除非沒(méi)有預(yù)期的輸出，在這種情況下它是一個(gè)空字符串。 構(gòu)造函數(shù)在必要時(shí)添加一個(gè)換行。

exc_msg?

用例產(chǎn)生的異常信息，如果這個(gè)例子被期望產(chǎn)生一個(gè)異常；或者為 None ，如果它不被期望產(chǎn)生一個(gè)異常。 這個(gè)異常信息與 traceback.format_exception_only() 的返回值進(jìn)行比較。 exc_msg 以換行結(jié)束，除非是 None 。

lineno?

包含本例的字符串中的行號(hào)，即本例的開(kāi)始。 這個(gè)行號(hào)相對(duì)于包含字符串的開(kāi)頭來(lái)說(shuō)是以零開(kāi)始的。

indent?

用例在包含字符串中的縮進(jìn)，即在用例的第一個(gè)提示前有多少個(gè)空格字符。

options?

一個(gè)從選項(xiàng)標(biāo)志到 True 或 False 的字典映射，用于覆蓋這個(gè)例子的默認(rèn)選項(xiàng)。 任何不包含在這個(gè)字典中的選項(xiàng)標(biāo)志都被保留為默認(rèn)值（由 DocTestRunner 的 optionflags 指定）。默認(rèn)情況下，沒(méi)有選項(xiàng)被設(shè)置。

DocTestFinder 對(duì)象?

class doctest.DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)?

一個(gè)處理類(lèi)，用于從一個(gè)給定的對(duì)象的 docstring 和其包含的對(duì)象的 docstring 中提取與之相關(guān)的 DocTest 。 DocTest 可以從模塊、類(lèi)、函數(shù)、方法、靜態(tài)方法、類(lèi)方法和屬性中提取。

可選的參數(shù) verbose 可以用來(lái)顯示查找器搜索到的對(duì)象。 它的默認(rèn)值是 False （無(wú)輸出）。

可選的參數(shù) parser 指定了 DocTestParser 對(duì)象（或一個(gè)可替換的對(duì)象），用于從文檔串中提取 doctest 。

如果可選的參數(shù) recurse 是 False ，那么 DocTestFinder.find() 將只檢查給定的對(duì)象，而不是任何包含的對(duì)象。

如果可選參數(shù) exclude_empty 為 False ，那么 DocTestFinder.find() 將包括對(duì)文檔字符串為空的對(duì)象的測(cè)試。

DocTestFinder 定義了以下方法：

find(obj[, name][, module][, globs][, extraglobs])?

返回 DocTest 的列表，該列表由 obj 的文檔串或其包含的任何對(duì)象的文檔串定義。

可選參數(shù) name 指定了對(duì)象的名稱；這個(gè)名稱將被用來(lái)為返回的 DocTest 構(gòu)建名稱。 如果沒(méi)有指定*name*，則使用 obj.__name__ 。

可選參數(shù) module 是包含給定對(duì)象的模塊。如果沒(méi)有指定模塊或者是 None ，那么測(cè)試查找器將試圖自動(dòng)確定正確的模塊。 該對(duì)象被使用的模塊：

• 作為一個(gè)默認(rèn)的命名空間，如果沒(méi)有指定 globs 。

• 為了防止 DocTestFinder 從其他模塊導(dǎo)入的對(duì)象中提取 DocTest 。 (包含有除 module 以外的模塊的對(duì)象會(huì)被忽略)。

• 找到包含該對(duì)象的文件名。

• 找到該對(duì)象在其文件中的行號(hào)。

如果 module 是 False ，將不會(huì)試圖找到這個(gè)模塊。 這是不明確的，主要用于測(cè)試 doctest 本身：如果 module 是 False ，或者是 None 但不能自動(dòng)找到，那么所有對(duì)象都被認(rèn)為屬于（不存在的）模塊，所以所有包含的對(duì)象將（遞歸地）被搜索到 doctest 。

每個(gè) DocTest 的 globals 是由 globs 和 extraglobs 組合而成的（ extraglobs 的綁定覆蓋 globs 的綁定）。 為每個(gè) DocTest 創(chuàng)建一個(gè)新的 globals 字典的淺層拷貝。如果沒(méi)有指定 globs ，那么它默認(rèn)為模塊的 __dict__ ，如果指定了或者為 {} ，則除外。 如果沒(méi)有指定 extraglobs ，那么它默認(rèn)為 {} 。

DocTestParser 對(duì)象?

class doctest.DocTestParser?

一個(gè)處理類(lèi)，用于從一個(gè)字符串中提取交互式的用例，并使用它們來(lái)創(chuàng)建一個(gè) DocTest 對(duì)象。

DocTestParser 定義了以下方法：

get_doctest(string, globs, name, filename, lineno)?

從給定的字符串中提取所有的測(cè)試用例，并將它們收集到一個(gè) DocTest 對(duì)象中。

globs 、 name 、 filename 和 lineno 是新的 DocTest 對(duì)象的屬性。 更多信息請(qǐng)參見(jiàn) DocTest 的文檔。

get_examples(string, name='<string>')?

從給定的字符串中提取所有的測(cè)試用例，并以 Example 對(duì)象列表的形式返回。 行數(shù)以 0 為基數(shù)。 可選參數(shù) name 用于識(shí)別這個(gè)字符串的名稱，只用于錯(cuò)誤信息。

parse(string, name='<string>')?

將給定的字符串分成用例和中間的文本，并以 Example 和字符串交替的列表形式返回。 Example 的行號(hào)以 0 為基數(shù)。 可選參數(shù) name 用于識(shí)別這個(gè)字符串的名稱，只用于錯(cuò)誤信息。

DocTestRunner 對(duì)象?

class doctest.DocTestRunner(checker=None, verbose=None, optionflags=0)?

一個(gè)處理類(lèi)，用于執(zhí)行和驗(yàn)證 DocTest 中的交互式用例。

預(yù)期輸出和實(shí)際輸出之間的比較是由一個(gè) OutputChecker 完成的。 這種比較可以用一些選項(xiàng)標(biāo)志來(lái)定制；更多信息請(qǐng)看 選項(xiàng)標(biāo)記 部分。 如果選項(xiàng)標(biāo)志不夠，那么也可以通過(guò)向構(gòu)造函數(shù)傳遞 OutputChecker 的子類(lèi)來(lái)定制比較。

測(cè)試運(yùn)行器的顯示輸出可以通過(guò)兩種方式控制。首先，一個(gè)輸出函數(shù)可以被傳遞給 TestRunner.run() ；這個(gè)函數(shù)將被調(diào)用，并顯示出應(yīng)該顯示的字符串。 它的默認(rèn)值是 sys.stdout.write 。 如果捕獲輸出是不夠的，那么也可以通過(guò)子類(lèi)化 DocTestRunner 來(lái)定制顯示輸出，并重寫(xiě) report_start() , report_success() , report_unexpected_exception() 和 report_failure() 方法。

可選的關(guān)鍵字參數(shù) checker 指定了 OutputChecker 對(duì)象（或其相似替換），它應(yīng)該被用來(lái)比較預(yù)期輸出和 doctest 用例的實(shí)際輸出。

可選的關(guān)鍵字參數(shù) verbose 控制 DocTestRunner 的詳細(xì)程度。 如果 verbose 是 True ，那么每個(gè)用例的信息都會(huì)被打印出來(lái)，當(dāng)它正在運(yùn)行時(shí)。 如果 verbose 是 False ，則只打印失敗的信息。 當(dāng) verbose 沒(méi)有指定，或者為 None ，如果使用了命令行開(kāi)關(guān) -v ，則使用verbose輸出。

可選的關(guān)鍵字參數(shù) optionflags 可以用來(lái)控制測(cè)試運(yùn)行器如何比較預(yù)期輸出和實(shí)際輸出，以及如何顯示失敗。更多信息，請(qǐng)參見(jiàn)章節(jié) 選項(xiàng)標(biāo)記 。

DocTestParser 定義了以下方法：

report_start(out, test, example)?

報(bào)告測(cè)試運(yùn)行器即將處理給定的用例。提供這個(gè)方法是為了讓 DocTestRunner 的子類(lèi)能夠定制他們的輸出；它不應(yīng)該被直接調(diào)用。

example 是即將被處理的用。 test 是 包含用例 的測(cè)試。 out 是傳遞給 DocTestRunner.run() 的輸出函數(shù)。

report_success(out, test, example, got)?

報(bào)告給定的用例運(yùn)行成功。 提供這個(gè)方法是為了讓 DocTestRunner 的子類(lèi)能夠定制他們的輸出；它不應(yīng)該被直接調(diào)用。

example 是即將被處理的用例。 got 是這個(gè)例子的實(shí)際輸出。 test 是包含 example 的測(cè)試。 out 是傳遞給 DocTestRunner.run() 的輸出函數(shù)。

report_failure(out, test, example, got)?

報(bào)告給定的用例運(yùn)行失敗。 提供這個(gè)方法是為了讓 DocTestRunner 的子類(lèi)能夠定制他們的輸出；它不應(yīng)該被直接調(diào)用。

example 是即將被處理的用例。 got 是這個(gè)例子的實(shí)際輸出。 test 是包含 example 的測(cè)試。 out 是傳遞給 DocTestRunner.run() 的輸出函數(shù)。

report_unexpected_exception(out, test, example, exc_info)?

報(bào)告給定的用例觸發(fā)了一個(gè)異常。 提供這個(gè)方法是為了讓 DocTestRunner 的子類(lèi)能夠定制他們的輸出；它不應(yīng)該被直接調(diào)用。

example 是將要被處理的用例。 exc_info 是一個(gè)元組，包含關(guān)于異常的信息（如由 sys.exc_info() 返回）。 test 是包含 example 的測(cè)試。 out 是傳遞給 DocTestRunner.run() 的輸出函數(shù)。

run(test, compileflags=None, out=None, clear_globs=True)?

在 test （一個(gè) DocTest 對(duì)象）中運(yùn)行這些用例，并使用寫(xiě)入函數(shù) out 顯示結(jié)果。

這些用例都是在命名空間 test.globs 中運(yùn)行的。 如果 clear_globs 為 True （默認(rèn)），那么這個(gè)命名空間將在測(cè)試運(yùn)行后被清除，以幫助進(jìn)行垃圾回收。如果你想在測(cè)試完成后檢查命名空間，那么使用 clear_globs=False 。

compileflags 給出了 Python 編譯器在運(yùn)行例子時(shí)應(yīng)該使用的標(biāo)志集。如果沒(méi)有指定，那么它將默認(rèn)為適用于 globs 的 future-import 標(biāo)志集。

每個(gè)用例的輸出都使用 DocTestRunner 的輸出檢查器進(jìn)行檢查，結(jié)果由 DocTestRunner.report_*() 方法進(jìn)行格式化。

summarize(verbose=None)?

打印這個(gè) DocTestRunner 運(yùn)行過(guò)的所有測(cè)試用例的摘要，并返回一個(gè) named tuple TestResults(failed, attempted) 。

可選的 verbose 參數(shù)控制摘要的詳細(xì)程度。 如果沒(méi)有指定 verbose ，那么將使用 DocTestRunner 的 verbose 。

OutputChecker 對(duì)象?

class doctest.OutputChecker?

一個(gè)用于檢查測(cè)試用例的實(shí)際輸出是否與預(yù)期輸出相匹配的類(lèi)。 OutputChecker 定義了兩個(gè)方法： check_output() ，比較給定的一對(duì)輸出，如果它們匹配則返回 True ； output_difference() ，返回一個(gè)描述兩個(gè)輸出之間差異的字符串。

OutputChecker 定義了以下方法：

check_output(want, got, optionflags)?

如果一個(gè)用例的實(shí)際輸出（ got ）與預(yù)期輸出（ want ）匹配，則返回 True 。 如果這些字符串是相同的，總是被認(rèn)為是匹配的；但是根據(jù)測(cè)試運(yùn)行器使用的選項(xiàng)標(biāo)志，也可能有幾種非精確的匹配類(lèi)型。 參見(jiàn)章節(jié) 選項(xiàng)標(biāo)記 了解更多關(guān)于選項(xiàng)標(biāo)志的信息。

output_difference(example, got, optionflags)?

返回一個(gè)字符串，描述給定用例（ example ）的預(yù)期輸出和實(shí)際輸出（ got ）之間的差異。 optionflags 是用于比較 want 和 got 的選項(xiàng)標(biāo)志集。