Up One Level Python ライブラリリファレンス Contents Module Index Index
Previous: Up: 23.2 doctest Next:


23.2.7 基本 API

関数 testmod() および testfile() は、 基本的なほとんどの用途に十分な doctest インタフェースを提供しています。 これら二つの関数についてもっとくだけた説明を読みたければ、 23.2.1 節および 23.2.2 節 を参照してください。

testfile( filename[, module_relative][, name][, package][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, parser][, encoding])

filename 以外の引数は全てオプションで、キーワード引数形式で 指定せねばなりません。

filename に指定したファイル内にある例題をテストします。 "(failure_count, test_count)" を返します。

オプション引数の module_relative は、ファイル名をどのように 解釈するかを指定します:

オプション引数 name には、テストの名前を指定します; デフォルトの 場合や None を指定した場合、 os.path.basename(filename) になります。

オプション引数 package には、 Python パッケージを指定するか、 モジュール相対のファイル名の場合には相対の基準ディレクトリとなる Python パッケージの名前を指定します。パッケージを指定しない倍、 関数を呼び出しているモジュールのディレクトリを相対の基準 ディレクトリとして使います。module_relative をFalse に指定している場合、package を指定するとエラーになります。

オプション引数globs には辞書を指定します。この辞書は、 例題を実行する際のグローバル変数として用いられます。 doctest はこの辞書の浅いコピーを生成するので、例題は白紙の 状態からスタートします。デフォルトの場合やNone を指定 した場合、新たな空の辞書になります。

オプション引数 extraglobs には辞書を指定します。この辞書は、 例題を実行する際にグローバル変数にマージされます。マージは dict.update() のように振舞います: globs と extraglobs との間に同じキー値がある場合、両者を合わせた 辞書中にはextraglobs の方の値が入ります。この仕様は、 パラメタ付きで doctest を実行するという、やや進んだ機能です。 例えば、一般的な名前を使って基底クラス向けに doctest を書いておき、 その後で辞書で一般的な名前からテストしたいサブクラスへの対応付けを 行う辞書をextraglobs に渡して、様々なサブクラスをテスト できます。

オプション引数 verbose が真の場合、様々な情報を出力します。 偽の場合にはテストの失敗だけを報告します。デフォルトの場合や None を指定した場合、sys.argv に -v を指定しない限り この値は真になりません。

オプション引数report が真の場合、テストの最後にサマリを 出力します。それ以外の場合には何も出力しません。verbose モードの 場合、サマリには詳細な情報を出力しますが、そうでない場合には サマリはとても簡潔になります (実際には、全てのテストが成功した場合には 何も出力しません)。

オプション引数 optionflags は、各オプションフラグの論理和を とった値を指定します。23.2.6 節を参照してください。

オプション引数 raise_on_error の値はデフォルトでは偽です。 真にすると、最初のテスト失敗や予期しない例外が起きたときに例外を 送出します。このオプションを使うと、失敗の原因を検死デバッグ (post-mortem debug) できます。デフォルトの動作では、例題の実行を 継続します。

オプション引数 parser には、DocTestParser (または そのサブクラス) を指定します。このクラスはファイルから例題を抽出 するために使われます。デフォルトでは通常のパーザ (DocTestParser()) です。

オプション引数 encoding にはファイルをユニコードに変換する際に使われる エンコーディングを指定します。

バージョン 2.4 で 新たに追加 された仕様です。

バージョン 2.5 で 変更 された仕様: encoding パラメタが追加されました

testmod( [m][, name][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, exclude_empty])

引数は全てオプションで、m以外の引数はキーワード引数として 指定せねばなりません。

モジュール m (m を指定しないかNone にした場合には __main__) から到達可能な関数およびクラスの docstring 内に ある例題をテストします。m.__doc__ 内の例題からテストを 開始します。

また、辞書 m.__test__ が存在し、None で ない場合、この辞書から到達できる例題もテストします。 m.__test__ は、(文字列の) 名前から関数、クラスおよび 文字列への対応付けを行っています。関数およびクラスの場合には、 その docstring 内から例題を検索します。文字列の場合には、docstring と同じようにして例題の検索を直接実行します。

モジュールm に属するオブジェクトにつけられた docstrings のみを 検索します。

"(failure_count, test_count)" を返します。

オプション引数 name には、モジュールの名前を指定します。 デフォルトの場合やNone を指定した場合には、 m.__name__ を使います。

オプション引数 exclude_empty はデフォルトでは偽になっています。 この値を真にすると、doctest を持たないオブジェクトを考慮から 外します。デフォルトの設定は依存のバージョンとの互換性を考えたハック であり、doctest.master.summarize() と testmod() を 合わせて利用しているようなコードでも、テスト例題を持たないオブジェクト から出力を得るようにしています。 新たに追加されたDocTestFinder のコンストラクタの exclude_empty はデフォルトで真になります。

オプション引数 extraglobs, verbose, report, optionflags, raise_on_error, および globs は 上で説明した testfile() の引数と同じです。ただし、 globs のデフォルト値はm.__dict__ になります。

バージョン 2.3 で 変更 された仕様: optionflags パラメタを追加しました

バージョン 2.4 で 変更 された仕様: extraglobs, raise_on_error およびexclude_empty パラメタを追加しました

バージョン 2.5 で 変更 された仕様: オプション引数 isprivate は、2.4 では非推奨でしたが、 廃止されました

単一のオブジェクトに関連付けられた doctest を実行するための関数も あります。この関数は以前のバージョンとの互換性のために提供されて います。この関数を撤廃する予定はありませんが、役に立つことは ほとんどありません:

run_docstring_examples( f, globs[, verbose][, name][, compileflags][, optionflags])

オブジェクト f に関連付けられた例題をテストします。 f はモジュール、関数、またはクラスオブジェクトです。

引数globs に辞書を指定すると、その浅いコピーを実行コンテキスト に使います。

オプション引数name はテスト失敗時のメッセージに使われます。 デフォルトの値は NoName です。

オプション引数 verbose の値を真にすると、テストが失敗しなくても 出力を生成します。デフォルトでは、例題のテストに失敗したときのみ 出力を生成します。

オプション引数compileflags には、例題を実行するときに Python バイトコードコンパイラが使うフラグを指定します。デフォルトの場合や None を指定した場合、フラグはglobs 内にある future 機能セットに対応したものになります。

オプション引数 optionflags は、上で述べたtestfile() と同様の働きをします。

Up One Level Python ライブラリリファレンス Contents Module Index Index
Previous: Up: 23.2 doctest Next:
リリース 2.5 ，19th September, 2006 更新
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。