"doctest" --- Test interactive Python examples
**********************************************

**ソースコード:** Lib/doctest.py

======================================================================

"doctest" モジュールは、対話的 Python セッションのように見えるテキスト
を探し出し、セッションの内容を実行して、そこに書かれている通りに振舞う
かを調べます。 "doctest" は以下のような用途によく使われています:

* モジュールの docstring (ドキュメンテーション文字列) 中にある対話実行
  例のすべてが書かれている通りに動作するか検証することで、docstring の
  内容が最新かどうかチェックする。

* テストファイルやテストオブジェクト中の対話実行例が期待通りに動作する
  かを検証することで、回帰テストを実現します。

* 入出力例を豊富に使ったパッケージのチュートリアルドキュメントが書けま
  す。入出力例と解説文のどちらに注目するかによって、ドキュメントは「読
  めるテスト」にも「実行できるドキュメント」にもなります。

以下に完全かつ短い実行例を示します:

   """
   This is the "example" module.

   The example module supplies one function, factorial().  For example,

   >>> factorial(5)
   120
   """

   def factorial(n):
       """Return the factorial of n, an exact integer >= 0.

       >>> [factorial(n) for n in range(6)]
       [1, 1, 2, 6, 24, 120]
       >>> factorial(30)
       265252859812191058636308480000000
       >>> factorial(-1)
       Traceback (most recent call last):
           ...
       ValueError: n must be >= 0

       Factorials of floats are OK, but the float must be an exact integer:
       >>> factorial(30.1)
       Traceback (most recent call last):
           ...
       ValueError: n must be exact integer
       >>> factorial(30.0)
       265252859812191058636308480000000

       It must also not be ridiculously large:
       >>> factorial(1e100)
       Traceback (most recent call last):
           ...
       OverflowError: n too large
       """

       import math
       if not n >= 0:
           raise ValueError("n must be >= 0")
       if math.floor(n) != n:
           raise ValueError("n must be exact integer")
       if n+1 == n:  # catch a value like 1e300
           raise OverflowError("n too large")
       result = 1
       factor = 2
       while factor <= n:
           result *= factor
           factor += 1
       return result


   if __name__ == "__main__":
       import doctest
       doctest.testmod()

"example.py" をコマンドラインから直接実行すると、 "doctest" はその魔法
を働かせます:

   $ python example.py
   $

出力は何もありません！しかしこれが正常で、すべての実行例が正しく動作す
ることを意味しています。スクリプトに "-v" を与えると、 "doctest" は何
を行おうとしているのかを記録した詳細なログを出力し、最後にまとめを出力
します:

   $ python example.py -v
   Trying:
       factorial(5)
   Expecting:
       120
   ok
   Trying:
       [factorial(n) for n in range(6)]
   Expecting:
       [1, 1, 2, 6, 24, 120]
   ok

といった具合で、最後には:

   Trying:
       factorial(1e100)
   Expecting:
       Traceback (most recent call last):
           ...
       OverflowError: n too large
   ok
   2 items passed all tests:
      1 tests in __main__
      8 tests in __main__.factorial
   9 tests in 2 items.
   9 passed and 0 failed.
   Test passed.
   $

That's all you need to know to start making productive use of
"doctest"! Jump in.  The following sections provide full details.
Note that there are many examples of doctests in the standard Python
test suite and libraries. Especially useful examples can be found in
the standard test file "Lib/test/test_doctest/test_doctest.py".


簡単な利用法: docstring 中の実行例をチェックする
================================================

doctest を試す簡単な方法 (とはいえ、いつもそうする必要はないのですが)
は、各モジュール "M" の最後を、以下のようにして締めくくることです:

   if __name__ == "__main__":
       import doctest
       doctest.testmod()

こうすると、 "doctest" は "M" 中の docstring を検査します。

モジュールをスクリプトとして実行すると、docstring 中の実行例が実行され
、検証されます:

   python M.py

docstring に書かれた実行例の実行が失敗しない限り、何も表示されません。
失敗すると、失敗した実行例と、その原因が (場合によっては複数) 標準出力
に印字され、最後に "***Test Failed*** N failures." という行を出力しま
す。ここで、*N* は失敗した実行例の数です。

一方、"-v" スイッチをつけて走らせると:

   python M.py -v

実行を試みたすべての実行例について詳細に報告し、最後に各種まとめを行っ
た内容が標準出力に印字されます。

"verbose=True" を "testmod()" に渡せば、詳細報告 (verbose) モードを強
制できます。また、 "verbose=False" にすれば禁止できます。どちらの場合
にも、 "testmod()" は "sys.argv" 上のスイッチを調べません。(したがって
、 "-v" をつけても効果はありません)。

There is also a command line shortcut for running "testmod()".  You
can instruct the Python interpreter to run the doctest module directly
from the standard library and pass the module name(s) on the command
line:

   python -m doctest -v example.py

This will import "example.py" as a standalone module and run
"testmod()" on it.  Note that this may not work correctly if the file
is part of a package and imports other submodules from that package.

"testmod()" の詳しい情報は 基本 API 節を参照してください。


簡単な利用法: テキストファイル中の実行例をチェックする
======================================================

doctest のもう一つの簡単な用途は、テキストファイル中にある対話実行例に
対するテストです。これには "testfile()" 関数を使います:

   import doctest
   doctest.testfile("example.txt")

この短いスクリプトは、 "example.txt" というファイルの中に入っている対
話モードの Python 操作例すべてを実行して、その内容を検証します。ファイ
ルの内容は一つの巨大な docstring であるかのように扱われます; ファイル
が Python プログラムである必要はありません！例えば、 "example.txt" に
は以下のような内容が入っているとします:

   The ``example`` module
   ======================

   Using ``factorial``
   -------------------

   This is an example text file in reStructuredText format.  First import
   ``factorial`` from the ``example`` module:

       >>> from example import factorial

   Now use it:

       >>> factorial(6)
       120

"doctest.testfile("example.txt")" を実行すると、このドキュメント内のエ
ラーを見つけ出します:

   File "./example.txt", line 14, in example.txt
   Failed example:
       factorial(6)
   Expected:
       120
   Got:
       720

"testmod()" と同じく、 "testfile()" は実行例が失敗しない限り何も表示し
ません。実行例が失敗すると、失敗した実行例とその原因が (場合によっては
複数) "testmod()" と同じ書式で標準出力に書き出されます。

デフォルトでは、 "testfile()" は自分自身を呼び出したモジュールのあるデ
ィレクトリを探します。その他の場所にあるファイルを見に行くように
"testfile()" に指示するためのオプション引数についての説明は 基本 API
節を参照してください。

"testmod()" と同様に "testfile()" の冗長性 (verbosity) はコマンドライ
ンスイッチ "-v" またはオプションのキーワード引数 *verbose* によって指
定できます。

There is also a command line shortcut for running "testfile()".  You
can instruct the Python interpreter to run the doctest module directly
from the standard library and pass the file name(s) on the command
line:

   python -m doctest -v example.txt

Because the file name does not end with ".py", "doctest" infers that
it must be run with "testfile()", not "testmod()".

"testfile()" の詳細は 基本 API 節を参照してください。


doctest のからくり
==================

この節では、doctest のからくり: どの docstring を見に行くのか、どのよ
うに対話実行例を見つけ出すのか、どんな実行コンテキストを使うのか、例外
をどう扱うか、上記の振る舞いを制御するためにどのようなオプションフラグ
を使うか、について詳しく吟味します。こうした情報は、doctest に対応した
実行例を書くために必要な知識です; 書いた実行例に対して実際に doctest
を実行する上で必要な情報については後続の節を参照してください。


どの docstring が検証されるのか?
--------------------------------

モジュールの docstring と、すべての関数、クラスおよびメソッドの
docstring が検索されます。モジュールに import されたオブジェクトは検索
されません。

