5.2.7 注意事項

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

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

は脆弱です! 回避法としては、

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

としてください。別のやり方としては、

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

のようにします。

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

もう一つのよくない発想は、

>>> id(1.0) # certain to fail some of the time
7948648
>>>

のようなオブジェクトアドレスの埋め込みです。

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

単純な分数は人が理解し易いこともあり、よりよいドキュメント記述になります。

一度だけしか実行してはならないコードには気をつけてください。

一度だけしか実行してはならないようなモジュールレベルのコードがあるなら、_test() のフールプルーフ性の高い定義は

def _test():
    import doctest, sys
    doctest.testmod()

のようになります。

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