23.2.6 例外はどう扱えばよいのですか?

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

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

>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
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 ?
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 をテストする必要があるというごく稀なケースでは、例題に自分で作ったトレースバックヘッダを追加する必要があるでしょう。
SyntaxError の場合、 Python は構文エラーの起きた場所を^ マーカで表示します:
```
>>> 1 1
  File "<stdin>", line 1
    1 1
      ^
SyntaxError: invalid syntax
```
例外の型と詳細情報の前にエラー位置を示す行がくるため、 doctest はこの行を調べません。例えば、以下の例では、間違った場所に^ マーカを入れてもパスしてしまいます:
```
>>> 1 1
Traceback (most recent call last):
  File "<stdin>", line 1
    1 1
    ^
SyntaxError: invalid syntax
```

バージョン 2.4 で変更された仕様: 複数行からなる例外の詳細情報を扱えるようにし、 doctest オプションIGNORE_EXCEPTION_DETAIL を追加しました

脚注

... 単にトレースバックを貼り付けてください。^23.1: 予想出力結果と例外の両方を含んだ例はサポートされていません。一方の終わりと他方の始まりを見分けようとするのはエラーの元になりがちですし、解りにくいテストになってしまいます。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。