In addition, there are cases when you want tests to be part of a
module but not part of the help text, which requires that the tests
not be included in the docstring. Doctest looks for a module-level
variable called "__test__" and uses it to locate other tests. If
"M.__test__" exists, it must be a dict, and each entry maps a (string)
name to a function object, class object, or string. Function and class
object docstrings found from "M.__test__" are searched, and strings
are treated as if they were docstrings.  In output, a key "K" in
"M.__test__" appears with name "M.__test__.K".

For example, place this block of code at the top of "example.py":

   __test__ = {
       'numbers': """
   >>> factorial(6)
   720

   >>> [factorial(n) for n in range(6)]
   [1, 1, 2, 6, 24, 120]
   """
   }

The value of "example.__test__["numbers"]" will be treated as a
docstring and all the tests inside it will be run. It is important to
note that the value can be mapped to a function, class object, or
module; if so, "doctest" searches them recursively for docstrings,
which are then scanned for tests.

検索中に見つかったクラスも同様に再帰的に検索が行われ、クラスに含まれて
いるメソッドおよびネストされたクラスについて docstring のテストが行わ
れます。


docstring 内の実行例をどのように認識するのか?
---------------------------------------------

ほとんどの場合、対話コンソールセッション上でのコピー／ペーストはうまく
動作します。とはいえ、"doctest" は特定の Python シェルの振る舞いを正確
にエミュレーションしようとするわけではありません。

   >>> # comments are ignored
   >>> x = 12
   >>> x
   12
   >>> if x == 13:
   ...     print("yes")
   ... else:
   ...     print("no")
   ...     print("NO")
   ...     print("NO!!!")
   ...
   no
   NO
   NO!!!
   >>>

コードを含む最後の "'>>> '" または "'... '" 行の直下に期待する出力結果
が置かれます。(出力結果がもしあれば) それは次の "'>>> '" 行か、すべて
空白文字の行まで続きます。

詳細事項:

* 期待する出力結果には、空白だけの行が入っていてはなりません。そのよう
  な行は期待する出力結果の終了を表すと見なされるからです。もし期待する
  出力結果の内容に空白行が入っている場合には、空白行が入るべき場所すべ
  てに "<BLANKLINE>" を入れてください。

* 全てのタブ文字は 8 カラムのタブ位置でスペースに展開されます。テスト
  対象のコードが作成した出力にあるタブは変更されません。出力例にあるど
  んなタブも展開 *される* ので、コードの出力がハードタブを含んでいた場
  合、 doctest が通るには "NORMALIZE_WHITESPACE" オプションか
  directive を有効にするしかありません。そうする代わりに、テストが出力
  を読み取りテストの一部として期待される値と正しく比較するように、テス
  トを書き直すこともできます。このソース中のタブの扱いは試行錯誤の結果
  であり、タブの扱いの中で最も問題の起きにくいものだということが分かっ
  ています。タブの扱いについては、独自の "DocTestParser" クラスを実装
  して、別のアルゴリズムを使うこともできます。

* 標準出力への出力は取り込まれますが、標準エラーは取り込まれません (例
  外発生時のトレースバックは別の方法で取り込まれます)。

* 対話セッションにおいて、バックスラッシュを用いて次の行に続ける場合や
  、その他の理由でバックスラッシュを用いる場合、raw docstring を使って
  バックスラッシュを入力どおりに扱わせるようにしなければなりません:

     >>> def f(x):
     ...     r'''Backslashes in a raw docstring: m\n'''
     >>> print(f.__doc__)
     Backslashes in a raw docstring: m\n

  そうしない場合は、バックスラッシュは文字列の一部として解釈されます。
  例えば、上の "\n" は改行文字として解釈されてしまいます。それ以外の方
  法では、doctest にあるバックスラッシュを二重にする (そして raw
  string を使わない) という方法もあります:

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

  期待する出力結果の先頭部にある空白文字列は、実行例の開始部分にあたる
  "'>>> '" 行の先頭にある空白文字列と同じだけ取り除かれます。


実行コンテキストとは何か?
-------------------------

デフォルトでは、 "doctest" はテストを行うべき docstring を見つけるたび
に "M" のグローバル名前空間の *浅いコピー* を使い、テストの実行によっ
てモジュールの実際のグローバル名前空間を変更しないようにし、かつ "M"
内で行ったテストが痕跡を残して偶発的に別のテストを誤って動作させないよ
うにしています。したがって、実行例中では "M" 内のトップレベルで定義さ
れたすべての名前と、 docstring が動作する以前に定義された名前を自由に
使えます。個々の実行例は他の docstring 中で定義された名前を参照できま
せん。

"testmod()" や "testfile()" に "globs=your_dict" を渡し、自前の辞書を
実行コンテキストとして使うこともできます。


例外はどう扱えばよいか?
-----------------------

トレースバックが実行例によって生成される唯一の出力なら問題ありません。
単にトレースバックを貼り付けてください。[1] トレースバックには、頻繁に
変更されがちな情報 (例えばファイルパスや行番号など) が入っているものな
ので、これは受け入れるテスト結果に柔軟性を持たせようと doctest が苦労
している部分の一つです。

簡単な例を示しましょう:

   >>> [1, 2, 3].remove(42)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ValueError: list.remove(x): x not in list

この doctest は、 "ValueError" が送出され、その詳細情報が
"list.remove(x): x not in list" である場合に成功します。

例外が発生したときの期待する出力はトレースバックヘッダから始まっていな
ければなりません。トレースバックの形式は以下の二通りの行のいずれかで、
実行例の最初の行と同じインデントでなければりません:

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

トレースバックヘッダの後ろにトレースバックスタックが続いてもかまいませ
んが、doctest はその内容を無視します。普通はトレースバックスタックを省
略するか、対話セッションからそのままコピーしてきます。

トレースバックスタックの後ろにはもっとも有意義な部分、例外の型と詳細情
報の入った行があります。これは通常トレースバックの最後の行ですが、例外
が複数行の詳細情報を持っている場合、複数の行にわたることもあります:

   >>> raise ValueError('multi\n    line\ndetail')
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ValueError: multi
       line
   detail

上の例では、最後の 3 行 ("ValueError" から始まる行) における例外の型と
詳細情報だけが比較され、それ以外の部分は無視されます。

例外を扱うコツは、実行例をドキュメントとして読む上で明らかに価値のある
情報でない限り、トレースバックスタックは省略する、ということです。した
がって、先ほどの例は以下のように書くべきでしょう:

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

トレースバックの扱いは非常に特殊なので注意してください。特に、上の書き
直した実行例では、 "..." の扱いは doctest の "ELLIPSIS" オプションとは
独立しています。この例での省略記号は何かの省略を表しているかもしれませ
んし、コンマや数字が 3 個 (または 300 個) かもしれませんし、 Monty
Python のスキットをインデントして書き写したものかもしれません。

以下の詳細はずっと覚えておく必要はないのですが、一度目を通しておいてく
ださい:

* doctest は期待する出力の出所が print 文なのか例外なのかを推測できま
  せん。したがって、例えば期待する出力が "ValueError: 42 is prime" で
  あるような実行例は、 "ValueError" が実際に送出された場合と、万が一期
  待する出力と同じ文字列を print した場合の両方で成功してしまいます。
  現実的には、通常の出力がトレースバックヘッダから始まることはないので
  、実際に問題になることはないでしょう。

* トレースバックスタック (がある場合) の各行は、実行例の最初の行よりも
  深くインデントされているか、*または* 英数文字以外で始まっていなけれ
  ばなりません。トレースバックヘッダ以後に現れる行のうち、インデントが
  等しく英数文字で始まる最初の行は例外の詳細情報が書かれた行とみなされ
  るからです。もちろん、本物のトレースバックでは正しく動作します。

