# 5.2 `doctest` -- ドキュメンテーション文字列に本当のことが書かれているか調べる

`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` の全ての側面についての詳細な情報が入っており、 ここではより重要な点をカバーするだけにします。