23.2.6.2 注意

doctest では、予想出力に対する厳密な一致を厳しく求めています。一致しない文字が一文字でもあると、テストは失敗してしまいます。このため、Python が出力に関して何を保証していて、何を保証していないかを正確に知っていないと幾度か混乱させられることでしょう。例えば、辞書を出力する際、Python はキーと値のペアが常に特定の順番で並ぶよう保証してはいません。従って、以下のようなテスト

>>> foo()
{"Hermione": "hippogryph", "Harry": "broomstick"}

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

>>> d = foo().items()
>>> d.sort()
>>> d
[('Harry', 'broomstick'), ('Hermione', 'hippogryph')]

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

>>> id(1.0) # certain to fail some of the time
7948648
>>> class C: pass
>>> C()   # the default repr() for instances embeds an address
<__main__.C instance at 0x00AC18F0>

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

>>> C() #doctest: +ELLIPSIS
<__main__.C instance 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

このように、単分数 (simple fraction) を使えば、人間にとっても理解しやすくよいドキュメントになります。