doctest Advanced API

基本的API是一個(gè)簡(jiǎn)單的包裝，旨在使doctest易于使用。它相當(dāng)靈活，應(yīng)該滿足大多數(shù)用戶的需求; 但是，如果您需要對(duì)測(cè)試進(jìn)行更精細(xì)的控制，或者希望擴(kuò)展doctest的功能，那么您應(yīng)該使用高級(jí)API。

高級(jí)API圍繞兩個(gè)容器類進(jìn)行，這兩個(gè)容器類用于存儲(chǔ)從doctest案例中提取的交互式示例：

• Example：一個(gè)Python 語(yǔ)句，與它的預(yù)期輸出配對(duì)。

• DocTest：Examples 的集合，通常從單個(gè)文檔字符串或文本文件中提取。

定義其他處理類來查找，分析和運(yùn)行，并檢查doctest示例：

• DocTestFinder：查找給定模塊中的所有文檔字符串，并使用DocTestParsera DocTest從包含交互式示例的每個(gè)文檔字符串中創(chuàng)建一個(gè)。

• DocTestParser：DocTest從字符串中創(chuàng)建一個(gè)對(duì)象（例如對(duì)象的文檔字符串）。

• DocTestRunner：執(zhí)行DocTest中的例子，并使用一個(gè)OutputChecker來驗(yàn)證它們的輸出。

• OutputChecker：將doctest示例中的實(shí)際輸出與預(yù)期輸出進(jìn)行比較，并確定它們是否匹配。

下圖總結(jié)了這些處理類之間的關(guān)系：

                            list of:
+------+                   +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+    |        ^     +---------+     |       ^    (printed)
            |        |     | Example |     |       |
            v        |     |   ...   |     v       |
           DocTestParser   | Example |   OutputChecker
                           +---------+

DocTest Objects

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

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

2.4版本中的新功能。

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

examples

Example編碼應(yīng)該由此測(cè)試運(yùn)行的各個(gè)交互式Python示例的對(duì)象列表。

globs

應(yīng)該運(yùn)行示例的名稱空間（又稱全局變量）。這是一個(gè)將名稱映射到值的字典。globs在測(cè)試運(yùn)行之后，示例所做的任何對(duì)名稱空間的更改（例如綁定新變量）都會(huì)反映出來。

name

一個(gè)字符串名稱標(biāo)識(shí)DocTest。通常，這是測(cè)試從中提取的對(duì)象或文件的名稱。

filename

這DocTest是從中提取的文件的名稱; 或者None如果文件名是未知的，或者如果DocTest沒有從文件中提取。

lineno

行號(hào)在filename哪里DocTest開始，或None行號(hào)是否不可用。該行號(hào)相對(duì)于文件的開頭是從零開始的。

docstring

從中提取測(cè)試None的字符串，或者字符串不可用，或者測(cè)試未從字符串中提取。

示例對(duì)象

class doctest.Example(source, want[, exc_msg][, lineno][, indent][, options])

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

2.4版本中的新功能。

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

source

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

want

運(yùn)行示例源代碼的預(yù)期輸出（來自標(biāo)準(zhǔn)輸出，或者異常情況下的回溯）。want除非沒有輸出，否則以換行符結(jié)束，在這種情況下，它是一個(gè)空字符串。構(gòu)造函數(shù)在必要時(shí)添加一個(gè)換行符。

exc_msg

該示例生成的異常消息，如果該示例預(yù)計(jì)會(huì)生成異常; 或者None如果不希望產(chǎn)生異常。該異常消息與返回值進(jìn)行比較traceback.format_exception_only()。exc_msg除非是換行符，否則以換行符結(jié)尾None。如果需要，構(gòu)造函數(shù)會(huì)添加一個(gè)換行符。

lineno

包含示例開始處的示例的字符串中的行號(hào)。該行號(hào)相對(duì)于包含字符串的開頭是從零開始的。

indent

包含字符串中的示例縮進(jìn)，即示例第一個(gè)提示之前的空格字符數(shù)。

options

從選項(xiàng)標(biāo)記到Trueor的字典映射False，用于覆蓋此示例的默認(rèn)選項(xiàng)。任何未包含在此字典中的選項(xiàng)標(biāo)志都保留默認(rèn)值（由DocTestRunners 指定optionflags）。默認(rèn)情況下，不設(shè)置任何選項(xiàng)。

