哪些文件串被檢查了？?

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

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

<name of M>.__test__.K

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

文檔串的例子是如何被識別的？?

在大多數情況下，對交互式控制臺會(huì )話(huà)的復制和粘貼功能工作得很好，但是 doctest 并不試圖對任何特定的 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!!!
>>>

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

fine輸出：

• 預期輸出不能包含一個(gè)全白的行，因為這樣的行被認為是預期輸出的結束信號。 如果預期的輸出包含一個(gè)空行，在你的測試例子中，在每一個(gè)預期有空行的地方加上``<BLANKLINE>``。

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

• 向stdout的輸出被捕獲，但不向stderr輸出（異?；厮萃ㄟ^(guò)不同的方式被捕獲）。

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

  >>>

  >>> 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
  

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

什么是執行上下文？?

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

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

異常如何處理？?

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

簡(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ā)，該測試就會(huì )成功，list.remove(x): x not in list 的細節如圖所示。

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

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

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

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

>>> 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)型和細節進(jìn)行比較，其余的被忽略。

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

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

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

有些細節你應該讀一遍，但不需要記?。?/p>

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

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

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

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

• 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'
  

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

  >>>

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

選項標記?

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

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

doctest.DONT_ACCEPT_TRUE_FOR_1?

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

doctest.DONT_ACCEPT_BLANKLINE?

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

doctest.NORMALIZE_WHITESPACE?

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

doctest.ELLIPSIS?

當指定時(shí)，預期輸出中的省略號（...）可以匹配實(shí)際輸出中的任何子串。這包括跨行的子串和空子串，所以最好保持簡(jiǎn)單的用法。復雜的用法會(huì )導致與``.*``在正則表達式中容易出現的 "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 現在也忽略了與包含被測異常的模塊有關(guān)的任何信息。

doctest.SKIP?

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

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

doctest.COMPARISON_FLAGS?

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

第二組選項控制測試失敗的報告方式：

doctest.REPORT_UDIFF?

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

doctest.REPORT_CDIFF?

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

doctest.REPORT_NDIFF?

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

doctest.REPORT_ONLY_FIRST_FAILURE?

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

doctest.FAIL_FAST?

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

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

3.4 新版功能.

doctest.REPORTING_FLAGS?

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

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

doctest.register_optionflag(name)?

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

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" \| ...

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

一個(gè)用例的 doctest 指令可以修改 doctest 對該用例的行為。 使用 + 來(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]

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

警告?

doctest 是嚴格地要求在預期輸出中完全匹配。 如果哪怕只有一個(gè)字符不匹配，測試就會(huì )失敗。 這可能會(huì )讓你吃驚幾次，在你確切地了解到 Python 對輸出的保證和不保證之前。 例如，當打印一個(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)數在不同的平臺上也會(huì )有小的輸出變化，因為Python在浮點(diǎn)數的格式化上依賴(lài)于平臺的C庫，而C庫在這個(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``的數字在所有的平臺上都是安全的，我經(jīng)常設計一些測試的用例來(lái)產(chǎn)生該形式的數:

>>> 3./4  # utterly safe
0.75

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

DocTest 對象?

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

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

DocTest 定義了以下屬性。 它們由構造函數初始化，不應該被直接修改。

examples?

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

globs?

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

name?

識別 DocTest 的字符串名稱(chēng)。 通常情況下，這是從測試中提取的對象或文件的名稱(chēng)。

filename?

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

lineno?

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

docstring?

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

Example 對象?

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

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

Example 定義了以下屬性。 它們由構造函數初始化，不應該被直接修改。

source?

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

want?

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

exc_msg?

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

lineno?

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

indent?

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

options?

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

DocTestFinder 對象?

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

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

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

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

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

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

DocTestFinder 定義了以下方法：

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

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

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

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

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

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

• 找到包含該對象的文件名。

• 找到該對象在其文件中的行號。

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

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

DocTestParser 對象?

class doctest.DocTestParser?

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

DocTestParser 定義了以下方法：

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

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

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

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

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

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

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

DocTestRunner 對象?

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

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

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

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

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

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

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

DocTestParser 定義了以下方法：

report_start(out, test, example)?

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

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

report_success(out, test, example, got)?

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

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

report_failure(out, test, example, got)?

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

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

report_unexpected_exception(out, test, example, exc_info)?

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

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

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

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

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

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

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

summarize(verbose=None)?

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

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

OutputChecker 對象?

class doctest.OutputChecker?

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

OutputChecker 定義了以下方法：

check_output(want, got, optionflags)?

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

output_difference(example, got, optionflags)?

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