doctest Advanced API

基本的API是一個簡單的包裝，旨在使doctest易于使用。它相當靈活，應該滿足大多數(shù)用戶的需求; 但是，如果您需要對測試進行更精細的控制，或者希望擴展doctest的功能，那么您應該使用高級API。

高級API圍繞兩個容器類進行，這兩個容器類用于存儲從doctest案例中提取的交互式示例：

• Example：一個Python 語句，與它的預期輸出配對。

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

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

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

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

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

• OutputChecker：將doctest示例中的實際輸出與預期輸出進行比較，并確定它們是否匹配。

下圖總結(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)

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

2.4版本中的新功能。

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

examples

Example編碼應該由此測試運行的各個交互式Python示例的對象列表。

globs

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

name

一個字符串名稱標識DocTest。通常，這是測試從中提取的對象或文件的名稱。

filename

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

lineno

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

docstring

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

示例對象

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

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

2.4版本中的新功能。

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

source

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

want

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

exc_msg

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

lineno

包含示例開始處的示例的字符串中的行號。該行號相對于包含字符串的開頭是從零開始的。

indent

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

options

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

DocTestFinder對象

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

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

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

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

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

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

2.4版本中的新功能。

DocTestFinder 定義了以下方法：

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

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

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

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

• 作為默認命名空間，如果沒有指定globs。

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

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

• 幫助查找文件中對象的行號。

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

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

DocTestParser對象

class doctest.DocTestParser

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

2.4版本中的新功能。

DocTestParser 定義了以下方法：

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

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

globs，name，filename和lineno是新DocTest對象的屬性。請參閱文檔以DocTest獲取更多信息。

get_examples(string[, name])

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

parse(string[, name])

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

DocTestRunner對象

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

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

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

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

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

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

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

2.4版本中的新功能。

DocTestParser 定義了以下方法：

report_start(out, test, example)

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

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

report_success(out, test, example, got)

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

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

report_failure(out, test, example, got)

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

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

report_unexpected_exception(out, test, example, exc_info)

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

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

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

運行在實施例中測試（一個DocTest對象），并使用寫入器功能顯示結(jié)果出來。

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

compileflags給出了運行示例時Python編譯器應該使用的一組標志。如果未指定，則它將默認為適用于globs的future-import標志集。

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

summarize([verbose])

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

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

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

OutputChecker對象

class doctest.OutputChecker

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

2.4版本中的新功能。

OutputChecker 定義了以下方法：

check_output(want, got, optionflags)

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

output_difference(example, got, optionflags)

返回一個字符串，描述給定示例（示例）的預期輸出與實際輸出（獲得）之間的差異。optionflags是用來比較想要和得到的選項標志的集合。