##
7 基本 API

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

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

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

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

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

  - module_relative が `True` (デフォルト) の場合、 filename は OS に依存しないモジュールの相対パスになります。 デフォルトでは、このパスは関数 `testfile` を呼び出して いるモジュールからの相対パスになります; ただし、package 引数を指定した場合には、パッケージからの相対になります。 OS への依存性を除くため、filename ではパスを分割する 文字に`/` を使わねばならず、絶対パスにしてはなりません (パス文字列を`/` で始めてはなりません)。
  - module_relative が `False` の場合、filename は OS 依存のパスを示します。パスは絶対パスでも相対パスでも かまいません; 相対パスにした場合、現在の作業ディレクトリを 基準に解決します。

  オプション引数 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 は、各オプションフラグの論理和を とった値を指定します。5.2.6 節を参照してください。

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

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

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

`testmod`( | [m][, name][, globs][, verbose][, isprivate][, 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__` になります。

  オプション引数 isprivate には、ある名前がプライベート名で あるかどうかを決定する関数を指定します。デフォルトでは、全ての 名前を public とみなします。isprivate は `doctest.is_private` にも設定できます。この場合、Python のアンダースコアを使った名前付け 規約に従ってプライベート名かどうかを判別し、テストをスキップします。

  リリース 2.4 で撤廃されました。 isprivate を使うのは賢くありません - 使わないようにしてください。名前に基づいてテストをスキップしたければ、 `DocTestFinder.find()` の返すリストをフィルタしてください。

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

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

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

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

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

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

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

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

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

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