doctest モジュールは、モジュールのドキュメンテーション文字列 (docstring) から、対話的 Python セッションのように見えるテキストを探しだし、これらのセッションを実際に実行して、そこに書かれている通りに動作するか検証します。以下に小さな、しかし完全な例を示します:
"""
This is module example.
Example supplies one function, factorial. For example,
>>> factorial(5)
120
"""
def factorial(n):
"""Return the factorial of n, an exact integer >= 0.
If the result is small enough to fit in an int, return an int.
Else return a long.
>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> [factorial(long(n)) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> factorial(30)
265252859812191058636308480000000L
>>> factorial(30L)
265252859812191058636308480000000L
>>> factorial(-1)
Traceback (most recent call last):
...
ValueError: n must be >= 0
Factorials of floats are OK, but the float must be an exact integer:
>>> factorial(30.1)
Traceback (most recent call last):
...
ValueError: n must be exact integer
>>> factorial(30.0)
265252859812191058636308480000000L
It must also not be ridiculously large:
>>> factorial(1e100)
Traceback (most recent call last):
...
OverflowError: n too large
"""
import math
if not n >= 0:
raise ValueError("n must be >= 0")
if math.floor(n) != n:
raise ValueError("n must be exact integer")
if n+1 == n: # catch a value like 1e300
raise OverflowError("n too large")
result = 1
factor = 2
while factor <= n:
try:
result *= factor
except OverflowError:
result *= long(factor)
factor += 1
return result
def _test():
import doctest, example
return doctest.testmod(example)
if __name__ == "__main__":
_test()
example.py をコマンドラインから直接実行すると、 doctest はその魔法を働かせます:
$ python example.py $
出力は何もありません! しかしこれが正常で、全ての例が正しく動作する ことを意味しています。 スクリプトに -v を与えると、doctest は何を行おうとしているのかを記録した詳細なログを出力し、 最後にまとめを出力します:
$ python example.py -v Running example.__doc__ Trying: factorial(5) Expecting: 120 ok 0 of 1 examples failed in example.__doc__ Running example.factorial.__doc__ Trying: [factorial(n) for n in range(6)] Expecting: [1, 1, 2, 6, 24, 120] ok Trying: [factorial(long(n)) for n in range(6)] Expecting: [1, 1, 2, 6, 24, 120] ok Trying: factorial(30) Expecting: 265252859812191058636308480000000L ok
And so on, eventually ending with:
Trying: factorial(1e100)
Expecting:
Traceback (most recent call last):
...
OverflowError: n too large
ok
0 of 8 examples failed in example.factorial.__doc__
2 items passed all tests:
1 tests in example
8 tests in example.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$
これが、doctest を使って生産性の向上を目指す上で知っておく 必要があることの全てです! さあやってみましょう。doctest.py 内のドキュメンテーション 文字列には doctest の全ての側面についての詳細な情報が入っており、 ここではより重要な点をカバーするだけにします。