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) を使えば、人間にとっても 理解しやすくよいドキュメントになります。

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