* doctest のオプション "IGNORE_EXCEPTION_DETAIL" を指定した場合、最も
  左端のコロン以後の全ての内容と、例外名の中の全てのモジュール情報が無
  視されます。

* 対話シェルでは、 "SyntaxError" の場合にトレースバックヘッダが省略さ
  れることがあります。しかし doctest にとっては、例外を例外でないもの
  と区別するためにトレースバックヘッダが必要です。そこで、トレースバッ
  クヘッダを省略するような "SyntaxError" をテストする必要があるという
  ごく稀なケースでは、実行例にトレースバックヘッダを手作業で追加する必
  要があるでしょう。

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

  例外の型と詳細情報の前にエラー位置を示す行がくるため、doctest はこの
  行を調べません。例えば、以下の例では、間違った場所に "^" マーカを入
  れても成功してしまいます:

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


オプションフラグ
----------------

doctest の振る舞いは、数多くのオプションフラグによって様々な側面から制
御されています。フラグのシンボル名はモジュールの定数として提供され、
ビット単位論理和 でつないで様々な関数に渡すことができます。シンボル名
は doctest directives でも使用でき、doctest コマンドラインインターフェ
ースに "-o" を通して与えることができます。

バージョン 3.4 で追加: The "-o" command line option.

最初に説明するオプション群は、テストのセマンティクスを決めます。すなわ
ち、実際にテストを実行したときの出力と実行例中の期待する出力とが一致し
ているかどうかを doctest がどのように判断するかを制御します:

doctest.DONT_ACCEPT_TRUE_FOR_1

   デフォルトでは、期待する出力ブロックに単に "1" だけが入っており、実
   際の出力ブロックに "1" または "True" だけが入っていた場合、これらの
   出力は一致しているとみなされます。 "0" と "False" の場合も同様です
   。 "DONT_ACCEPT_TRUE_FOR_1" を指定すると、こうした値の読み替えを行
   いません。デフォルトの挙動で読み替えを行うのは、最近の Python で多
   くの関数の戻り値型が整数型からブール型に変更されたことに対応するた
   めです; 読み替えを行う場合、"通常の整数" の出力を期待する出力とする
   ような doctest も動作します。このオプションはそのうちなくなるでしょ
   うが、ここ数年はそのままでしょう。

doctest.DONT_ACCEPT_BLANKLINE

   デフォルトでは、期待する出力ブロックに "<BLANKLINE>" だけの入った行
   がある場合、その行は実際の出力における空行に一致するようになります
   。完全な空行を入れてしまうと期待する出力がそこで終わっているとみな
   されてしまうため、期待する出力に空行を入れたい場合にはこの方法を使
   わなければなりません。 "DONT_ACCEPT_BLANKLINE" を指定すると、
   "<BLANKLINE>" の読み替えを行わなくなります。

doctest.NORMALIZE_WHITESPACE

   このフラグを指定すると、連続する空白 (空白と改行文字) は互いに等価
   であるとみなします。期待する出力における任意の空白列は実際の出力に
   おける任意の空白と一致します。デフォルトでは、空白は厳密に一致しな
   ければなりません。 "NORMALIZE_WHITESPACE" は、期待する出力の内容が
   非常に長いために、ソースコード中でその内容を複数行に折り返して書き
   たい場合に特に便利です。

