Pythonのdoctest入門: ドキュメント文字列をテストとして実行する方法

# example_basic.py

def add(x, y):
    """2つの値を足し算します。

    返り値を検証する基本的な例です。

    >>> add(1, 2)
    3
    >>> add(-1, 5)
    4
    >>> add("a", "b")
    'ab'

    例外を検証することもできます。以下は引数不足の例です。

    >>> add(1)  # 引数が足りないとTypeErrorになります
    Traceback (most recent call last):
        ...
    TypeError: add() missing 1 required positional argument: 'y'
    """
    return x + y

def shout(name):
    """挨拶を大文字で返す関数です。

    >>> shout("Alice")
    'HELLO, ALICE!'
    """
    return f"HELLO, {name.upper()}!"

def hello(name):
    """printの出力も検証できます。

    >>> hello("Bob")
    Hello, Bob!
    """
    print(f"Hello, {name}!")

# example_structured.py
"""モジュール全体の使い方の例です。

>>> add(2, 3)
5
"""

def add(a, b):
    """足し算を行う関数です。

    >>> add(10, 20)
    30
    """
    return a + b

class Accumulator:
    """合計値を貯める簡単なクラスです。

    >>> acc = Accumulator()
    >>> acc.add(5)
    >>> acc.total
    5
    """
    def __init__(self) -> None:
        self.total = 0

    def add(self, value: int) -> None:
        """値を加算します。

        >>> acc = Accumulator()
        >>> acc.add(3)
        >>> acc.total
        3
        """
        self.total += value

python -m doctest -v example_basic.py

# 空白差や長い出力の省略に寛容にする例
python -m doctest -v -o NORMALIZE_WHITESPACE -o ELLIPSIS example_long.py

# example_run_in_code.py

def mul(a, b):
    """掛け算します。

    >>> mul(2, 5)
    10
    """
    return a * b

if __name__ == "__main__":
    # verbose=Trueで詳細表示、戻り値は失敗数と試行数
    import doctest
    result = doctest.testmod(verbose=True)
    print("summary:", result)

def columns(a, b, c):
    """列を整形して出力します。

    # 空白が複数あっても、1個の空白として比較します
    >>> print(columns("A", "BB", "CCC"))  # doctest: +NORMALIZE_WHITESPACE
    A    BB   CCC
    """
    # 幅を揃えるため空白が増える
    return f"{a:>1} {b:>4} {c:>3}"

def make_long_list(n):
    """0からn-1までのリストを作ります。

    >>> items = make_long_list(100)
    >>> items[:10]  # 先頭だけ確認
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

    # 全体をざっくり確認したいときはELLIPSIS
    >>> items  # doctest: +ELLIPSIS
    [0, 1, 2, ..., 97, 98, 99]
    """
    return list(range(n))

import math

def ratio(a, b):
    """比率を返します。

    # 丸めて比較する例
    >>> round(ratio(1, 3), 4)
    0.3333

    # iscloseで真偽を確認する例
    >>> math.isclose(ratio(1, 3), 0.3333333, rel_tol=1e-6)
    True
    """
    return a / b

# example_deterministic.py
import random
from datetime import datetime

def pick_index(rng=None):
    """0〜9の乱数インデックスを返します。

    # シード固定で値を安定化する
    >>> rng = random.Random(0)
    >>> pick_index(rng)
    6
    """
    rng = rng or random.Random()
    return rng.randrange(10)

def iso_now(now_fn=None):
    """現在時刻のISO文字列を返します。

    # 現在時刻を関数として注入して固定化する
    >>> fixed = lambda: datetime(2024, 1, 1, 12, 0, 0)
    >>> iso_now(fixed)
    '2024-01-01T12:00:00'
    """
    now_fn = now_fn or datetime.now
    return now_fn().isoformat()

def must_positive(x):
    """正の数でなければならない例。

    >>> must_positive(-1)  # doctest: +IGNORE_EXCEPTION_DETAIL
    Traceback (most recent call last):
        ...
    ValueError: ...
    """
    if x <= 0:
        raise ValueError(f"must be positive: {x}")
    return x