Le module doctest exécute les exemples écrits dans les docstrings

def double(x):
    """Double de x.

    >>> double(3)
    6
    >>> double(-2.5)
    -5.0
    """
    return 2 * x

import doctest
print(doctest.testmod())
# TestResults(failed=0, attempted=2)

Deux tests tentés, zéro échec. Le format est celui de l'interpréteur interactif : la ligne >>> porte l'appel, la suivante le résultat exactement tel qu'il s'affiche — -5.0 et non -5.

Le défaut corrigé. Une documentation ment toujours à la longue : le code évolue, les exemples restent. doctest rend la documentation exécutable, donc réfutable. Si l'on modifiait double en return 3 * x, le test échouerait immédiatement, en désignant la ligne fautive de la docstring.

À l'inverse, c'est un mauvais outil pour tester massivement : on n'écrit pas mille cas dans une docstring. Sa place est celle de l'exemple canonique, celui qu'on lit pour comprendre la fonction — et qu'on a la garantie de pouvoir recopier. Hors programme, mais c'est la mise en pratique la plus directe de « prototyper une fonction ».