pytho****@googl*****
pytho****@googl*****
2011年 11月 21日 (月) 20:40:06 JST
Revision: 9a51009dc21b Author: Arihiro TAKASE <hinac****@gmail*****> Date: Mon Nov 21 03:39:33 2011 Log: Update 2.7.2: library/doctest http://code.google.com/p/python-doc-ja/source/detail?r=9a51009dc21b Modified: /library/doctest.rst ======================================= --- /library/doctest.rst Wed Apr 6 11:59:50 2011 +++ /library/doctest.rst Mon Nov 21 03:39:33 2011 @@ -9,40 +9,23 @@ .. sectionauthor:: Edward Loper <edlop****@users*****> -.. The :mod:`doctest` module searches for pieces of text that look like interactive -.. Python sessions, and then executes those sessions to verify that they work -.. exactly as shown. There are several common ways to use doctest: - :mod:`doctest` モジュールは、対話的 Python セッションのように見えるテキスト を探し出し、 セッションの内容を実行して、そこに書かれている通りに振舞うかを調べます。 :mod:`doctest` は以下のような用途によく使われています。 -.. * To check that a module's docstrings are up-to-date by verifying that all -.. interactive examples still work as documented. - * モジュールの docstring (ドキュメンテーション文字列) 中にある対話実行例の すべてが書かれている通りに動作するか検証することで、 docstring の内容が最新かどうかチェックする。 -.. * To perform regression testing by verifying that interactive examples from a -.. test file or a test object work as expected. - * テストファイルやテストオブジェクト中の対話実行例が期待通りに動作するかを 検証することで、 回帰テストを実現します。 -.. * To write tutorial documentation for a package, liberally illustrated with -.. input-output examples. Depending on whether the examples or the expository text -.. are emphasized, this has the flavor of "literate testing" or "executable -.. documentation". - * 入出力例を豊富に使ったパッケージのチュートリアルドキュメントが書けます。 入出力例と解説文のどちらに注目するかによって、ドキュメントは「読めるテス ト」にも「実行できるドキュメント」にもなります。 -.. Here's a complete but small example module: - 以下に完全かつ短い実行例を示します。 @@ -111,9 +94,6 @@ doctest.testmod() -.. If you run :file:`example.py` directly from the command line, :mod:`doctest` -.. works its magic: - :file:`example.py` をコマンドラインから直接実行すると、 :mod:`doctest` はそ の魔法を働かせます。 @@ -123,12 +103,8 @@ $ -.. There's no output! That's normal, and it means all the examples worked. Pass -.. :option:`-v` to the script, and :mod:`doctest` prints a detailed log of what -.. it's trying, and prints a summary at the end: - 出力は何もありません！ しかしこれが正常で、すべての実行例が正しく動作するこ とを意味しています。 -スクリプトに :option:`-v` を与えると、 :mod:`doctest` は何を行おうとしてい るのかを記録した詳細なログを出力し、 +スクリプトに ``-v`` を与えると、 :mod:`doctest` は何を行おうとしているのか を記録した詳細なログを出力し、 最後にまとめを出力します。 @@ -152,8 +128,6 @@ ok -.. And so on, eventually ending with: - といった具合で、最後には @@ -175,12 +149,6 @@ $ -.. That's all you need to know to start making productive use of :mod:`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 -.. :file:`Lib/test/test_doctest.py`. - :mod:`doctest` の生産的な利用を始めるために知る必要があるのはこれだけです！ さあやってみましょう。詳細な事柄は後続の各節ですべて説明しています。 doctest の例は、標準の Python テストスイートやライブラリ中に沢山あります。 @@ -192,9 +160,6 @@ 簡単な利用法: docstring 中の実行例をチェックする ------------------------------------------------ -.. The simplest way to start using doctest (but not necessarily the way you'll -.. continue to do it) is to end each module :mod:`M` with: - doctest を試す簡単な方法 (とはいえ、いつもそうする必要はないのですが) は、 各モジュール :mod:`M` の最後を、以下のようにして締めくくることです。 @@ -206,14 +171,9 @@ doctest.testmod() -.. :mod:`doctest` then examines docstrings in module :mod:`M`. - こうすると、 :mod:`doctest` は :mod:`M` 中の docstring を検査します。 -.. Running the module as a script causes the examples in the docstrings to get -.. executed and verified: - モジュールをスクリプトとして実行すると、docstring 中の実行例が実行され、検 証されます。 @@ -222,19 +182,12 @@ python M.py -.. This won't display anything unless an example fails, in which case the failing -.. example(s) and the cause(s) of the failure(s) are printed to stdout, and the -.. final line of output is ``***Test Failed*** N failures.``, where *N* is the -.. number of examples that failed. - docstring に書かれた実行例の実行が失敗しない限り、何も表示されません。 失敗すると、失敗した実行例と、その原因が (場合によっては複数) 標準出力に印 字され、 最後に ``***Test Failed*** N failures.`` という行を出力します。ここで、 *N* は失敗した実行例の数です。 -.. Run it with the :option:`-v` switch instead: - -一方、 :option:`-v` スイッチをつけて走らせると +一方、 ``-v`` スイッチをつけて走らせると :: @@ -242,27 +195,14 @@ python M.py -v -.. and a detailed report of all examples tried is printed to standard output, along -.. with assorted summaries at the end. - 実行を試みたすべての実行例について詳細に報告し、最後に各種まとめを行った内 容が標準出力に印字されます。 -.. You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or -.. prohibit it by passing ``verbose=False``. In either of those cases, -.. ``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not -.. has no effect). - ``verbose=True`` を :func:`testmod` に渡せば、詳細報告 (verbose) モードを強 制できます。また、 ``verbose=False`` にすれば禁止できます。どちらの場合にも、 :func:`testmod` は ``sys.argv`` 上のスイッチ -を調べません。(したがって、 :option:`-v` をつけても効果はありません)。 +を調べません。(したがって、 ``-v`` をつけても効果はありません)。 -.. Since Python 2.6, there is also a command line shortcut for running -.. :func:`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 2.6 からは :func:`testmod` を実行するコマンドラインショートカットが あります。 Python インタプリタに doctest モジュールを標準ライブラリから直接実行して、 テストする モジュール名をコマンドライン引数に与えます。 @@ -273,18 +213,12 @@ python -m doctest -v example.py -.. This will import :file:`example.py` as a standalone module and run -.. :func:`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. - こうすると :file:`example.py` を単体モジュールとしてインポートして、 それに対して :func:`testmod` を実行します。 このファイルがパッケージの一部で他のサブモジュールをそのパッケージからイン ポートしている場合は うまく動かないことに注意してください。 -.. For more information on :func:`testmod`, see section :ref:`doctest-basic-api`. - :func:`testmod` の詳しい情報は :ref:`doctest-basic-api` 節を参照してくださ い。 @@ -293,9 +227,6 @@ 簡単な利用法: テキストファイル中の実行例をチェックする ------------------------------------------------------ -.. Another simple application of doctest is testing interactive examples in a text -.. file. This can be done with the :func:`testfile` function: - doctest のもう一つの簡単な用途は、テキストファイル中にある対話実行例に対す るテストです。 これには :func:`testfile` 関数を使います。 @@ -306,11 +237,6 @@ doctest.testfile("example.txt") -.. That short script executes and verifies any interactive Python examples -.. contained in the file :file:`example.txt`. The file content is treated as if it -.. were a single giant docstring; the file doesn't need to contain a Python -.. program! For example, perhaps :file:`example.txt` contains this: - この短いスクリプトは、 :file:`example.txt` というファイルの中に入っている対 話モードの Python 操作例すべてを実行して、その内容を検証します。 ファイルの内容は一つの巨大な docstring であるかのように扱われます; ファイル が Python プログラムである必要はありません！ @@ -352,9 +278,6 @@ 120 -.. Running ``doctest.testfile("example.txt")`` then finds the error in this -.. documentation: - ``doctest.testfile("example.txt")`` を実行すると、このドキュメント内のエ ラーを見つけ出します。 @@ -369,39 +292,21 @@ 720 -.. As with :func:`testmod`, :func:`testfile` won't display anything unless an -.. example fails. If an example does fail, then the failing example(s) and the -.. cause(s) of the failure(s) are printed to stdout, using the same format as -.. :func:`testmod`. - :func:`testmod` と同じく、 :func:`testfile` は実行例が失敗しない限り何も表 示しません。 実行例が失敗すると、失敗した実行例とその原因が (場合によっては複数 ) :func:`testmod` と同じ書式で標準出力に書き出されます。 -.. By default, :func:`testfile` looks for files in the calling module's directory. -.. See section :ref:`doctest-basic-api` for a description of the optional arguments -.. that can be used to tell it to look for files in other locations. - デフォルトでは、 :func:`testfile` は自分自身を呼び出したモジュールのあるデ ィレクトリを探します。 その他の場所にあるファイルを見に行くように :func:`testfile` に指示するためのオプション引数についての説明は :ref:`doctest-basic-api` 節を参照してください。 -.. Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the -.. :option:`-v` command-line switch or with the optional keyword argument -.. *verbose*. - :func:`testmod` と同様に :func:`testfile` の冗長性 (verbosity) はコマンドラ インスイッチ -:option:`-v` またはオプションのキーワード引数 *verbose* によって指定できま す。 +``-v`` またはオプションのキーワード引数 *verbose* によって指定できます。 -.. Since Python 2.6, there is also a command line shortcut for running -.. :func:`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 2.6 からは :func:`testfile` を実行するコマンドラインショートカットが あります。 Python インタプリタに doctest モジュールを標準ライブラリから直接実行して、 テストする モジュール名をコマンドライン引数に与えます。 @@ -412,15 +317,10 @@ python -m doctest -v example.txt -.. Because the file name does not end with :file:`.py`, :mod:`doctest` infers that -.. it must be run with :func:`testfile`, not :func:`testmod`. - ファイル名が :file:`.py` で終っていないので、 :mod:`doctest` は :func:`testmod` ではなく :func:`testfile` を使って実行するのだと判断します。 -.. For more information on :func:`testfile`, see section :ref:`doctest-basic-api`. - :func:`testfile` の詳細は :ref:`doctest-basic-api` 節を参照してください。 @@ -429,13 +329,6 @@ doctest のからくり ------------------ -.. This section examines in detail how doctest works: which docstrings it looks at, -.. how it finds interactive examples, what execution context it uses, how it -.. handles exceptions, and how option flags can be used to control its behavior. -.. This is the information that you need to know to write doctest examples; for -.. information about actually running doctest on these examples, see the following -.. sections. - この節では、doctest のからくり: どの docstring を見に行くのか、 どのように対話実行例を見つけ出すのか、どんな実行コンテキストを使うのか、 例外をどう扱うか、上記の振る舞いを制御するためにどのようなオプションフラグ を使うか、について詳しく吟味します。 @@ -448,19 +341,10 @@ どの docstring が検証されるのか? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. The module docstring, and all function, class and method docstrings are -.. searched. Objects imported into the module are not searched. - モジュールの docstring と、すべての関数、クラスおよびメソッドの docstring が検索されます。 モジュールに import されたオブジェクトは検索されません。 -.. In addition, if ``M.__test__`` exists and "is true", 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__`` が存在し、 "真の値を持つ" 場合、この値は辞書でなけ ればならず、辞書の各エントリは (文字列の) 名前を 関数オブジェクト、クラスオブジェクト、または文字列へとマップします。 ``M.__test__`` から得られた関数およびクラスオブジェクトの docstring は、 @@ -477,17 +361,11 @@ のように表示されます。 -.. Any classes found are recursively searched similarly, to test docstrings in -.. their contained methods and nested classes. - 検索中に見つかったクラスも同様に再帰的に検索が行われ、 クラスに含まれているメソッドおよびネストされたクラスについて docstring のテストが行われます。 -.. .. versionchanged:: 2.4 -.. A "private name" concept is deprecated and no longer documented. - .. versionchanged:: 2.4 "プライベート名" の概念は廃止されたため、ドキュメント化されなくなりまし た。 @@ -497,9 +375,6 @@ docstring 内の実行例をどのように認識するのか? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. In most cases a copy-and-paste of an interactive console session works fine, -.. but doctest isn't trying to do an exact emulation of any specific Python shell. - ほとんどの場合、対話コンソールセッション上でのコピー／ペーストはうまく動作 します。 とはいえ、 :mod:`doctest` は特定の Python シェルの振る舞いを正確にエミュ レーションしようとするわけではありません。 @@ -523,48 +398,22 @@ >>> -.. Any expected output must immediately follow the final ``'>>> '`` or ``'... '`` -.. line containing the code, and the expected output (if any) extends to the next -.. ``'>>> '`` or all-whitespace line. - コードを含む最後の ``'>>> '`` または ``'... '`` 行の直下に期待する出力結果 が置かれます。 (出力結果がもしあれば) それは次の ``'>>> '`` 行か、すべて空白文字の行まで続 きます。 -.. The fine print: - 詳細事項: -.. * Expected output cannot contain an all-whitespace line, since such a line is -.. taken to signal the end of expected output. If expected output does contain a -.. blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line -.. is expected. - * 期待する出力結果には、空白だけの行が入っていてはなりません。 そのような行は期待する出力結果の終了を表すと見なされるからです。 もし期待する出力結果の内容に空白行が入っている場合には、空白行が入るべき 場所すべてに ``<BLANKLINE>`` を入れてください。 - .. .. versionchanged:: 2.4 - .. ``<BLANKLINE>`` was added; there was no way to use expected output containing - .. empty lines in previous versions. - - .. versionchanged:: 2.4 + .. versionadded:: 2.4 ``<BLANKLINE>`` が追加されました; 以前のバージョンでは、空白行を含む出 力結果を扱う方法がありませんでした。 -.. * All hard tab characters are expanded to spaces, using 8-column tab stops. -.. Tabs in output generated by the tested code are not modified. Because any -.. hard tabs in the sample output *are* expanded, this means that if the code -.. output includes hard tabs, the only way the doctest can pass is if the -.. :const:`NORMALIZE_WHITESPACE` option or directive is in effect. -.. Alternatively, the test can be rewritten to capture the output and compare it -.. to an expected value as part of the test. This handling of tabs in the -.. source was arrived at through trial and error, and has proven to be the least -.. error prone way of handling them. It is possible to use a different -.. algorithm for handling tabs by writing a custom :class:`DocTestParser` class. - * ハードタブはすべて 8 カラムのタブストップを使ってスペースに展開されます。 テストコードによって生成された出力におけるタブは変更されていません。 サンプル出力におけるハードタブはすべて展開 *される* ので、これが意味する のは、 @@ -575,25 +424,14 @@ カスタムな :class:`DocTestParser` クラスを書くことによって、タブを扱うの に異なるアルゴリズムを使うことができます。 - .. .. versionchanged:: 2.4 - .. Expanding tabs to spaces is new; previous versions tried to preserve hard tabs, - .. with confusing results. - .. versionchanged:: 2.4 新たにタブをスペースに展開するようになりました; 以前のバージョンはハー ドタブを保存しようとしていたので、 混乱させるようなテスト結果になってしまっていました。 -.. * Output to stdout is captured, but not output to stderr (exception tracebacks -.. are captured via a different means). - * 標準出力への出力は取り込まれますが、標準エラーは取り込まれません (例外発 生時のトレースバックは別の方法で取り込まれます)。 -.. * If you continue a line via backslashing in an interactive session, or for any -.. other reason use a backslash, you should use a raw docstring, which will -.. preserve your backslashes exactly as you type them: - * 対話セッションにおいて、バックスラッシュを用いて次の行に続ける場合や、 その他の理由でバックスラッシュを用いる場合、raw docstring を使って バックスラッシュを入力どおりに扱わせるようにしなければなりません。 @@ -607,10 +445,6 @@ Backslashes in a raw docstring: m\n - .. Otherwise, the backslash will be interpreted as part of the string. For example, - .. the "\\" above would be interpreted as a newline character. Alternatively, you - .. can double each backslash in the doctest version (and not use a raw string): - こうしなければ、バックスラッシュは文字列の一部として解釈されてしまいま す。 例えば、上の例の "\\n" は改行文字として認識されてしまうでしょう。 こうする代わりに、(raw docstring を使わずに) doctest 版の中ではバックスラ ッシュをすべて二重にしてもかまいません。 @@ -624,8 +458,6 @@ Backslashes in a raw docstring: m\n -.. * The starting column doesn't matter: - * 開始カラムはどこでもかまいません。 @@ -637,9 +469,6 @@ 1.0 - .. and as many leading whitespace characters are stripped from the expected output - .. as appeared in the initial ``'>>> '`` line that started the example. - 期待する出力結果の先頭部にある空白文字列は、実行例の開始部分にあたる ``'>>> '`` 行の先頭にある空白文字列と同じだけ取り除かれます。 @@ -648,14 +477,6 @@ 実行コンテキストとは何か? ^^^^^^^^^^^^^^^^^^^^^^^^^ -.. By default, each time :mod:`doctest` finds a docstring to test, it uses a -.. *shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the -.. module's real globals, and so that one test in :mod:`M` can't leave behind -.. crumbs that accidentally allow another test to work. This means examples can -.. freely use any names defined at top-level in :mod:`M`, and names defined earlier -.. in the docstring being run. Examples cannot see names defined in other -.. docstrings. - デフォルトでは、 :mod:`doctest` はテストを行うべき docstring を見つけるたび に :mod:`M` のグローバル名前空間の *浅いコピー* を使い、 テストの実行によってモジュールの実際のグローバル名前空間を変更しないように し、 @@ -665,9 +486,6 @@ 個々の実行例は他の docstring 中で定義された名前を参照できません。 -.. You can force use of your own dict as the execution context by passing -.. ``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead. - :func:`testmod` や :func:`testfile` に ``globs=your_dict`` を渡し、 自前の辞書を実行コンテキストとして使うこともできます。 @@ -677,20 +495,12 @@ 例外はどう扱えばよいか? ^^^^^^^^^^^^^^^^^^^^^^^ -.. No problem, provided that the traceback is the only output produced by the -.. example: just paste in the traceback. [#]_ Since tracebacks contain details -.. that are likely to change rapidly (for example, exact file paths and line -.. numbers), this is one case where doctest works hard to be flexible in what it -.. accepts. - トレースバックが実行例によって生成される唯一の出力なら問題ありません。 単にトレースバックを貼り付けてください。 [#]_ トレースバックには、頻繁に変更されがちな情報 (例えばファイルパスや行番号な ど) が入っているものなので、 これは受け入れるテスト結果に柔軟性を持たせようと doctest が苦労している部分 の一つです。 -.. Simple example: - 簡単な例を示しましょう。 @@ -702,16 +512,9 @@ ValueError: list.remove(x): x not in list -.. That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x): -.. x not in list`` detail as shown. - この doctest は、 :exc:`ValueError` が送出され、その詳細情報が ``list.remove(x): x not in list`` である場合に成功します。 -.. The expected output for an exception must start with a traceback header, which -.. may be either of the following two lines, indented the same as the first line of -.. the example: - 例外が発生したときの期待する出力はトレースバックヘッダから始まっていなけれ ばなりません。 トレースバックの形式は以下の二通りの行のいずれかで、 実行例の最初の行と同じインデントでなければりません。 @@ -723,20 +526,11 @@ Traceback (innermost last): -.. The traceback header is followed by an optional traceback stack, whose contents -.. are ignored by doctest. The traceback stack is typically omitted, or copied -.. verbatim from an interactive session. - トレースバックヘッダの後ろにトレースバックスタックが続いてもかまいません が、 doctest はその内容を無視します。 普通はトレースバックスタックを省略するか、対話セッションからそのままコピー してきます。 -.. The traceback stack is followed by the most interesting part: the line(s) -.. containing the exception type and detail. This is usually the last line of a -.. traceback, but can extend across multiple lines if the exception has a -.. multi-line detail: - トレースバックスタックの後ろにはもっとも有意義な部分、例外の型と詳細情報の 入った行があります。 これは通常トレースバックの最後の行ですが、例外が複数行の詳細情報を持ってい る場合、 複数の行にわたることもあります。 @@ -752,15 +546,12 @@ detail -.. The last three lines (starting with :exc:`ValueError`) are compared against the -.. exception's type and detail, and the rest are ignored. - 上の例では、最後の 3 行 (:exc:`ValueError` から始まる行) における例外の型と 詳細情報だけが比較され、 それ以外の部分は無視されます。 - -.. Best practice is to omit the traceback stack, unless it adds significant -.. documentation value to the example. So the last example is probably better as: +.. versionchanged:: 2.4 + 以前のバージョンでは、複数行にわたる例外の詳細を扱えませんでした。 + 例外を扱うコツは、実行例をドキュメントとして読む上で明らかに価値のある情報 でない限り、 トレースバックスタックは省略する、ということです。したがって、先ほどの例は 以下のように書くべきでしょう。 @@ -776,12 +567,6 @@ detail -.. Note that tracebacks are treated very specially. In particular, in the -.. rewritten example, the use of ``...`` is independent of doctest's -.. :const:`ELLIPSIS` option. The ellipsis in that example could be left out, or -.. could just as well be three (or three hundred) commas or digits, or an indented -.. transcript of a Monty Python skit. - トレースバックの扱いは非常に特殊なので注意してください。 特に、上の書き直した実行例では、 ``...`` の扱いは doctest の :const:`ELLIPSIS` オプションとは独立しています。 @@ -790,18 +575,9 @@ Monty Python のスキットをインデントして書き写したものかもしれません。 -.. Some details you should read once, but won't need to remember: - 以下の詳細はずっと覚えておく必要はないのですが、一度目を通しておいてくださ い。 -.. * Doctest can't guess whether your expected output came from an exception -.. traceback or from ordinary printing. So, e.g., an example that expects -.. ``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually -.. raised or if the example merely prints that traceback text. In practice, -.. ordinary output rarely begins with a traceback header line, so this doesn't -.. create real problems. - * doctest は期待する出力の出所が print 文なのか例外なのかを推測できません。 したがって、例えば期待する出力が ``ValueError: 42 is prime`` であるような 実行例は、 :exc:`ValueError` が実際に送出された場合と、万が一期待する出力と同じ文字 列を @@ -810,12 +586,6 @@ 実際に問題になることはないでしょう。 -.. * Each line of the traceback stack (if present) must be indented further than -.. the first line of the example, *or* start with a non-alphanumeric character. -.. The first line following the traceback header indented the same and starting -.. with an alphanumeric is taken to be the start of the exception detail. Of -.. course this does the right thing for genuine tracebacks. - * トレースバックスタック (がある場合) の各行は、実行例の最初の行よりも深く インデントされているか、 *または* 英数文字以外で始まっていなければなりません。 トレースバックヘッダ以後に現れる行のうち、インデントが等しく英数文字で始 まる最初の行は @@ -823,19 +593,11 @@ もちろん、本物のトレースバックでは正しく動作します。 -.. * When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is is specified, -.. everything following the leftmost colon is ignored. - * doctest のオプション :const:`IGNORE_EXCEPTION_DETAIL` を指定した場合、 - 最も左端のコロン以後の内容が無視されます。 + 最も左端のコロン以後の全ての内容と、例外名の中の全てのモジュール情報が + 無視されます。 -.. * The interactive shell omits the traceback header line for some -.. :exc:`SyntaxError`\ s. But doctest uses the traceback header line to -.. distinguish exceptions from non-exceptions. So in the rare case where you need -.. to test a :exc:`SyntaxError` that omits the traceback header, you will need to -.. manually add the traceback header line to your test example. - * 対話シェルでは、 :exc:`SyntaxError` の場合にトレースバックヘッダが省略さ れることがあります。 しかし doctest にとっては、例外を例外でないものと区別するためにトレースバ ックヘッダが必要です。 そこで、トレースバックヘッダを省略するような :exc:`SyntaxError` @@ -843,9 +605,6 @@ 実行例にトレースバックヘッダを手作業で追加する必要があるでしょう。 -.. * For some :exc:`SyntaxError`\ s, Python displays the character position of the -.. syntax error, using a ``^`` marker: - * :exc:`SyntaxError` の場合、 Python は構文エラーの起きた場所を ``^`` マー カで表示します。 @@ -858,10 +617,6 @@ SyntaxError: invalid syntax - .. Since the lines showing the position of the error come before the exception type - .. and detail, they are not checked by doctest. For example, the following test - .. would pass, even though it puts the ``^`` marker in the wrong location: - 例外の型と詳細情報の前にエラー位置を示す行がくるため、 doctest はこの行を 調べません。 例えば、以下の例では、間違った場所に ``^`` マーカを入れても成功してしまい ます。 @@ -876,46 +631,22 @@ SyntaxError: invalid syntax -.. .. versionchanged:: 2.4 -.. The ability to handle a multi-line exception detail, and the -.. :const:`IGNORE_EXCEPTION_DETAIL` doctest option, were added. - -.. versionchanged:: 2.4 - 複数行からなる例外の詳細情報が扱えるようになり、 doctest オプショ ン :const:`IGNORE_EXCEPTION_DETAIL` が追加されました. - - .. _doctest-options: オプションフラグとディレクティブ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. A number of option flags control various aspects of doctest's behavior. -.. Symbolic names for the flags are supplied as module constants, which can be -.. or'ed together and passed to various functions. The names can also be used in -.. doctest directives (see below). - doctest では、その挙動の様々な側面をたくさんのオプションフラグで制御してい ます。各フラグのシンボル名はモジュールの定数として提供されて おり、論理和で組み合わせて様々な関数に渡せるようになっています。シンボル名 は doctest のディレクティブ (directive, 下記参照) としても 使えます。 -.. The first group of options define test semantics, controlling aspects of how -.. doctest decides whether actual output matches an example's expected output: - 最初に説明するオプション群は、テストのセマンティクスを決めます。すなわち、 実際にテストを実行したときの出力と実行例中の期待する出力とが一致しているかど うかを doctest がどのように判断するかを制御します。 .. data:: DONT_ACCEPT_TRUE_FOR_1 - .. By default, if an expected output block contains just ``1``, an actual output - .. block containing just ``1`` or just ``True`` is considered to be a match, and - .. similarly for ``0`` versus ``False``. When :const:`DONT_ACCEPT_TRUE_FOR_1` is - .. specified, neither substitution is allowed. The default behavior caters to that - .. Python changed the return type of many functions from integer to boolean; - .. doctests expecting "little integer" output still work in these cases. This - .. option will probably go away, but not for several years. - デフォルトでは、期待する出力ブロックに単に ``1`` だけが入っており、実際 の出力ブロックに ``1`` または ``True`` だけが入っていた場合、これらの出力は一致しているとみなされます。 ``0`` と ``False`` の場合も同様です。 @@ -927,12 +658,6 @@ .. data:: DONT_ACCEPT_BLANKLINE - .. By default, if an expected output block contains a line containing only the - .. string ``<BLANKLINE>``, then that line will match a blank line in the actual - .. output. Because a genuinely blank line delimits the expected output, this is - .. the only way to communicate that a blank line is expected. When - .. :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed. - デフォルトでは、期待する出力ブロックに ``<BLANKLINE>`` だけの入った行が ある場合、 その行は実際の出力における空行に一致するようになります。 完全な空行を入れてしまうと期待する出力がそこで終わっているとみなされてし まうため、 @@ -942,13 +667,6 @@ .. data:: NORMALIZE_WHITESPACE - .. When specified, all sequences of whitespace (blanks and newlines) are treated as - .. equal. Any sequence of whitespace within the expected output will match any - .. sequence of whitespace within the actual output. By default, whitespace must - .. match exactly. :const:`NORMALIZE_WHITESPACE` is especially useful when a line of - .. expected output is very long, and you want to wrap it across multiple lines in - .. your source. - このフラグを指定すると、連続する空白 (空白と改行文字) は互いに等価である とみなします。 期待する出力における任意の空白列は実際の出力における任意の空白と一致しま す。 デフォルトでは、空白は厳密に一致しなければなりません。 @@ -958,12 +676,6 @@ .. data:: ELLIPSIS - .. When specified, an ellipsis marker (``...``) in the expected output can match - .. any substring in the actual output. This includes substrings that span line - .. boundaries, and empty substrings, so it's best to keep usage of this simple. - .. Complicated uses can lead to the same kinds of "oops, it matched too much!" - .. surprises that ``.*`` is prone to in regular expressions. - このフラグを指定すると、期待する出力中の省略記号マーカ (``...``) が実際の出力中の任意の部分文字列と一致するようになります。 部分文字列は行境界にわたるものや空文字列を含みます。 @@ -974,12 +686,6 @@ .. data:: IGNORE_EXCEPTION_DETAIL - .. When specified, an example that expects an exception passes if an exception of - .. the expected type is raised, even if the exception detail does not match. For - .. example, an example expecting ``ValueError: 42`` will pass if the actual - .. exception raised is ``ValueError: 3*14``, but will fail, e.g., if - .. :exc:`TypeError` is raised. - このフラグを指定すると、期待する実行結果に例外が入るような実行例で、 期待通りの型の例外が送出された場合に、例外の詳細情報が一致していなくても テストが成功します。 例えば、期待する出力が ``ValueError: 42`` であるような実行例は、 @@ -987,21 +693,28 @@ :exc:`TypeError` が送出されるといった場合には成功しません。 - .. Note that a similar effect can be obtained using :const:`ELLIPSIS`, and - .. :const:`IGNORE_EXCEPTION_DETAIL` may go away when Python releases prior to 2.4 - .. become uninteresting. Until then, :const:`IGNORE_EXCEPTION_DETAIL` is the only - .. clear way to write a doctest that doesn't care about the exception detail yet - .. continues to pass under Python releases prior to 2.4 (doctest directives appear - .. to be comments to them). For example, - - :const:`ELLIPSIS` を使っても同様のことがで き、 :const:`IGNORE_EXCEPTION_DETAIL` はリリース 2.4 以前の Python を使う人 がほとんどいなくなった時期を見計らって - 廃止するかもしれないので気をつけてください。 - それまでは、 :const:`IGNORE_EXCEPTION_DETAIL` は 2.4 以前の Python で - 例外の詳細については気にせずテストを成功させるように - doctest を書くための唯一の明確な方法です。例えば、 - - - :: + これは Python 3 doctest レポートにおいて使われるモジュール名も無視しま す。 + 従って、以下の 2 つのテストは、Python 2.7 と Python 3.2 (またはそれ以降 ) の + どちらでも同じように動作します: + + >>> raise CustomError('message') #doctest: +IGNORE_EXCEPTION_DETAIL + Traceback (most recent call last): + CustomError: message + + >>> raise CustomError('message') #doctest: +IGNORE_EXCEPTION_DETAIL + Traceback (most recent call last): + my_module.CustomError: message + + なお、 :const:`ELLIPSIS` を使っても例外メッセージの詳細を無視することが + できますが、モジュールの詳細が例外名の一部として表示されるかどうかに + 依存するようなテストは、やはり失敗します。 + また、 :const:`IGNORE_EXCEPTION_DETAIL` と Python 2.3 の詳細情報を + 使うことが、例外の詳細に影響されず、なおかつ Python 2.3 以前 の Python + (これらのリリースは doctest ディレクティブをサポートせず、 + これらを無関係なコメントとして無視します) で + 成功する doctest を書くための、唯一の明確な方法です。 + 例えば、例外の詳細情報は 2.4 で変更され、 "doesn't" の代わりに + "does not" と書くようになりましたが:: >>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): @@ -1009,21 +722,15 @@ TypeError: object doesn't support item assignment - .. passes under Python 2.4 and Python 2.3. The detail changed in 2.4, to say "does - .. not" instead of "doesn't". - - とすると、 Python 2.4 と Python 2.3 の両方でテストを成功させることができ ます。 - というのは、例外の詳細情報は 2.4 で変更され、 "doesn't" から "does not" と書くようになったからです。 + とすると、 Python 2.3 以降の Python バージョンでテストを成功させることが できます。 + + .. versionchanged:: 2.7 + :const:`IGNORE_EXCEPTION_DETAIL` は、テストにおいて例外を含むモジュー ルに + 関する情報も無視するようになりました。 .. data:: SKIP - .. When specified, do not run the example at all. This can be useful in contexts - .. where doctest examples serve as both documentation and test cases, and an - .. example should be included for documentation purposes, but should not be - .. checked. E.g., the example's output might be random; or the example might - .. depend on resources which would be unavailable to the test driver. - このフラグを指定すると、実行例は一切実行されません。 こうした機能は doctest の実行例がドキュメントとテストを兼ねていて、 ドキュメントのためには含めておかなければならないけれどチェックされなくて も良い、 @@ -1032,47 +739,30 @@ テストドライバーには利用できないリソースに依存している場合などです。 - .. The SKIP flag can also be used for temporarily "commenting out" examples. - SKIP フラグは一時的に実行例を"コメントアウト"するのにも使えます。 +.. versionadded:: 2.5 .. data:: COMPARISON_FLAGS - .. A bitmask or'ing together all the comparison flags above. - 上記の比較フラグすべての論理和をとったビットマスクです。 -.. The second group of options controls how test failures are reported: - 二つ目のオプション群は、テストの失敗を報告する方法を制御します。 .. data:: REPORT_UDIFF - .. When specified, failures that involve multi-line expected and actual outputs are - .. displayed using a unified diff. - このオプションを指定すると、期待する出力および実際の出力が複数行になると きにテストの失敗結果を unified diff 形式を使って表示します。 .. data:: REPORT_CDIFF - .. When specified, failures that involve multi-line expected and actual outputs - .. will be displayed using a context diff. - このオプションを指定すると、期待する出力および実際の出力が複数行になると きにテストの失敗結果を context diff 形式を使って表示します。 .. data:: REPORT_NDIFF - .. When specified, differences are computed by ``difflib.Differ``, using the same - .. algorithm as the popular :file:`ndiff.py` utility. This is the only method that - .. marks differences within lines as well as across lines. For example, if a line - .. of expected output contains digit ``1`` where actual output contains letter - .. ``l``, a line is inserted with a caret marking the mismatching column positions. - このオプションを指定すると、期待する出力と実際の出力との間の差分を ``difflib.Differ`` を使って算出します。 使われているアルゴリズムは有名な :file:`ndiff.py` ユーティリティと同じで す。 これは、行単位の差分と同じように行内の差分にマーカをつけられるようにする 唯一の手段です。 @@ -1082,14 +772,6 @@ .. data:: REPORT_ONLY_FIRST_FAILURE - .. When specified, display the first failing example in each doctest, but suppress - .. output for all remaining examples. This will prevent doctest from reporting - .. correct examples that break because of earlier failures; but it might also hide - .. incorrect examples that fail independently of the first failure. When - .. :const:`REPORT_ONLY_FIRST_FAILURE` is specified, the remaining examples are - .. still run, and still count towards the total number of failures reported; only - .. the output is suppressed. - このオプションを指定すると、各 doctest で最初にエラーの起きた実行例だけ を表示し、 それ以後の実行例の出力を抑制します。これにより、正しく書かれた実行例が、 それ以前の実行例の失敗によっておかしくなってしまった場合に、 @@ -1101,15 +783,9 @@ .. data:: REPORTING_FLAGS - .. A bitmask or'ing together all the reporting flags above. - 上記のエラー報告に関するフラグすべての論理和をとったビットマスクです。 -.. "Doctest directives" may be used to modify the option flags for individual -.. examples. Doctest directives are expressed as a special Python comment -.. following an example's source code: - 「doctest ディレクティブ」を使うと、個々の実行例に対してオプションフラグの 設定を変更できます。 doctest ディレクティブは特殊な Python コメント文として表現され、実行例のソースコードの後に続けます。 @@ -1122,23 +798,14 @@ directive_option_name: "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ... -.. Whitespace is not allowed between the ``+`` or ``-`` and the directive option -.. name. The directive option name can be any of the option flag names explained -.. above. - ``+`` や ``-`` とディレクティブオプション名の間に空白を入れてはなりません。 ディレクティブオプション名は上で説明したオプションフラグ名のいずれかです。 -.. An example's doctest directives modify doctest's behavior for that single -.. example. Use ``+`` to enable the named behavior, or ``-`` to disable it. - ある実行例の doctest ディレクティブは、その実行例だけの doctest の振る舞い を変えます。 ある特定の挙動を有効にしたければ ``+`` を、無効にしたければ ``-`` を使いま す。 -.. For example, this test passes: - 例えば、以下のテストは成功します。 @@ -1149,11 +816,6 @@ 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] -.. Without the directive it would fail, both because the actual output doesn't have -.. two blanks before the single-digit list elements, and because the actual output -.. is on a single line. This test also passes, and also requires a directive to do -.. so: - ディレクティブがない場合、実際の出力には一桁の数字の間に二つスペースが入っ ていないこと、 実際の出力は 1 行になることから、テストは成功しないはずです。 別のディレクティブを使って、このテストを成功させることもできます。 @@ -1165,8 +827,6 @@ [0, 1, ..., 18, 19] -.. Multiple directives can be used on a single physical line, separated by commas: - 複数のディレクティブは、一つの物理行の中にコンマで区切って指定できます。 @@ -1176,9 +836,6 @@ [0, 1, ..., 18, 19] -.. If multiple directive comments are used for a single example, then they are -.. combined: - 一つの実行例中で複数のディレクティブコメントを使った場合、それらは組み合わ されます。 @@ -1189,10 +846,6 @@ [0, 1, ..., 18, 19] -.. As the previous example shows, you can add ``...`` lines to your example -.. containing only directives. This can be useful when an example is too long for -.. a directive to comfortably fit on the same line: - この実行例で分かるように、実行例にはディレクティブだけを含む ``...`` 行を追 加することができます。 この書きかたは、実行例が長すぎるためにディレクティブを同じ行に入れると収ま りが悪い場合に便利です。 @@ -1204,57 +857,26 @@ [0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59] -.. Note that since all options are disabled by default, and directives apply only -.. to the example they appear in, enabling options (via ``+`` in a directive) is -.. usually the only meaningful choice. However, option flags can also be passed to -.. functions that run doctests, establishing different defaults. In such cases, -.. disabling an option via ``-`` in a directive can be useful. - -デフォルトではすべてのオプションが無効になっており、ディレクティブは特定の 実行例だけに影響を及ぼすので、 +フォルトではすべてのオプションが無効になっており、ディレクティブは特定の実 行例だけに影響を及ぼすので、 通常意味があるのは有効にするためのオプション (``+`` のついたディレクティブ ) だけです。 とはいえ、 doctest を実行する関数はオプションフラグを指定してデフォルトとは 異なった挙動を実現できるので、 そのような場合には ``-`` を使った無効化オプションも意味を持ちます。 -.. .. versionchanged:: 2.4 -.. Constants :const:`DONT_ACCEPT_BLANKLINE`, :const:`NORMALIZE_WHITESPACE`, -.. :const:`ELLIPSIS`, :const:`IGNORE_EXCEPTION_DETAIL`, :const:`REPORT_UDIFF`, -.. :const:`REPORT_CDIFF`, :const:`REPORT_NDIFF`, -.. :const:`REPORT_ONLY_FIRST_FAILURE`, :const:`COMPARISON_FLAGS` and -.. :const:`REPORTING_FLAGS` were added; by default ``<BLANKLINE>`` in expected -.. output matches an empty line in actual output; and doctest directives were -.. added. - -.. versionchanged:: 2.4 - 定数 :const:`DONT_ACCEPT_BLANKLINE`, :const:`NORMALIZE_WHITESPACE`, +.. versionadded:: 2.4 + doctest ディレクティブおよび関連する定数 + :const:`DONT_ACCEPT_BLANKLINE`, :const:`NORMALIZE_WHITESPACE`, :const:`ELLIPSIS`, :const:`IGNORE_EXCEPTION_DETAIL`, :const:`REPORT_UDIFF`, :const:`REPORT_CDIFF`, :const:`REPORT_NDIFF`, - :const:`REPORT_ONLY_FIRST_FAILURE`, :const:`COMPARISON_FLAGS`, - :const:`REPORTING_FLAGS` が追加されました。期待する出力中の ``<BLANKLINE>`` がデフォルトで - 実際の出力中の空行にマッチするようになりました。また、 doctest ディレク ティブが追加されました。 + :const:`REPORT_ONLY_FIRST_FAILURE`, :const:`COMPARISON_FLAGS`, および + :const:`REPORTING_FLAGS` が追加されました。 -.. .. versionchanged:: 2.5 -.. Constant :const:`SKIP` was added. - -.. versionchanged:: 2.5 - 定数 :const:`SKIP` が追加されました。 - - -.. There's also a way to register new option flag names, although this isn't useful -.. unless you intend to extend :mod:`doctest` internals via subclassing: - 新たなオプションフラグ名を登録する方法もありますが、 :mod:`doctest` の内部 をサブクラスで拡張しない限り、意味はないでしょう。 ***The diff for this file has been truncated for email.***
