doctest モジュールは、対話的 Python セッションのように 見えるテキストを探し出し、セッションの内容を実行して、そこに書かれている 通りに振舞うかを調べます。 doctest は以下のような用途に よく使われています:
以下にちょっとした、それでいて完全な例を示します:
doctest モジュールは、モジュールの docstring から、 これらのセッションを実際に実行して、そこに書かれている通りに動作するか 検証します。
"""
This is the "example" module.
The example module 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:
result *= factor
factor += 1
return result
def _test():
import doctest
doctest.testmod()
if __name__ == "__main__":
_test()
example.py をコマンドラインから直接実行すると、 doctest はその魔法を働かせます:
$ python example.py $
出力は何もありません! しかしこれが正常で、全ての例が正しく動作する ことを意味しています。 スクリプトに -v を与えると、doctest は何を行おうとしているのかを記録した詳細なログを出力し、 最後にまとめを出力します:
$ python example.py -v
Trying:
factorial(5)
Expecting:
120
ok
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(1e100)
Expecting:
Traceback (most recent call last):
...
OverflowError: n too large
ok
1 items had no tests:
__main__._test
2 items passed all tests:
1 tests in __main__
8 tests in __main__.factorial
9 tests in 3 items.
9 passed and 0 failed.
Test passed.
$
これが、doctest を使って生産性の向上を目指す上で知っておく 必要があることの全てです! さあやってみましょう。詳細な事柄は後続の各節で全て説明しています。 doctest の例は、標準の Python テストスイートやライブラリ中に 沢山あります。標準のテストファイル Lib/test/test_doctest.py には、特に便利な例題があります。
doctest.py 内の docstring には doctest の全ての側面に ついての詳細な情報が入っており、ここではより重要な点をカバーするだけに します。