doctest.ELLIPSIS

   このフラグを指定すると、期待する出力中の省略記号マーカ ("...") が実
   際の出力中の任意の部分文字列と一致するようになります。部分文字列は
   行境界にわたるものや空文字列を含みます。したがって、このフラグを使
   うのは単純な内容を対象にする場合にとどめましょう。複雑な使い方をす
   ると、正規表現に ".*" を使ったときのように "しまった、マッチしすぎ
   た！ (match 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 で変更: "doctest" モジュールの
   "IGNORE_EXCEPTION_DETAIL" フラグが、 テストされている例外を含むモジ
   ュールの名前を無視するようになりました。

doctest.SKIP

   このフラグを指定すると、実行例は一切実行されません。こうした機能は
   doctest の実行例がドキュメントとテストを兼ねていて、ドキュメントの
   ためには含めておかなければならないけれどチェックされなくても良い、
   というような文脈で役に立ちます。例えば、実行例の出力がランダムであ
   るとか、テストドライバーには利用できないリソースに依存している場合
   などです。

   SKIP フラグは一時的に実行例を"コメントアウト"するのにも使えます。

doctest.COMPARISON_FLAGS

   上記の比較フラグすべての論理和をとったビットマスクです。

二つ目のオプション群は、テストの失敗を報告する方法を制御します:

doctest.REPORT_UDIFF

   このオプションを指定すると、期待する出力および実際の出力が複数行に
   なるときにテストの失敗結果を unified diff 形式を使って表示します。

doctest.REPORT_CDIFF

   このオプションを指定すると、期待する出力および実際の出力が複数行に
   なるときにテストの失敗結果を context diff 形式を使って表示します。

doctest.REPORT_NDIFF

   このオプションを指定すると、期待する出力と実際の出力との間の差分を
   "difflib.Differ" を使って算出します。使われているアルゴリズムは有名
   な "ndiff.py" ユーティリティと同じです。これは、行単位の差分と同じ
   ように行内の差分にマーカをつけられるようにする唯一の手段です。例え
   ば、期待する出力のある行に数字の "1" が入っていて、実際の出力には
   "l" が入っている場合、不一致の起きているカラム位置を示すキャレット
   の入った行が一行挿入されます。

doctest.REPORT_ONLY_FIRST_FAILURE

   このオプションを指定すると、各 doctest で最初にエラーの起きた実行例
   だけを表示し、それ以後の実行例の出力を抑制します。これにより、正し
   く書かれた実行例が、それ以前の実行例の失敗によっておかしくなってし
   まった場合に、 doctest がそれを報告しないようになります。とはいえ、
   最初に失敗を引き起こした実行例とは関係なく誤って書かれた実行例の報
   告も抑制してしまいます。 "REPORT_ONLY_FIRST_FAILURE" を指定した場合
   、実行例がどこかで失敗しても、それ以後の実行例を続けて実行し、失敗
   したテストの総数を報告します; 出力が抑制されるだけです。

doctest.FAIL_FAST

   このオプションを指定すると、最初に実行例が失敗した時点で終了し、残
   りの実行例を実行しません。つまり、報告される失敗の数はたかだか 1 つ
   になります。最初の失敗より後の例はデバッグ出力を生成しないため、こ
   のフラグはデバッグの際に有用でしょう。

   The doctest command line accepts the option "-f" as a shorthand for
   "-o FAIL_FAST".

   バージョン 3.4 で追加.

doctest.REPORTING_FLAGS

   上記のエラー報告に関するフラグすべての論理和をとったビットマスクで
   す。

サブクラス化で "doctest" 内部を拡張するつもりがなければ役に立ちません
が、別の新しいオプションフラグ名を登録する方法もあります:

doctest.register_optionflag(name)

   名前 *name* の新たなオプションフラグを作成し、作成されたフラグの整
   数値を返します。 "register_optionflag()" は "OutputChecker" や
   "DocTestRunner" をサブクラス化して、その中で新たに作成したオプショ
   ンをサポートさせる際に使います。 "register_optionflag()" は以下のよ
   うな定形文で呼び出さなければなりません:

      MY_FLAG = register_optionflag('MY_FLAG')


ディレクティブ (Directives)
---------------------------

doctest ディレクティブは個々の実行例の オプションフラグ を操作するため
に使われます。 doctest ディレクティブは後のソースコード例にあるような
特殊な 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" | ...

"+" や "-" とディレクティブオプション名の間に空白を入れてはなりません
。ディレクティブオプション名は上で説明したオプションフラグ名のいずれか
です。

ある実行例の doctest ディレクティブは、その実行例だけの doctest の振る
舞いを変えます。ある特定の挙動を有効にしたければ "+" を、無効にしたけ
れば "-" を使います。

例えば、以下のテストは成功します:

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

ディレクティブがない場合、実際の出力には一桁の数字の間に二つスペースが
入っていないこと、実際の出力は 1 行になることから、テストは成功しない
はずです。別のディレクティブを使って、このテストを成功させることもでき
ます:

   >>> print(list(range(20)))  # doctest: +ELLIPSIS
   [0, 1, ..., 18, 19]

複数のディレクティブは、一つの物理行の中にコンマで区切って指定できます
:

   >>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
   [0,    1, ...,   18,    19]

一つの実行例中で複数のディレクティブコメントを使った場合、それらは組み
合わされます:

   >>> print(list(range(20)))  # doctest: +ELLIPSIS
   ...                         # doctest: +NORMALIZE_WHITESPACE
   [0,    1, ...,   18,    19]

この実行例で分かるように、実行例にはディレクティブだけを含む "..." 行
を追加することができます。この書きかたは、実行例が長すぎるためにディレ
クティブを同じ行に入れると収まりが悪い場合に便利です:

   >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
   ... # doctest: +ELLIPSIS
   [0, ..., 4, 10, ..., 19, 30, ..., 39]

フォルトではすべてのオプションが無効になっており、ディレクティブは特定
の実行例だけに影響を及ぼすので、通常意味があるのは有効にするためのオプ
ション ("+" のついたディレクティブ) だけです。とはいえ、doctest を実行
する関数はオプションフラグを指定してデフォルトとは異なった挙動を実現で
きるので、そのような場合には "-" を使った無効化オプションも意味を持ち
ます。


警告
----

"doctest" では、期待する出力に対する完全一致を厳格に求めます。 一致し
ない文字が一文字でもあると、テストは失敗してしまいます。 このため、
Python が出力に関して何を保証していて、何を保証していないかを正確に知
っていないと混乱させられることがあるでしょう。 例えば、集合を出力する
際、 Python は要素がある特定の順番で並ぶよう保証してはいません。したが
って、以下のようなテスト

   >>> foo()
   {"Hermione", "Harry"}

は失敗するかもしれないのです! 回避するには

   >>> foo() == {"Hermione", "Harry"}
   True

とするのが一つのやり方です。別のやり方は

   >>> d = sorted(foo())
   >>> d
   ['Harry', 'Hermione']

他のやり方もありますが、あとは自分で考えてみてください。

以下のように、オブジェクトアドレスを埋め込むような結果を print するの
もよくありません :

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

"ELLIPSIS" ディレクティブを使うと、上のような例をうまく解決できます:

   >>> C()  # doctest: +ELLIPSIS
   <C object at 0x...>

浮動小数点数もまた、プラットフォーム間での微妙な出力の違いの原因となり
ます。というのも、Python は浮動小数点の書式化をプラットフォームの C ラ
イブラリに委ねており、この点では、C ライブラリはプラットフォーム間で非
常に大きく異なっているからです。

   >>> 1./7  # risky
   0.14285714285714285
   >>> print(1./7) # safer
   0.142857142857
   >>> print(round(1./7, 6)) # much safer
   0.142857

"I/2.**J" の形式になる数値はどのプラットフォームでもうまく動作するので
、私はこの形式の数値を生成するように doctest の実行例を工夫しています:

   >>> 3./4  # utterly safe
   0.75

単純な分数は人間にとっても理解しやすく、良いドキュメントを書くために役
に立ちます。


基本 API
========

数 "testmod()" と "testfile()" は、ほとんどの基本的な用途に十分な
doctest インターフェースを提供しています。これら二つの関数についてあま
り形式的でない入門が読みたければ、 簡単な利用法: docstring 中の実行例
をチェックする 節や 簡単な利用法: テキストファイル中の実行例をチェック
する 節を参照してください。

doctest.testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None)

   *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* の方
   の値が入ります。デフォルト、または "None" であるとき、追加のグロー
   バル変数は使われません。この仕様は、パラメータ付きで doctest を実行
   するという、やや進んだ機能です。例えば、一般的な名前を使って基底ク
   ラス向けに doctest を書いておき、その後で辞書で一般的な名前からテス
   トしたいサブクラスへの対応付けを行う辞書を *extraglobs* に渡して、
   様々なサブクラスをテストできます。

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

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

   オプション引数 *optionflags* (デフォルト値 0) は、各オプションフラ
   グの ビット単位論理和 を取ります。 オプションフラグ 節を参照してく
   ださい。

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

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

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

doctest.testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)

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

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

   Also test examples reachable from dict "m.__test__", if it exists.
   "m.__test__" maps names (strings) to functions, classes and
   strings; function and class docstrings are searched for examples;
   strings are searched directly, as if they were docstrings.

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

   "(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__" になりま
   す。

doctest.run_docstring_examples(f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0)

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

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

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

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

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

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


単体テスト API
==============

doctest が付けられたモジュールが大きくなるにつれ、全ての doctest を組
織的に実行したくなるでしょう。 "doctest" モジュールは 2 つの関数を提供
していて、 "unittest" のテストスイートを作り、 doctest を含んだテキス
トファイルを作成するのに使えます。 "unittest" のテストディスカバリと組
み合わせるには、テストモジュールに load_tests 関数を書いておいてくださ
い:

   import unittest
   import doctest
   import my_module_with_doctests

   def load_tests(loader, tests, ignore):
       tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
       return tests

doctest の入ったテキストファイルやモジュールから "unittest.TestSuite"
インスタンスを生成するための主な関数は二つあります:

doctest.DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)

   単一または複数のテキストファイルに入っている doctest 形式のテストを
   、 "unittest.TestSuite" インスタンスに変換します。

   The returned "unittest.TestSuite" is to be run by the unittest
   framework and runs the interactive examples in each file.  If an
   example in any file fails, then the synthesized unit test fails,
   and a "failureException" exception is raised showing the name of
   the file containing the test and a (sometimes approximate) line
   number.

   関数には、テストを行いたい一つまたは複数のファイルへのパスを (文字
   列で) 渡します。

   "DocFileSuite()" には、キーワード引数でオプションを指定できます:

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

   * *module_relative* が "True" (デフォルト) の場合、*paths* 中のファ
     イル名は OS に依存しないモジュールの相対パスになります。デフォル
     トでは、このパスは呼び出し元のモジュールのディレクトリからの相対
     パスになります; ただし、*package* 引数を指定した場合には、パッケ
     ージからの相対になります。OS への依存性を除くため、各ファイル名は
     パスを分割するのに "/" 文字を使わなければならず、絶対パスにしては
     なりません (パス文字列を "/" で始めてはなりません)。

   * *module_relative* が "False" の場合、*filename* は OS 依存のパス
     を示します。パスは絶対パスでも相対パスでもかまいません; 相対パス
     にした場合、現在の作業ディレクトリを基準に解決します。

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

   オプション引数 *setUp* には、テストスイートのセットアップに使う関数
   を指定します。この関数は、各ファイルのテストを実行する前に呼び出さ
   れます。 *setUp* 関数は "DocTest" オブジェクトに引き渡されます。
   *setUp* は *globs* 属性を介してテストのグローバル変数にアクセスでき
   ます。

   オプション引数 *tearDown* には、テストを解体 (tear-down) するための
   関数を指定します。この関数は、各ファイルのテストの実行を終了するた
   びに呼び出されます。 *tearDown* 関数は "DocTest"  オブジェクトに引
   き渡されます。 *tearDown* は *globs* 属性を介してテストのグローバル
   変数にアクセスできます。

   オプション引数 *globs* は辞書で、テストのグローバル変数の初期値が入
   ります。この辞書は各テストごとに新たにコピーして使われます。デフォ
   ルトでは *globs* は空の新たな辞書です。

   オプション引数 *optionflags* には、テストを実行する際にデフォルトで
   適用される doctest オプションを OR で結合して指定します。 オプショ
   ンフラグ 節を参照してください。結果レポートに関するオプションを指定
   するより適切な方法は下記の "set_unittest_reportflags()" の説明を参
   照してください。

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

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

   "DocFileSuite()" を使用してテキストファイルからロードされた
   doctests に提供される globals に、グローバル変数 "__file__" が追加
   されます。

