23.2.4 ドキュメンテーション文字列内の例をどうやって認識するのか?

ほとんどの場合、対話コンソールセッション上でのコピー／ペーストはうまく動作します。とはいえ、 doctest は特定の Python シェルの振る舞いを正確にエミュレーションしようとするわけではありません。ハードタブは全て 8 カラムのタブストップを使ってスペースに展開されます。従って、タブがそのように表現されると考えておかないととまずいことになります: その場合は、ハードタブを使わないか、自前で DocTestParser クラスを書いてください。

バージョン 2.4 で変更された仕様: 新たにタブをスペースに展開するようになりました; 以前のバージョンはハードタブを保存しようとしていたので、混乱させるようなテスト結果になってしまっていました

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print "yes"
... else:
...     print "no"
...     print "NO"
...     print "NO!!!"
...
no
NO
NO!!!
>>>

出力結果例 (expected output) は、コードを含む最後の '»> ' or '... ' 行の直下に続きます。また、出力結果例 (がある場合) は、次の '»> ' 行か、全て空白文字の行まで続きます。

細かな注意:

出力結果例には、全て空白の行が入っていてはなりません。そのような行は出力結果例の終了を表すと見なされるからです。もし予想出力結果の内容に空白行が入っている場合には、空白行が入るべき場所全てに <BLANKLINE> を入れてください。バージョン 2.4 で変更された仕様: <BLANKLINE> を追加しました; 以前のバージョンでは、空白行の入った予想出力結果を扱う方法がありませんでした

stdout への出力は取り込まれますが、stderr は取り込まれません (例外発生時のトレースバックは別の方法で取り込まれます)。

対話セッションにおいて、バックスラッシュを用いて次の行に続ける場合や、その他の理由でバックスラッシュを用いる場合、raw docstring を使ってバックスラッシュを入力どおりに扱わせるようにせねばなりません:

>>> def f(x):
...     r'''Backslashes in a raw docstring: m\n'''
>>> print f.__doc__
Backslashes in a raw docstring: m\n

こうしなければ、バックスラッシュは文字列の一部として解釈されてしまいますう。例えば、上の例の "\" は改行文字として認識されてしまうでしょう。こうする代わりに、(raw docstring を使わずに) doctest 版の中ではバックスラッシュを全て二重にしてもかまいません:

>>> def f(x):
...     '''Backslashes in a raw docstring: m\\n'''
>>> print f.__doc__
Backslashes in a raw docstring: m\n

開始カラムはどこでもかまいません:

  >>> assert "Easy!"
        >>> import math
            >>> math.floor(1.9)
            1.0

出力結果例の先頭部にある空白文字列は、例題の開始部分にあたる '»> ' 行の先頭にある空白文字列と同じだけはぎとられます。

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