DocTestFinder對(duì)象

class doctest.DocTestFinder([verbose][, parser][, recurse][, exclude_empty])

一個(gè)處理類，用于DocTest從文檔字符串及其包含對(duì)象的文檔字符串中提取與給定對(duì)象相關(guān)的s。DocTests可以從下列對(duì)象類型中提?。耗K，函數(shù)，類，方法，靜態(tài)方法，類方法和屬性。

可選參數(shù)verbose可用于顯示查找器搜索的對(duì)象。它默認(rèn)為False（不輸出）。

可選參數(shù)解析器指定DocTestParser用于從文檔字符串中提取文檔測(cè)試的對(duì)象（或插入替換）。

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

如果可選參數(shù)exclude_empty為false，DocTestFinder.find()則將包含具有空文檔字符串的對(duì)象的測(cè)試。

2.4版本中的新功能。

DocTestFinder 定義了以下方法：

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

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

可選參數(shù)名稱指定對(duì)象的名稱; 這個(gè)名字將被用來為返回的DocTests 構(gòu)造名字。如果沒有指定名稱，則obj.__name__使用。

可選參數(shù)模塊是包含給定對(duì)象的模塊。如果模塊沒有被指定或者是None，則測(cè)試發(fā)現(xiàn)者將嘗試自動(dòng)確定正確的模塊。使用該對(duì)象的模塊：

• 作為默認(rèn)命名空間，如果沒有指定globs。

• 阻止DocTestFinder從其他模塊導(dǎo)入的對(duì)象中提取DocTests。（包含模塊以外的模塊的包含對(duì)象將被忽略。）

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

• 幫助查找文件中對(duì)象的行號(hào)。

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

對(duì)于每個(gè)全局DocTest通過組合形成水珠和extraglobs（在綁定extraglobs倍率綁定在水珠）。為每個(gè)字典創(chuàng)建一個(gè)新的globals字典的淺表副本DocTest。如果未指定globs，則默認(rèn)為模塊的___dict__ （如果已指定）或{}以其他方式指定。如果_extraglobs沒有被指定，那么它默認(rèn)為{}。

DocTestParser對(duì)象

class doctest.DocTestParser

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

2.4版本中的新功能。

DocTestParser 定義了以下方法：

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

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

globs，name，filename和lineno是新DocTest對(duì)象的屬性。請(qǐng)參閱文檔以DocTest獲取更多信息。

get_examples(string[, name])

從給定的字符串中提取所有doctest示例，并將它們作為Example對(duì)象列表返回。行號(hào)是從0開始的?？蛇x參數(shù)名稱是標(biāo)識(shí)此字符串的名稱，僅用于錯(cuò)誤消息。

parse(string[, name])

將給定的字符串分成示例和干預(yù)文本，并將它們作為交替Examples和字符串的列表返回。Examples的行號(hào)是基于0的?？蛇x參數(shù)名稱是標(biāo)識(shí)此字符串的名稱，僅用于錯(cuò)誤消息。

DocTestRunner對(duì)象

class doctest.DocTestRunner([checker][, verbose][, optionflags])

處理類用于執(zhí)行和驗(yàn)證DocTest中的交互式示例。

預(yù)期產(chǎn)出與實(shí)際產(chǎn)出之間的比較由OutputChecker。這種比較可以用許多選項(xiàng)標(biāo)志來定制; 有關(guān)更多信息，請(qǐng)參閱選項(xiàng)標(biāo)志部分。如果選項(xiàng)標(biāo)志不足，則可以通過OutputChecker向構(gòu)造函數(shù)傳遞一個(gè)子類來定制比較。

測(cè)試運(yùn)行者的顯示輸出可以通過兩種方式進(jìn)行控制。首先，可以傳遞一個(gè)輸出函數(shù)TestRunner.run(); 這個(gè)函數(shù)將會(huì)被顯示的字符串調(diào)用。它默認(rèn)為sys.stdout.write。如果捕獲的輸出不充分，則顯示輸出也可以通過繼承DocTestRunner，并覆蓋方法定制report_start()，report_success()，report_unexpected_exception()，和report_failure()。