doctest.DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, checker=None)

   doctest のテストを "unittest.TestSuite" に変換します。

   The returned "unittest.TestSuite" is to be run by the unittest
   framework and runs each doctest in the module.  If any of the
   doctests fail, then the synthesized unit test fails, and a
   "failureException" exception is raised showing the name of the file
   containing the test and a (sometimes approximate) line number.

   オプション引数 *module* には、テストしたいモジュールの名前を指定し
   ます。*module* にはモジュールオブジェクトまたは (ドット表記の) モジ
   ュール名を指定できます。*module* を指定しない場合、この関数を呼び出
   しているモジュールになります。

   オプション引数 *globs* は辞書で、テストのグローバル変数の初期値が入
   ります。この辞書は各テストごとに新たにコピーして使われます。デフォ
   ルトでは *globs* は空の新たな辞書です。

   オプション引数 *extraglobs* には追加のグローバル変数セットを指定し
   ます。この変数セットは *globs* に統合されます。デフォルトでは、追加
   のグローバル変数はありません。

   オプション引数 *test_finder* は、モジュールから doctest を抽出する
   ための "DocTestFinder" オブジェクト (またはその代替となるオブジェク
   ト) です。

   オプション引数 *setUp* 、 *tearDown* 、および *optionflags* は上の
   "DocFileSuite()" と同じです。

   この関数は "testmod()" と同じ検索方法を使います。

   バージョン 3.5 で変更: *module* がドキュメンテーション文字列を含ま
   ない場合には、 "DocTestSuite()" は "ValueError" を送出するのではな
   く空の  "unittest.TestSuite" を返します。

exception doctest.failureException

   When doctests which have been converted to unit tests by
   "DocFileSuite()" or "DocTestSuite()" fail, this exception is raised
   showing the name of the file containing the test and a (sometimes
   approximate) line number.

Under the covers, "DocTestSuite()" creates a "unittest.TestSuite" out
of "doctest.DocTestCase" instances, and "DocTestCase" is a subclass of
"unittest.TestCase". "DocTestCase" isn't documented here (it's an
internal detail), but studying its code can answer questions about the
exact details of "unittest" integration.

Similarly, "DocFileSuite()" creates a "unittest.TestSuite" out of
"doctest.DocFileCase" instances, and "DocFileCase" is a subclass of
"DocTestCase".

So both ways of creating a "unittest.TestSuite" run instances of
"DocTestCase".  This is important for a subtle reason: when you run
"doctest" functions yourself, you can control the "doctest" options in
use directly, by passing option flags to "doctest" functions.
However, if you're writing a "unittest" framework, "unittest"
ultimately controls when and how tests get run.  The framework author
typically wants to control "doctest" reporting options (perhaps, e.g.,
specified by command line options), but there's no way to pass options
through "unittest" to "doctest" test runners.

このため、 "doctest" では、以下の関数を使って、 "unittest" サポートに
特化したレポートフラグ表記方法もサポートしています:

doctest.set_unittest_reportflags(flags)

   "doctest" のレポートフラグをセットします。

   引数 *flags* はオプションフラグの ビット単位論理和 を取ります。 オ
   プションフラグ 節を参照してください。「レポートフラグ」しか使えませ
   ん。

   This is a module-global setting, and affects all future doctests
   run by module "unittest":  the "runTest()" method of "DocTestCase"
   looks at the option flags specified for the test case when the
   "DocTestCase" instance was constructed.  If no reporting flags were
   specified (which is the typical and expected case), "doctest"'s
   "unittest" reporting flags are bitwise ORed into the option flags,
   and the option flags so augmented are passed to the "DocTestRunner"
   instance created to run the doctest.  If any reporting flags were
   specified when the "DocTestCase" instance was constructed,
   "doctest"'s "unittest" reporting flags are ignored.

   この関数は、関数を呼び出す前に有効になっていた "unittest" レポート
   フラグの値を返します。


拡張 API
========

基本 API は、doctest を使いやすくするための簡単なラッパであり、柔軟性
があってほとんどのユーザの必要を満たしています; とはいえ、もっとテスト
をきめ細かに制御したい場合や、doctest の機能を拡張したい場合、拡張 API
(advanced API) を使わなければなりません。

拡張 API は、doctest ケースから抽出した対話モードでの実行例を記憶する
ための二つのコンテナクラスを中心に構成されています:

* "Example": 1つの Python *文* と、その期待する出力をペアにしたもの。

* "DocTest": "Example" の集まり。通常一つの docstring やテキストファイ
  ルから抽出されます。

その他に、doctest の実行例を検索、構文解析、実行、チェックするための処
理クラスが以下のように定義されています:

* "DocTestFinder": 与えられたモジュールからすべての docstring を検索し
  、 "DocTestParser" を使って対話モードでの実行例が入ったすべての
  docstring から "DocTest" を生成します。

* "DocTestParser": (オブジェクトの docstring 等の) 文字列から
  "DocTest" オブジェクトを生成します。

* "DocTestRunner": "DocTest" 内の実行例を実行し、 "OutputChecker" を使
  って出力を検証します。

* "OutputChecker": doctest 実行例から実際に出力された結果を期待する出
  力と比較し、両者が一致するか判別します。

これらの処理クラスの関係を図にまとめると、以下のようになります:

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


DocTest オブジェクト
--------------------

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

   単一の名前空間内で実行される doctest 実行例の集まりです。コンストラ
   クタの引数は "DocTest" インスタンス中の同名の属性の初期化に使われま
   す。

   "DocTest" では、以下の属性を定義しています。これらの変数はコンスト
   ラクタで初期化されます。直接変更してはなりません。

   examples

      対話モードにおける実行例それぞれをエンコードしていて、テストで実
      行される、 "Example" オブジェクトからなるリストです。

   globs

      実行例を実行する名前空間 (いわゆるグローバル変数) です。このメン
      バは、名前から値への対応付けを行っている辞書です。実行例が名前空
      間に対して (新たな変数を束縛するなど) 何らかの変更を行った場合、
      "globs" への反映はテストの実行後に起こります。

   name

      "DocTest" を識別する名前の文字列です。通常、この値はテストを取り
      出したオブジェクトかファイルの名前になります。

   filename

      "DocTest" を取り出したファイルの名前です; ファイル名が未知の場合
      や "DocTest" をファイルから取り出したのでない場合には "None" に
      なります。

   lineno

      "filename" 中で "DocTest" のテスト実行例が始まっている行の行番号
      で、行番号が利用できなければ "None" です。行番号は、ファイルの先
      頭を 0 として数えます。

   docstring

      テストを取り出した docstring 自体を現す文字列です。docstring 文
      字列を得られない場合や、文字列からテスト実行例を取り出したのでな
      い場合には "None" になります。


Example オブジェクト
--------------------

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

   ひとつの Python 文と、それに対する期待する出力からなる、単一の対話
   的モードの実行例です。コンストラクタの引数は "Example" インスタンス
   中の同名の属性の初期化に使われます。

   "Example" では、以下の属性を定義しています。これらの変数はコンスト
   ラクタで初期化されます。直接変更してはなりません。

   source

      実行例のソースコードが入った文字列です。ソースコードは単一の
      Python で、末尾は常に改行です。コンストラクタは必要に応じて改行
      を追加します。

   want

      実行例のソースコードを実行した際の期待する出力 (標準出力と、例外
      が生じた場合にはトレースバック) です。 "want" の末尾は、期待する
      出力がまったくない場合を除いて常に改行になります。期待する出力が
      ない場合には空文字列になります。コンストラクタは必要に応じて改行
      を追加します。

   exc_msg

      実行例が例外を生成すると期待される場合の例外メッセージです。例外
      を送出しない場合には "None" です。この例外メッセージは、
      "traceback.format_exception_only()" の戻り値と比較されます。値が
      "None" でない限り、 "exc_msg" は改行で終わっていなければなりませ
      ん; コンストラクタは必要に応じて改行を追加します。

   lineno

      この実行例を含む文字列における実行例が始まる行番号です。行番号は
      文字列の先頭を 0 として数えます。

   indent

      実行例の入っている文字列のインデント、すなわち実行例の最初のプロ
      ンプトより前にある空白文字の数です。

   options

      A dictionary mapping from option flags to "True" or "False",
      which is used to override default options for this example.  Any
      option flags not contained in this dictionary are left at their
      default value (as specified by the "DocTestRunner"'s
      optionflags). By default, no options are set.


DocTestFinder オブジェクト
--------------------------

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

   与えられたオブジェクトについて、そのオブジェクト自身の docstring か
   、そのオブジェクトに含まれるオブジェクトの docstring から "DocTest"
   を抽出する処理クラスです。モジュール、クラス、関数、メソッド、静的
   メソッド、クラスメソッド、プロパティから "DocTest" を抽出できます。

   オプション引数 *verbose* を使うと、抽出処理の対象となるオブジェクト
   を表示できます。デフォルトは "False" (出力を行わない) です。

   オプション引数 *parser* には、 docstring から "DocTest" を抽出する
   のに使う "DocTestParser" オブジェクト (またはその代替となるオブジェ
   クト) を指定します。

   オプション引数 *recurse* が偽の場合、 "DocTestFinder.find()" は与え
   られたオブジェクトだけを調べ、そのオブジェクトに含まれる他のオブジ
   ェクトを調べません。

   オプション引数 *exclude_empty* が偽の場合、 "DocTestFinder.find()"
   は空の docstring を持つオブジェクトもテスト対象に含めます。

   "DocTestFinder" では以下のメソッドを定義しています:

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

      *obj* または *obj* 内に入っているオブジェクトの docstring 中で定
      義されている "DocTest" のリストを返します。

      オプション引数 *name* には、オブジェクトの名前を指定します。この
      名前は、関数が返す "DocTest" の名前になります。 *name* を指定し
      ない場合、 "obj.__name__" を使います。

      オプションのパラメータ *module* は、指定したオブジェクトを収めて
      いるモジュールを指定します。 *module* を指定しないか、"None" を
      指定した場合には、正しいモジュールを自動的に決定しようと試みます
      。 オブジェクトのモジュールは以下のような役割を果たします:

      * *globs* を指定していない場合、オブジェクトのモジュールはデフォ
        ルトの名前空間になります。

      * 他のモジュールから import されたオブジェクトに対して
        "DocTestFinder" が "DocTest" を抽出するのを避けるために使いま
        す。 (*module* 由来でないオブジェクトを無視します。)

      * オブジェクトの入っているファイル名を調べるために使います。

      * オブジェクトがファイル内の何行目にあるかを調べる手助けにします
        。

      *module* が "False" の場合には、モジュールの検索を試みません。こ
      れは正確さを欠くような使い方で、通常 doctest 自体のテストにしか
      使いません。*module* が "False" の場合、または *module* が
      "None" で自動的に的確なモジュールを見つけ出せない場合には、すべ
      てのオブジェクトは "(non-existent)" モジュールに属するとみなされ
      、そのオブジェクト内のすべてのオブジェクトに対して (再帰的に)
      doctest の検索を行います。

      各 "DocTest" のグローバル変数は、 *globs* と *extraglobs* を合わ
      せたもの (*extraglobs* 内の束縛が *globs* 内の束縛を上書きする)
      になります。各々の "DocTest" に対して、グローバル変数を表す辞書
      の新たな浅いコピーを生成します。 *globs* を指定しない場合に使わ
      れるのデフォルト値は、モジュールを指定していればそのモジュールの
      *__dict__* になり、指定していなければ "{}" になります。
      *extraglobs* を指定しない場合、デフォルトの値は "{}" になります
      。


DocTestParser オブジェクト
--------------------------

class doctest.DocTestParser

   対話モードの実行例を文字列から抽出し、それを使って "DocTest" オブジ
   ェクトを生成するために使われる処理クラスです。

   "DocTestParser" では以下のメソッドを定義しています:

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

      指定した文字列からすべての doctest 実行例を抽出し、 "DocTest" オ
      ブジェクト内に集めます。

      *globs*, *name*, *filename*, および *lineno* は新たに作成される
      "DocTest" オブジェクトの属性になります。詳しくは "DocTest" のド
      キュメントを参照してください。

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

      指定した文字列からすべての doctest 実行例を抽出し、 "Example" オ
      ブジェクトからなるリストにして返します。各 "Example" の行番号は
      0 から数えます。オプション引数 *name* はこの文字列につける名前で
      、エラーメッセージにしか使われません。

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

      指定した文字列を、実行例とその間のテキストに分割し、実行例を
      "Example" オブジェクトに変換し、 "Example" と文字列からなるリス
      トにして返します。各 "Example" の行番号は 0から数えます。オプシ
      ョン引数 *name* はこの文字列につける名前で、エラーメッセージにし
      か使われません。