可選的關(guān)鍵字參數(shù)檢查器指定OutputChecker應(yīng)該用于比較預(yù)期輸出與doctest示例的實(shí)際輸出的對(duì)象（或插入替換）。

可選的關(guān)鍵字參數(shù)verbose控制著DocTestRunner冗長(zhǎng)。如果詳細(xì)是True，則會(huì)在每個(gè)示例運(yùn)行時(shí)打印信息。如果詳細(xì)是False，則只打印故障。如果verbose未指定，或者None使用詳細(xì)輸出，則使用命令行開關(guān)-v。

可選的關(guān)鍵字參數(shù)optionflags可用于控制測(cè)試運(yùn)行器如何將預(yù)期輸出與實(shí)際輸出進(jìn)行比較，以及它如何顯示故障。有關(guān)更多信息，請(qǐng)參見選項(xiàng)標(biāo)志部分。

2.4版本中的新功能。

DocTestParser 定義了以下方法：

report_start(out, test, example)

報(bào)告測(cè)試運(yùn)行人員即將處理給出的示例。提供此方法以允許其子類DocTestRunner定制其輸出；它不應(yīng)該直接調(diào)用。

例子就是要處理的例子。測(cè)試是包含示例的測(cè)試。out是傳遞給的輸出函數(shù)DocTestRunner.run()。

report_success(out, test, example, got)

報(bào)告給出的示例已成功運(yùn)行。提供此方法以允許其子類DocTestRunner定制其輸出；它不應(yīng)該直接調(diào)用。

例子就是要處理的例子。得到的是實(shí)例的實(shí)際輸出。測(cè)試是包含示例的測(cè)試。out是傳遞給的輸出函數(shù)DocTestRunner.run()。

report_failure(out, test, example, got)

報(bào)告給出的例子失敗。提供此方法以允許其子類DocTestRunner定制其輸出; 它不應(yīng)該直接調(diào)用。

例子就是要處理的例子。得到的是實(shí)例的實(shí)際輸出。測(cè)試是包含示例的測(cè)試。out是傳遞給的輸出函數(shù)DocTestRunner.run()。

report_unexpected_exception(out, test, example, exc_info)

報(bào)告給出的示例引發(fā)了意外的異常。提供此方法以允許其子類DocTestRunner定制其輸出; 它不應(yīng)該直接調(diào)用。

例子就是要處理的例子。exc_info是包含有關(guān)意外異常（由返回的sys.exc_info()）的信息的元組。測(cè)試是包含示例的測(cè)試。out是傳遞給的輸出函數(shù)DocTestRunner.run()。

run(test[, compileflags][, out][, clear_globs])

運(yùn)行在實(shí)施例中測(cè)試（一個(gè)DocTest對(duì)象），并使用寫入器功能顯示結(jié)果出來。

這些示例在命名空間中運(yùn)行test.globs。如果clear_globs為true（缺省值），那么該名稱空間將在測(cè)試運(yùn)行后清除，以幫助進(jìn)行垃圾回收。如果您想在測(cè)試完成后檢查名稱空間，請(qǐng)使用clear_globs = False。

compileflags給出了運(yùn)行示例時(shí)Python編譯器應(yīng)該使用的一組標(biāo)志。如果未指定，則它將默認(rèn)為適用于globs的future-import標(biāo)志集。

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

summarize([verbose])

打印由此DocTestRunner運(yùn)行的所有測(cè)試用例的摘要，并返回一個(gè)指定的元組 TestResults(failed, attempted)。

可選的詳細(xì)參數(shù)控制摘要的詳細(xì)程度。如果沒有指定DocTestRunner詳細(xì)程度，則使用冗長(zhǎng)度。

在版本2.6中更改：使用命名的元組。

OutputChecker對(duì)象

class doctest.OutputChecker

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

2.4版本中的新功能。

OutputChecker 定義了以下方法：

check_output(want, got, optionflags)

True如果示例（got）的實(shí)際輸出與預(yù)期輸出（想要）匹配，則返回。如果這些字符串相同，則始終認(rèn)為它們匹配；但取決于測(cè)試運(yùn)行器使用的選項(xiàng)標(biāo)志，還可以使用幾種非精確匹配類型。有關(guān)選項(xiàng)標(biāo)志的更多信息，請(qǐng)參見選項(xiàng)標(biāo)志部分。

output_difference(example, got, optionflags)

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