DocTestRunner オブジェクト
--------------------------

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

   "DocTest" 内の対話モード実行例を実行し、検証する際に用いられる処理
   クラスです。

   期待する出力と実際の出力との比較は "OutputChecker" で行います。比較
   は様々なオプションフラグを使ってカスタマイズできます; 詳しくは オプ
   ションフラグ を参照してください。オプションフラグでは不十分な場合、
   コンストラクタに "OutputChecker" のサブクラスを渡して比較方法をカス
   タマイズできます。

   The test runner's display output can be controlled in two ways.
   First, an output function can be passed to "TestRunner.run()"; this
   function will be called with strings that should be displayed.  It
   defaults to "sys.stdout.write".  If capturing the output is not
   sufficient, then the display output can be also customized by
   subclassing DocTestRunner, and overriding the methods
   "report_start()", "report_success()",
   "report_unexpected_exception()", and "report_failure()".

   オプションのキーワード引数 *checker* には、 "OutputChecker" オブジ
   ェクト (またはその代替となるオブジェクト) を指定します。このオブジ
   ェクトは doctest 実行例の期待する出力と実際の出力との比較を行う際に
   使われます。

   オプションのキーワード引数 *verbose* は、 "DocTestRunner" の出すメ
   ッセージの冗長性を制御します。 *verbose* が "True" の場合、各実行例
   を実行する都度、その実行例についての情報を出力します。 *verbose* が
   "False" の場合、テストの失敗だけを出力します。 *verbose* を指定しな
   い場合や "None" を指定した場合、コマンドラインスイッチ "-v" を使っ
   た場合にのみ *verbose* 出力を適用します。

   オプションのキーワード引数 *optionflags* を使うと、テストランナーが
   期待される出力と実際の出力を比較する方法や、テストの失敗を表示する
   方法を制御できます。詳しくは オプションフラグ 節を参照してください
   。

   "DocTestRunner" defines the following methods:

   report_start(out, test, example)

      テストランナーが実行例を処理しようとしているときにレポートを出力
      します。 "DocTestRunner" の出力をサブクラスでカスタマイズできる
      ようにするためのメソッドです。直接呼び出してはなりません。

      *example* は処理する実行例です。 *test* は *example* の入ってい
      るテストです。 *out* は出力用の関数で、 "DocTestRunner.run()" に
      渡されます。

   report_success(out, test, example, got)

      与えられた実行例が正しく動作したことを報告します。このメソッドは
      "DocTestRunner" のサブクラスで出力をカスタマイズできるようにする
      ために提供されています; 直接呼び出してはなりません。

      *example* は処理する実行例です。 *got* は実行例から実際に得られ
      た出力です。 *test* は *example* の入っているテストです。 *out*
      は出力用の関数で、 "DocTestRunner.run()" に渡されます。

   report_failure(out, test, example, got)

      与えられた実行例が正しく動作しなかったことを報告します。このメソ
      ッドは "DocTestRunner" のサブクラスで出力をカスタマイズできるよ
      うにするために提供されています; 直接呼び出してはなりません。

      *example* は処理する実行例です。 *got* は実行例から実際に得られ
      た出力です。 *test* は *example* の入っているテストです。 *out*
      は出力用の関数で、 "DocTestRunner.run()" に渡されます。

   report_unexpected_exception(out, test, example, exc_info)

      与えられた実行例が期待とは違う例外を送出したことを報告します。こ
      のメソッドは "DocTestRunner" のサブクラスで出力をカスタマイズで
      きるようにするために提供されています; 直接呼び出してはなりません
      。

      *example* は処理する実行例です。 *exc_info* には予期せず送出され
      た例外の情報を入れたタプル ("sys.exc_info()" の返す内容) になり
      ます。 *test* は *example* の入っているテストです。 *out* は出力
      用の関数で、 "DocTestRunner.run()" に渡されます。

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

      Run the examples in *test* (a "DocTest" object), and display the
      results using the writer function *out*.

      実行例は名前空間 "test.globs" の下で実行されます。*clear_globs*
      が真 (デフォルト) の場合、名前空間はテストの実行後に消去され、ガ
      ベージコレクションを促します。テストの実行完了後にその内容を調べ
      たければ、*clear_globs=False* としてください。

      *compileflags* には、実行例を実行する際に Python コンパイラに適
      用するフラグセットを指定します。*compileflags* を指定しない場合
      、デフォルト値は *globs* で適用されている future-import フラグセ
      ットになります。

      The output of each example is checked using the
      "DocTestRunner"'s output checker, and the results are formatted
      by the "DocTestRunner.report_*()" methods.

   summarize(verbose=None)

      Print a summary of all the test cases that have been run by this
      DocTestRunner, and return a *named tuple* "TestResults(failed,
      attempted)".

      オプションの *verbose* 引数を使うと、どのくらいサマリを詳しくす
      るかを制御できます。冗長度を指定しない場合、 "DocTestRunner" 自
      体の冗長度を使います。


OutputChecker オブジェクト
--------------------------

class doctest.OutputChecker

   doctest 実行例を実際に実行したときの出力が期待する出力と一致するか
   どうかをチェックするために使われるクラスです。 "OutputChecker" では
   、与えられた二つの出力を比較して、一致する場合には "True" を返す
   "check_output()" と、二つの出力間の違いを説明する文字列を返す
   "output_difference()" の、二つのメソッドがあります。

   "OutputChecker" では以下のメソッドを定義しています:

   check_output(want, got, optionflags)

      実行例から実際に得られた出力 (*got*) と、期待する出力 (*want*)
      が一致する場合にのみ "True" を返します。二つの文字列がまったく同
      一の場合には常に一致するとみなしますが、テストランナーの使ってい
      るオプションフラグにより、厳密には同じ内容になっていなくても一致
      するとみなす場合もあります。オプションフラグについての詳しい情報
      は オプションフラグ 節を参照してください。

   output_difference(example, got, optionflags)

      与えられた実行例 (*example*) の期待する出力と、実際に得られた出
      力 (*got*) の間の差異を解説している文字列を返します。
      *optionflags* は *want* と *got* を比較する際に使われるオプショ
      ンフラグのセットです。


デバッグ
========

"doctest" では、doctest 実行例をデバッグするメカニズムをいくつか提供し
ています:

* doctest を実行可能な Python プログラムに変換し、 Python デバッガ
  "pdb" で実行できるようにするための関数がいくつかあります。

* "DocTestRunner" のサブクラス "DebugRunner" クラスがあります。このク
  ラスは、最初に失敗した実行例に対して例外を送出します。例外には実行例
  に関する情報が入っています。この情報は実行例の検死デバッグに利用でき
  ます。

* "DocTestSuite()" の生成する "unittest" テストケースは、 "debug()" メ
  ソッドをサポートしています。 "debug()" は "unittest.TestCase" で定義
  されています。

* "pdb.set_trace()" を doctest 実行例の中で呼び出しておけば、その行が
  実行されたときに Python デバッガが組み込まれます。デバッガを組み込ん
  だあとは、変数の現在の値などを調べられます。たとえば、以下のようなモ
  ジュールレベルの docstring の入ったファイル "a.py" があるとします:

     """
     >>> def f(x):
     ...     g(x*2)
     >>> def g(x):
     ...     print(x+3)
     ...     import pdb; pdb.set_trace()
     >>> f(3)
     9
     """

  対話セッションは以下のようになるでしょう:

     >>> import a, doctest
     >>> doctest.testmod(a)
     --Return--
     > <doctest a[1]>(3)g()->None
     -> import pdb; pdb.set_trace()
     (Pdb) list
       1     def g(x):
       2         print(x+3)
       3  ->     import pdb; pdb.set_trace()
     [EOF]
     (Pdb) p x
     6
     (Pdb) step
     --Return--
     > <doctest a[0]>(2)f()->None
     -> g(x*2)
     (Pdb) list
       1     def f(x):
       2  ->     g(x*2)
     [EOF]
     (Pdb) p x
     3
     (Pdb) step
     --Return--
     > <doctest a[2]>(1)?()->None
     -> f(3)
     (Pdb) cont
     (0, 3)
     >>>

以下は、doctest を Python コードに変換して、できたコードをデバッガ下で
実行できるようにするための関数です:

doctest.script_from_examples(s)

   実行例の入ったテキストをスクリプトに変換します。

   引数 *s* は doctest 実行例の入った文字列です。この文字列は Python
   スクリプトに変換され、その中では *s* の doctest 実行例が通常のコー
   ドに、それ以外は Python のコメント文になります。生成したスクリプト
   を文字列で返します。例えば、

      import doctest
      print(doctest.script_from_examples(r"""
          Set x and y to 1 and 2.
          >>> x, y = 1, 2

          Print their sum:
          >>> print(x+y)
          3
      """))

   は:

      # Set x and y to 1 and 2.
      x, y = 1, 2
      #
      # Print their sum:
      print(x+y)
      # Expected:
      ## 3

   この関数は内部的に他の関数から使われていますが (下記参照)、対話セッ
   ションを Python スクリプトに変換したいような場合にも便利でしょう。

doctest.testsource(module, name)

   あるオブジェクトの doctest をスクリプトに変換します。

   Argument *module* is a module object, or dotted name of a module,
   containing the object whose doctests are of interest.  Argument
   *name* is the name (within the module) of the object with the
   doctests of interest.  The result is a string, containing the
   object's docstring converted to a Python script, as described for
   "script_from_examples()" above.  For example, if module "a.py"
   contains a top-level function "f()", then

      import a, doctest
      print(doctest.testsource(a, "a.f"))

   prints a script version of function "f()"'s docstring, with
   doctests converted to code, and the rest placed in comments.

doctest.debug(module, name, pm=False)

   オブジェクトの持つ doctest をデバッグします。

   *module* および *name* 引数は上の "testsource()" と同じです。指定し
   たオブジェクトの docstring から合成された Python スクリプトは一時フ
   ァイルに書き出され、その後 Python デバッガ "pdb" の制御下で実行され
   ます。

   ローカルおよびグローバルの実行コンテキストには、"module.__dict__"
   の浅いコピーが使われます。

   オプション引数 *pm* は、検死デバッグを行うかどうかを指定します。
   *pm* が真の場合、スクリプトファイルは直接実行され、スクリプトが送出
   した例外が処理されないまま終了した場合にのみデバッガが立ち入ります
   。その場合、 "pdb.post_mortem()" によって検死デバッグを起動し、処理
   されなかった例外から得られたトレースバックオブジェクトを渡します。
   *pm* を指定しないか値を偽にした場合、 "pdb.run()" に適切な "exec()"
   呼び出しを渡して、最初からデバッガの下でスクリプトを実行します。

doctest.debug_src(src, pm=False, globs=None)

   文字列中の doctest をデバッグします。

   上の "debug()" に似ていますが、doctest の入った文字列は *src* 引数
   で直接指定します。

   オプション引数 *pm* は上の "debug()" と同じ意味です。

   オプション引数 *globs* には、ローカルおよびグローバルな実行コンテキ
   ストの両方に使われる辞書を指定します。*globs* を指定しない場合や
   "None" にした場合、空の辞書を使います。辞書を指定した場合、実際の実
   行コンテキストには浅いコピーが使われます。

"DebugRunner" クラス自体や "DebugRunner" クラスが送出する特殊な例外は
、テストフレームワークの作者にとって非常に興味のあるところですが、ここ
では概要しか述べられません。詳しくはソースコード、とりわけ
"DebugRunner" の docstring (それ自体 doctest です!) を参照してください
:

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

   テストの失敗に遭遇するとすぐに例外を送出するようになっている
   "DocTestRunner" のサブクラスです。予期しない例外が生じると、
   "UnexpectedException" 例外を送出します。この例外には、テスト、実行
   例、もともと送出された例外が入っています。期待する出力と実際の出力
   が一致しないために失敗した場合には、 "DocTestFailure" 例外を送出し
   ます。この例外には、テスト、実行例、実際の出力が入っています。

   コンストラクタのパラメータやメソッドについては、 拡張 API 節の
   "DocTestRunner" のドキュメントを参照してください。

"DebugRunner" インスタンスの送出する例外には以下の二つがあります:

exception doctest.DocTestFailure(test, example, got)

   doctest 実行例の実際の出力が期待する出力と一致しなかったことを示す
   ために "DocTestRunner" が送出する例外です。コンストラクタの引数は、
   インスタンスの同名の属性を初期化するために使われます。

"DocTestFailure" では以下の属性を定義しています:

DocTestFailure.test

   実行例が失敗した時に実行されていた "DocTest" オブジェクトです。

DocTestFailure.example

   失敗した "Example" オブジェクトです。

DocTestFailure.got

   実行例の実際の出力です。

exception doctest.UnexpectedException(test, example, exc_info)

   doctest 実行例が予期しない例外を送出したことを示すために
   "DocTestRunner" が送出する例外です。コンストラクタの引数は、インス
   タンスの同名の属性を初期化するために使われます。

"UnexpectedException" では以下の属性を定義しています:

UnexpectedException.test

   実行例が失敗した時に実行されていた "DocTest" オブジェクトです。

UnexpectedException.example

   失敗した "Example" オブジェクトです。

UnexpectedException.exc_info

   予期しない例外についての情報の入ったタプルで、 "sys.exc_info()" が
   返すのと同じものです。


アドバイス
==========

冒頭でも触れたように、 "doctest" は、以下の三つの主な用途を持つように
なりました:

1. docstring 内の実行例をチェックする。

2. 回帰テストを行う。

3. 実行可能なドキュメント/読めるテストの実現。

これらの用途にはそれぞれ違った要求があるので、区別して考えるのが重要で
す。特に、docstring を曖昧なテストケースに埋もれさせてしまうとドキュメ
ントとしては最悪です。

docstring の例は注意深く作成してください。 doctest の作成にはコツがあ
り、きちんと学ぶ必要があります --- 最初はすんなりできないでしょう。実
行例はドキュメントに本物の価値を与えます。良い例は、たくさんの言葉と同
じ価値を持つことがしばしばあります。注意深くやれば、例はユーザにとって
は非常に有益であり、時を経るにつれて、あるいは状況が変わった際に、何度
も修正するのにかかる時間を節約するという形で、きっと見返りを得るでしょ
う。私は今でも、自分の "doctest" 実行例が "無害な" 変更を行った際にう
まく動作しなくなることに驚いています。

説明テキストの作成をけちらなければ、"doctest" は回帰テストの優れたツー
ルにもなり得ます。説明文と実行例を交互に記述していけば、実際に何をどう
してテストしているのかもっと簡単に把握できるようになるでしょう。もちろ
ん、コードベースのテストに詳しくコメントを入れるのも手ですが、そんなこ
とをするプログラマはほとんどいません。多くの人々が、"doctest" のアプロ
ーチをとった方がきれいにテストを書けると気づいています。おそらく、これ
は単にコード中にコメントを書くのが少し面倒だからという理由でしょう。私
はもう少し穿った見方もしています。doctest ベースのテストを書くときの自
然な態度は、自分のソフトウェアのよい点を説明しようとして、実行例を使っ
て説明しようとするときの態度そのものだからだ、という理由です。それゆえ
に、テストファイルは自然と単純な機能の解説から始め、論理的により複雑で
境界条件的なケースに進むような形になります。結果的に、一見ランダムに見
えるような個別の機能をテストしている個別の関数の集まりではなく、首尾一
貫した説明ができるようになるのです。"doctest" によるテストの作成はまっ
たく別の取り組み方であり、テストと説明の区別をなくして、まったく違う結
果を生み出すのです。

回帰テストは特定のオブジェクトやファイルにまとめておくのがよいでしょう
。回帰テストの組み方にはいくつか選択肢があります:

* テストケースを対話モードの実行例にして入れたテキストファイルを書き、
  "testfile()" や "DocFileSuite()" を使ってそのファイルをテストします
  。この方法をお勧めします。最初から doctest を使うようにしている新た
  なプロジェクトでは、この方法が一番簡単です。

* "_regrtest_topic" という名前の関数を定義します。この関数には、あるト
  ピックに対応するテストケースの入った docstring が一つだけ入っていま
  す。この関数はモジュールと同じファイルの中にも置けますし、別のテスト
  ファイルに分けてもかまいません。

* 回帰テストのトピックをテストケースの入った docstring に対応付けた辞
  書 "__test__" 辞書を定義します。

テストコードをモジュールに組み込むことで、そのモジュールは、モジュール
自身がテストランナーになることができます。テストが失敗した場合には、問
題箇所をデバッグする際に、失敗したdoctestだけを再度実行することで、作
成したテストランナーを修正することができます。これがこのようなテストラ
ンナーの最小例となります。

   if __name__ == '__main__':
       import doctest
       flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
       if len(sys.argv) > 1:
           name = sys.argv[1]
           if name in globals():
               obj = globals()[name]
           else:
               obj = __test__[name]
           doctest.run_docstring_examples(obj, globals(), name=name,
                                          optionflags=flags)
       else:
           fail, total = doctest.testmod(optionflags=flags)
           print("{} failures out of {} tests".format(fail, total))

-[ 脚注 ]-

[1] 期待する出力結果と例外の両方を含んだ例はサポートされていません。一
    方の終わりと他方の始まりを見分けようとするのはエラーの元になりがち
    ですし、解りにくいテストになってしまいます。
