# `doctest` — Test interactive Python examples

Código fuente: Lib/doctest.py

El módulo `doctest` busca pedazos de texto que lucen como sesiones interactivas de Python, y entonces ejecuta esas sesiones para verificar que funcionen exactamente como son mostradas. Hay varias maneras de usar doctest:

- Para revisar que los docstrings de un módulo están al día al verificar que todos los ejemplos interactivos todavía trabajan como está documentado.

- Para realizar pruebas de regresión al verificar que los ejemplos interactivos de un archivo de pruebas o un objeto de pruebas trabaje como sea esperado.

- Para escribir documentación de tutorial para un paquete, generosamente ilustrado con ejemplos de entrada-salida. Dependiendo si los ejemplos o el texto expositivo son enfatizados, tiene el sabor de «pruebas literarias» o «documentación ejecutable».

Aquí hay un módulo de ejemplo completo pero pequeño:

    """
    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.

        >>> [factorial(n) for n in range(6)]
        [1, 1, 2, 6, 24, 120]
        >>> factorial(30)
        265252859812191058636308480000000
        >>> 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)
        265252859812191058636308480000000

        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

    if __name__ == "__main__":
        import doctest
        doctest.testmod()

Si ejecutas `example.py` directamente desde la línea de comandos, `doctest` hará su magia:

    $ python example.py
    $

¡No hay salida! Eso es normal, y significa que todos los ejemplos funcionaron. Pasa `-v` al script, y `doctest` imprime un registro detallado de lo que está intentando, e imprime un resumen al final:

    $ 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

Y demás, eventualmente terminando con:

    Trying:
        factorial(1e100)
    Expecting:
        Traceback (most recent call last):
            ...
        OverflowError: n too large
    ok
    2 items passed all tests:
       1 tests in __main__
       8 tests in __main__.factorial
    9 tests in 2 items.
    9 passed and 0 failed.
    Test passed.
    $

That’s all you need to know to start making productive use of `doctest`! Jump in. The following sections provide full details. Note that there are many examples of doctests in the standard Python test suite and libraries. Especially useful examples can be found in the standard test file `Lib/test/test_doctest/test_doctest.py`.

## Uso simple: verificar ejemplos en docstrings

The simplest way to start using doctest (but not necessarily the way you’ll continue to do it) is to end each module `M` with:

    if __name__ == "__main__":
        import doctest
        doctest.testmod()

`doctest` then examines docstrings in module `M`.

Ejecutar el módulo como un script causa que los ejemplos en los docstrings se ejecuten y sean verificados:

    python M.py

No mostrará nada a menos que un ejemplo falle, en cuyo caso el ejemplo fallido o ejemplos fallidos y sus causas de la falla son imprimidas a stdout, y la línea final de salida es `***Test Failed*** N failures.`, donde N es el número de ejemplos que fallaron.

Ejecútalo con el modificador `-v` en su lugar:

    python M.py -v

y un reporte detallado de todos los ejemplos intentados es impreso a la salida estándar, junto con resúmenes clasificados al final.

Puedes forzar el modo verboso al pasar `verbose=True` a `testmod()`, o prohibirlo al pasarlo `verbose=False`. En cualquiera de estas casos, `sys.argv` no es examinado por `testmod()` (por lo que pasar o no `-v`, no tiene efecto).

There is also a command line shortcut for running `testmod()`, see section Command-line Usage.

Para más información de `testmod()`, consulte la sección API básica.

## Uso Simple: Verificar ejemplos en un Archivo de Texto

Otra simple aplicación de doctest es probar ejemplos interactivos en un archivo de texto. Esto puede ser hecho con la función `testfile()`:

    import doctest
    doctest.testfile("example.txt")

Este script corto ejecuta y verifica cualquier ejemplo interactivo de Python contenido en el archivo `example.txt`. El contenido del archivo es tratado como si fuese un solo gran docstring; ¡el archivo no necesita contener un programa de Python! Por ejemplo, tal vez `example.txt` contenga esto:

    The ``example`` module
    ======================

    Using ``factorial``
    -------------------

    This is an example text file in reStructuredText format.  First import
    ``factorial`` from the ``example`` module:

        >>> from example import factorial

    Now use it:

        >>> factorial(6)
        120

Ejecutar `doctest.testfile("example.txt")` entonces encuentra el error en esta documentación:

    File "./example.txt", line 14, in example.txt
    Failed example:
        factorial(6)
    Expected:
        120
    Got:
        720

Como con `testmod()`, `testfile()` no mostrará nada a menos que un ejemplo falle. Si un ejemplo no falla, entonces los ejemplos fallidos y sus causas son impresas a stdout, usando el mismo formato como `testmod()`.

Por defecto, `testfile()` busca archivos en el directorio del módulo al que se llama. Véase la sección API básica para una descripción de los argumentos opcionales que pueden ser usados para decirle que busque archivos en otros lugares.

Como `testmod()`, la verbosidad de `testfile()` puede ser establecida con el modificador de la línea de comandos `-v` o con el argumento por palabra clave opcional verbose.

There is also a command line shortcut for running `testfile()`, see section Command-line Usage.

Para más información en `testfile()`, véase la sección API básica.

## Command-line Usage

The `doctest` module can be invoked as a script from the command line:

    python -m doctest [-v] [-o OPTION] [-f] file [file ...]

-v, --verbose

  Detailed report of all examples tried is printed to standard output, along with assorted summaries at the end:

      python -m doctest -v example.py

  This will import `example.py` as a standalone module and run `testmod()` on it. Note that this may not work correctly if the file is part of a package and imports other submodules from that package.

  If the file name does not end with `.py`, `doctest` infers that it must be run with `testfile()` instead:

      python -m doctest -v example.txt

-o, --option <option>

  Option flags control various aspects of doctest’s behavior, see section Banderas de Opción.

  Added in version 3.4.

-f, --fail-fast

  This is shorthand for `-o FAIL_FAST`.

  Added in version 3.4.

## Cómo funciona

Esta sección examina en detalle cómo funciona doctest: qué docstrings revisa, cómo encuentra ejemplos interactivos, qué contexto de ejecución usa, cómo maneja las excepciones, y cómo las banderas pueden ser usadas para controlar su comportamiento. Esta es la información que necesitas saber para escribir ejemplos de doctest; para información sobre ejecutar doctest en estos ejemplos, véase las siguientes secciones.

### ¿Qué docstrings son examinados?

Se busca en el docstring del módulo, y todos los docstrings de las funciones, clases, y métodos. Los objetos importados en el módulo no se buscan.

In addition, there are cases when you want tests to be part of a module but not part of the help text, which requires that the tests not be included in the docstring. Doctest looks for a module-level variable called `__test__` and uses it to locate other tests. If `M.__test__` exists, it must be a dict, and each entry maps a (string) name to a function object, class object, or string. Function and class object docstrings found from `M.__test__` are searched, and strings are treated as if they were docstrings. In output, a key `K` in `M.__test__` appears with name `M.__test__.K`.

For example, place this block of code at the top of `example.py`:

    __test__ = {
        'numbers': """
    >>> factorial(6)
    720

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    """
    }

The value of `example.__test__["numbers"]` will be treated as a docstring and all the tests inside it will be run. It is important to note that the value can be mapped to a function, class object, or module; if so, `doctest` searches them recursively for docstrings, which are then scanned for tests.

Todas las clases encontradas se buscan recursivamente de manera similar, para probar docstrings en sus métodos contenidos y clases anidadas.

### ¿Cómo se reconocen los ejemplos de docstring?

En la mayoría de los casos un copiar y pegar de una sesión de consola interactiva funciona bien, pero doctest no está intentando hacer una emulación exacta de ningún shell específico de Python.

    >>> # comments are ignored
    >>> x = 12
    >>> x
    12
    >>> if x == 13:
    ...     print("yes")
    ... else:
    ...     print("no")
    ...     print("NO")
    ...     print("NO!!!")
    ...
    no
    NO
    NO!!!
    >>>

Cualquier salida esperada debe seguir inmediatamente el final de la línea `'>>>'` o `'...'` conteniendo el código, y la salida esperada (si la hubiera) se extiende hasta el siguiente `'>>>'` o la línea en blanco.

La letra pequeña:

- La salida esperada no puede contener una línea de espacios en blanco, ya que ese tipo de línea se toma para indicar el fin de la salida esperada. Si la salida esperada de verdad contiene una línea en blanco, pon `<BLANKLINE>` en tu ejemplo de doctest en cada lugar donde una línea en blanco sea esperada.

- Todos los caracteres de tabulación se expanden a espacios, usando paradas de tabulación de 8 -columnas. Las tabulaciones generadas por el código en pruebas no son modificadas. Ya que todas las tabulaciones en la salida de prueba son expandidas, significa que si el código de salida incluye tabulaciones, la única manera de que el doctest pueda pasar es si la opción `NORMALIZE_WHITESPACE` o directive está en efecto. Alternativamente, la prueba puede ser reescrita para capturar la salida y compararla a un valor esperado como parte de la prueba. Se llegó a este tratamiento de tabulaciones en la fuente a través de prueba y error, y ha demostrado ser la manera menos propensa a errores de manejarlos. Es posible usar un algoritmo diferente para manejar tabulaciones al escribir una clase `DocTestParser` personalizada.

- La salida a stdout es capturada, pero no la salida a stderr (los rastreos de la excepción son capturados a través de maneras diferentes).

- Si continuas una línea poniendo una barra invertida en una sesión interactiva, o por cualquier otra razón usas una barra invertida, debes usar un docstring crudo, que preservará tus barras invertidas exactamente como las escribes:

      >>> def f(x):
      ...     r'''Backslashes in a raw docstring: m\n'''
      ...
      >>> print(f.__doc__)
      Backslashes in a raw docstring: m\n

  De otra manera, la barra invertida será interpretada como parte de una cadena. Por ejemplo, el `\n` arriba sería interpretado como un carácter de nueva línea. Alternativamente, puedes duplicar cada barra invertida en la versión de doctest (y no usar una cadena de caracteres cruda):

      >>> def f(x):
      ...     '''Backslashes in a raw docstring: m\\n'''
      ...
      >>> print(f.__doc__)
      Backslashes in a raw docstring: m\n

- La columna inicial no importa:

      >>> assert "Easy!"
            >>> import math
                >>> math.floor(1.9)
                1

  y tantos espacios en blanco al principio se eliminan de la salida esperada como aparece en la línea `'>>>'` inicial que empezó el ejemplo.

### ¿Cuál es el contexto de ejecución?

By default, each time `doctest` finds a docstring to test, it uses a shallow copy of `M`’s globals, so that running tests doesn’t change the module’s real globals, and so that one test in `M` can’t leave behind crumbs that accidentally allow another test to work. This means examples can freely use any names defined at top-level in `M`, and names defined earlier in the docstring being run. Examples cannot see names defined in other docstrings.

Puedes forzar el uso de tus propios diccionarios como contexto de ejecución al pasar `globs=your_dict` a `testmod()` o `testfile()` en su lugar.

### ¿Y las excepciones?

No hay problema, siempre que el rastreo sea la única salida producida por el ejemplo: sólo copia el rastreo. [1] Ya que los rastreos contienen detalles que probablemente cambien rápidamente (por ejemplo, rutas de archivos exactas y números de línea), este es un caso donde doctest trabaja duro para ser flexible en lo que acepta.

Ejemplo simple:

    >>> [1, 2, 3].remove(42)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    ValueError: list.remove(x): x not in list

El doctest tiene éxito si se lanza `ValueError`, con el detalle `list.remove(x): x not in list` como se muestra.

La salida esperada para una excepción debe empezar con una cabecera de rastreo, que puede ser una de las siguientes dos líneas, con el mismo sangrado de la primera línea del ejemplo:

    Traceback (most recent call last):
    Traceback (innermost last):

La cabecera de rastreo es seguida por una pila de rastreo opcional, cuyo contenido es ignorado por doctest. La pila de rastreo es típicamente omitida, o copiada palabra por palabra de una sesión interactiva.

La pila de rastreo es seguida por la parte más interesante: la línea o líneas conteniendo el tipo de excepción y detalle. Esto es usualmente la última línea de un rastreo, pero se puede extender a través de múltiples líneas si la excepción tiene un detalle de varias líneas:

    >>> raise ValueError('multi\n    line\ndetail')
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    ValueError: multi
        line
    detail

Las últimas tres líneas (empezando con `ValueError`) son comparados con el tipo de excepción y detalle, y el resto es ignorado.

La mejor práctica es omitir la pila de rastreo, a menos que añada valor de documentación significante al ejemplo. Por lo que el último ejemplo es probablemente mejor como:

    >>> raise ValueError('multi\n    line\ndetail')
    Traceback (most recent call last):
        ...
    ValueError: multi
        line
    detail

Note que los rastreos son tratados de manera especial. En particular, en el ejemplo reescrito, el uso de `...` es independiente de la opción `ELLIPSIS` de doctest. Se pueden excluir los puntos suspensivos en ese ejemplo, así como también pueden haber tres (o trescientas) comas o dígitos, o una transcripción sangrada de un sketch de Monty Python.

Algunos detalles que debes leer una vez, pero no necesitarás recordar:

- Doctest no puede adivinar si tu salida esperada vino de una excepción de rastreo o de una impresión ordinaria. Así que, un ejemplo que espera `ValueError: 42 is prime` pasará, ya sea si de hecho se lance `ValueError` o si el ejemplo simplemente imprime ese texto de rastreo. En la práctica, la salida ordinaria raramente comienza con una línea de cabecera de rastreo, por lo que esto no crea problemas reales.

- Cada línea de la pila de rastreo (si se presenta) debe estar más sangrada que la primera línea del ejemplo, o empezar con un carácter no alfanumérico. la primera línea que sigue a la cabecera de rastreo sangrada de igual forma y empezando con un alfanumérico es considerado el inicio del detalle de la excepción. Por supuesto que esto es lo correcto para rastreos genuinos.

- Cuando se especifica la opción `IGNORE_EXCEPTION_DETAIL` de doctest. todo lo que sigue a los dos puntos más a la izquierda y cualquier otra información del módulo en el nombre de la excepción se ignora.

- El shell interactivo omite la línea de la cabecera de rastreo para algunos `SyntaxError`. Pero doctest usa la línea de la cabecera de rastreo para distinguir excepciones de los que no son. Así que en algunos casos raros donde necesitas probar un `SyntaxError` que omite la cabecera de rastreo, necesitarás poner manualmente la línea de cabecera de rastreo en tu ejemplo de prueba.

- En el caso de algunas excepciones Python señala la posición donde ocurrió el error usando un marcador `^`:

      >>> 1 + None
        File "<stdin>", line 1
          1 + None
          ~~^~~~~~
      TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'

  Ya que las líneas mostrando la posición del error vienen antes del tipo de excepción y detalle, no son revisadas por doctest. Por ejemplo, el siguiente test pasaría, a pesar de que pone el marcador `^` en la posición equivocada:

      >>> 1 + None
        File "<stdin>", line 1
          1 + None
          ^~~~~~~~
      TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'

### Banderas de Opción

Varias banderas de opción controlan diversos aspectos del comportamiento de doctest. Los nombres simbólicos para las banderas son proporcionados como constantes del módulo, que se pueden conectar mediante *OR* bit a bit y pasar a varias funciones. Los nombres también pueden ser usados en las directivas de doctest, y se pueden pasar a la interfaz de la línea de comandos de doctest a través de la opción `-o`.

El primer grupo de opciones definen las semánticas de la prueba, controlando aspectos de cómo doctest decide si la salida de hecho concuerda con la salida esperada del ejemplo:

doctest.DONT_ACCEPT_TRUE_FOR_1

  Por defecto, si un bloque de salida esperada contiene sólo `1`, se considera igual a un bloque de salida real conteniendo sólo `1` o `true`, y similarmente para `0` contra `False`. Cuando se especifica `DONT_ACCEPT_TRUE_FOR_1``, no se permite ninguna sustitución. El comportamiento por defecto atiende a que Python cambió el tipo de retorno de muchas funciones de enteros a booleanos; los doctest esperando salidas «de pequeño enteros» todavía trabajan en estos casos. Esta opción probablemente se vaya, pero no por muchos años.

doctest.DONT_ACCEPT_BLANKLINE

  Por defecto, si un bloque de salida esperada contiene una línea que sólo tiene la cadena de caracteres `<BLANKLINE>`, entonces esa línea corresponderá a una línea en blanco en la salida real. Ya que una línea en blanca auténtica delimita la salida esperada, esta es la única manera de comunicar que una línea en blanco es esperada. Cuando se especifica `DONT_ACCEPT_BLANKLINE`, esta substitución no se permite.

doctest.NORMALIZE_WHITESPACE

  Cuando se especifica, todas las secuencias de espacios en blanco (vacías y nuevas líneas) son tratadas como iguales. Cualquier secuencia de espacios en blanco dentro de la salida esperada corresponderá a cualquier secuencia de espacios en blanco dentro de la salida real. Por defecto, los espacios en blanco deben corresponderse exactamente. `NORMALIZE_WHITESPACE` es especialmente útil cuando una línea de la salida esperada es muy larga, y quieres envolverla a través de múltiples líneas en tu código fuente.

doctest.ELLIPSIS

  Cuando se especifica, un marcador de puntos suspensivos (`...`) en la salida esperada puede corresponder a cualquier cadena de caracteres en la salida real. Esto incluye las cadenas de caracteres que abarcan límites de líneas, y cadenas de caracteres vacías, por lo que es mejor mantener su uso simple. Usos complicados pueden conducir a los mismo tipos de sorpresa de «ups, coincidió demasiado» que `.*` es propenso a hacer en expresiones regulares.

doctest.IGNORE_EXCEPTION_DETAIL

  Cuando se especifica, las excepciones que doctest espera, pasarán siempre que sea lanzada una excepción del tipo esperado, incluso si los detalles (mensaje y nombre completo de la excepción) no coinciden.

  Por ejemplo, si se espera `ValueError: 42`, el test pasará si la verdadera excepción lanzada es `ValueError: 3*14`, pero fallará si es lanzada un `TypeError`. También ignorará cualquier nombre completo incluido antes de la clase de la excepción, lo cual puede variar entre implementaciones y versiones de Python y bibliotecas/código en uso. Por lo tanto, las tres variaciones funcionarán con la bandera especificada:

      >>> raise Exception('message')
      Traceback (most recent call last):
      Exception: message

      >>> raise Exception('message')
      Traceback (most recent call last):
      builtins.Exception: message

      >>> raise Exception('message')
      Traceback (most recent call last):
      __main__.Exception: message

  Tenga en cuenta que `ELLIPSIS` también puede ser usado para ignorar detalles del mensaje de la excepción, pero dicha prueba aún podría fallar si el nombre del modulo está presente o si hay coincidencias exactas.

  Distinto en la versión 3.2: `IGNORE_EXCEPTION_DETAIL` también ignora cualquier información relacionada al módulo conteniendo la excepción bajo prueba.

doctest.SKIP

  Cuando se especifica, no ejecuta el ejemplo del todo. Puede ser útil en contextos donde los ejemplos de doctest sirven como documentación y casos de prueba a la vez, y un ejemplo debe ser incluido para propósitos de documentación, pero no debe ser revisado. P. ej., la salida del ejemplo puede ser aleatoria, o el ejemplo puede depender de recursos que no estarían disponibles para el controlador de pruebas.

  La bandera SKIP también se puede usar para temporalmente «quitar» ejemplos.

doctest.COMPARISON_FLAGS

  Una máscara de bits o juntadas lógicamente todas las banderas de arriba.

El segundo grupo de opciones controla cómo las fallas de las pruebas son reportadas:

doctest.REPORT_UDIFF

  Cuando se especifica, las fallas que involucran salidas multilínea esperadas y reales son mostradas usando una diferencia (diff) unificada.

doctest.REPORT_CDIFF

  Cuando se especifica, las fallas que involucran salidas multilínea esperadas y reales se mostrarán usando una diferencia (diff) contextual.

doctest.REPORT_NDIFF

  Cuando se especifica, las diferencias son computadas por `difflib.Differ`, usando el mismo algoritmo que la popular utilidad `ndiff.py`. Este es el único método que marca diferencias dentro de líneas también como a través de líneas. Por ejemplo, si una línea de salida esperada contiene el dígito `1` donde la salida actual contiene la letra `l`, se inserta una línea con una marca de inserción marcando la posición de las columnas que no coinciden.

doctest.REPORT_ONLY_FIRST_FAILURE

  Cuando se especifica, muestra el primer ejemplo fallido en cada doctest, pero suprime la salida para todos ejemplos restantes. Esto evitará que doctest reporte los ejemplos correctos que se rompen por causa de fallos tempranos; pero también puede esconder ejemplos incorrectos que fallen independientemente de la primera falla. Cuando se especifica `REPORT_ONLY_FIRST_FAILURE`, los ejemplos restantes aún se ejecutan, y aún cuentan para el número total de fallas reportadas, sólo se suprime la salida.

doctest.FAIL_FAST

  Cuando se especifica, sale después del primer ejemplo fallido y no intenta ejecutar los ejemplos restantes. Por consiguiente, el número de fallas reportadas será como mucho 1. Esta bandera puede ser útil durante la depuración, ya que los ejemplos después de la primera falla ni siquiera producirán salida de depuración.

doctest.REPORTING_FLAGS

  Una máscara de bits o todas las banderas de reporte arriba combinadas.

También hay una manera de registrar nombres de nuevas opciones de banderas, aunque esto no es útil a menos que intentes extender `doctest` a través de herencia:

doctest.register_optionflag(name)

  Crea una nueva bandera de opción con un nombre dado, y retorna el valor entero de la nueva bandera. se puede usar `register_optionflag()` cuando se hereda `OutputChecker` o `DocTestRunner` para crear nuevas opciones que sean compatibles con tus clases heredadas. `register_optionflag()` siempre debe ser llamado usando la siguiente expresión:

      MY_FLAG = register_optionflag('MY_FLAG')

### Directivas

Se pueden usar las directivas de doctest para modificar las banderas de opción para un ejemplo individual. Las directivas de doctest son comentarios de Python especiales que siguen el código fuente de un ejemplo:

    directive             ::= "#" "doctest:" directive_options
    directive_options     ::= directive_option ("," directive_option)*
    directive_option      ::= on_or_off directive_option_name
    on_or_off             ::= "+" | "-"
    directive_option_name ::= "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...

No se permite el espacio en blanco entre el `+` o `-` y el nombre de la opción de directiva (directive option name). El nombre de la opción de directiva puede ser cualquiera de los nombres de las banderas de opciones explicadas arriba.

Las directivas de doctest de un ejemplo modifican el comportamiento de doctest para ese único ejemplo. Usa `+` para habilitar el comportamiento nombrado, o `-` para deshabilitarlo.

Por ejemplo, esta prueba se ejecuta con normalidad:

    >>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
    [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
    10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

Sin la directiva esto fallaría, porque de hecho la salida verdadera no tiene dos espacios en blanco antes de cada elemento de la lista, y además porque la la salida verdadera está en una sola línea. Mientras tanto, la siguiente prueba también pasa, y de la misma forma requiere de directivas para hacerlo:

    >>> print(list(range(20)))  # doctest: +ELLIPSIS
    [0, 1, ..., 18, 19]

Se pueden usar varias directivas en una sola línea, separadas por comas:

    >>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
    [0,    1, ...,   18,    19]

Si las diferentes directivas se usan para un sólo ejemplo, entonces estas se combinarán:

    >>> print(list(range(20)))  # doctest: +ELLIPSIS
    ...                         # doctest: +NORMALIZE_WHITESPACE
    [0,    1, ...,   18,    19]

Como se muestran en los ejemplos anteriores, puedes añadir líneas de `...` a tus ejemplos conteniendo sólo directivas. Puede ser útil cuando un ejemplo es demasiado largo para que una directiva pueda caber cómodamente en la misma línea:

    >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
    ... # doctest: +ELLIPSIS
    [0, ..., 4, 10, ..., 19, 30, ..., 39]

Tenga en cuenta que ya que todas las opciones están deshabilitadas por defecto, y las directivas sólo aplican a los ejemplos en los que aparecen, habilitarlas (a través de `+` en la directiva) usualmente es la única opción significativa. Sin embargo, las banderas de opciones también pueden ser pasadas a funciones que ejecutan doctests, estableciendo valores por defecto diferentes. En tales casos, deshabilitar una opción a través de `-` en una directiva puede ser útil.

### Advertencias

`doctest` es serio acerca de requerir coincidencias exactas en la salida esperada. Si incluso un solo carácter no coincide, el test falla. Esto probablemente te sorprenderá algunas veces, mientras aprendes exactamente lo que Python asegura y no asegura sobre la salida. Por ejemplo, cuando se imprime un conjunto, Python no asegura que el elemento sea impreso en ningún orden particular, por lo que una prueba como:

    >>> foo()
    {"spam", "eggs"}

¡es vulnerable! Una solución puede ser hacer:

    >>> foo() == {"spam", "eggs"}
    True

en su lugar. Otra es hacer

    >>> d = sorted(foo())
    >>> d
    ['eggs', 'spam']

Existen otros casos, pero ya captas la idea.

Otra mala idea es imprimir elementos que tienen la dirección de un objeto, como por ejemplo

    >>> id(1.0)  # certain to fail some of the time
    7948648
    >>> class C: pass
    >>> C()  # the default repr() for instances embeds an address
    <C object at 0x00AC18F0>

Con la directiva `ELLIPSIS` podemos sacar ventaja del último ejemplo:

    >>> C()  # doctest: +ELLIPSIS
    <C object at 0x...>

Los números de coma flotante también son sujetos a pequeñas variaciones de la salida a través de las plataformas, porque Python defiere a la librería C de la plataforma para el formato de flotantes, y las librerías de C varían extensamente en calidad aquí.

    >>> 1./7  # risky
    0.14285714285714285
    >>> print(1./7) # safer
    0.142857142857
    >>> print(round(1./7, 6)) # much safer
    0.142857

Números de la forma `I/2.**J` son seguros a lo largo de todas las plataformas, y yo frecuentemente planeo ejemplos de doctest para producir números de esa forma:

    >>> 3./4  # utterly safe
    0.75

Las facciones simples también son más fáciles de entender para las personas, y eso conduce a una mejor documentación.

## API básica

Las funciones `testmod()` y `testfile()` proporcionan una interfaz simple para doctest que debe ser suficiente para la mayoría de los usos básicos. Para una introducción menos formal a estas funciones, véase las secciones Uso simple: verificar ejemplos en docstrings y Uso Simple: Verificar ejemplos en un Archivo de Texto.

doctest.testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None)

  Todos los argumentos excepto filename son opcionales, y deben ser especificados en forma de palabras claves.

  Prueba los ejemplos en el archivo con nombre filename. Retorna `(failure_count, test_count)`.

  El argumento opcional module_relative especifica cómo el nombre de archivo debe ser interpretado:

  - Si module_relative es `True` (el valor por defecto), entonces filename especifica una ruta relativa al módulo que es independiente del SO. Por defecto, esta ruta es relativa al directorio del módulo que lo invoca; pero si el argumento package es especificado, entonces es relativo a ese paquete. Para asegurar la independencia del SO, filename debe usar caracteres `/` para separar segmentos, y no puede ser una ruta absoluta (por ejemplo., no puede empezar con `/`).

  - Si module_relative es `False`, entonces filename especifica una ruta especifica del SO. La ruta puede ser absoluta o relativa; las rutas relativas son resueltas con respecto al directorio de trabajo actual.

  El argumento opcional name proporciona el nombre de la prueba; por defecto, o si es `None`, se usa `os.path.basename(filename)`.

  El argumento opcional package es un paquete de Python o el nombre de una paquete de Python cuyo directorio debe ser usado como el directorio base para un nombre de archivo relativo al módulo. Si no se especifica ningún paquete, entonces el directorio del módulo que invoca se usa como el directorio base para los nombres de archivos relativos al módulo. Es un error especificar package si module_relative es `False`.

  El argumento opcional globs proporciona un diccionario a ser usado como los globales cuando se ejecuten los ejemplos. Se crea una nueva copia superficial de este diccionario para el doctest, por lo que sus ejemplos empiezan con una pizarra en blanco. Por defecto, o si es `None`, se usa un nuevo diccionario vacío.

  El argumento opcional extraglobs proporciona un diccionario mezclado con los globales usados para ejecutar ejemplos. Funciona como `dict.update()`: si globs y extraglobs tienen una clave en común, el valor asociado en extraglobs aparece en el diccionario combinado. Por defecto, o si es `None`, no se usa ninguna variable global. Es una característica avanzada que permite la parametrización de doctests. Por ejemplo, un doctest puede ser escribo para una clase base, usando un nombre genérico para la clase, y luego reusado para probar cualquier número de clases heredadas al pasar un diccionario de extraglobs mapeando el nombre genérico a la clase heredada para ser probada.

  El argumento opcional verbose imprime un montón de cosas si es verdadero, e imprime sólo las fallas si es falso; por defecto, o si es `None`, es verdadero si y sólo si `'-v'` está en `sys.argv`.

  El argumento opcional report imprime un resumen al final cuando es verdadero; si no, no imprime nada al final. En modo verboso (verbose), el resumen es detallado; si no, el resumen es muy corto (de hecho, vacío si todos las pruebas pasan).

  El argumento opcional optionflags (valor por defecto 0) toma las banderas de opciones juntadas lógicamente por un OR. Véase la sección Banderas de Opción.

  El argumento opcional raise_on_error tiene como valor por defecto false. Si es true, se lanza una excepción sobre la primera falla o excepción no esperada en un ejemplo. Esto permite que los fallos sean depurados en un análisis a posteriori. El comportamiento por defecto es continuar corriendo los ejemplos.

  El argumento opcional parser especifica un `DocTestParser` (o subclase) que debe ser usado para extraer las pruebas de los archivos. Su valor por defecto es un analizador sintáctico normal (i.e., `DocTestParser()`).

  El argumento opcional encoding especifica una codificación que debe ser usada para convertir el archivo a unicode.

doctest.testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)

  Todos los argumentos son opcionales, y todos excepto por m deben ser especificados en forma de palabras claves.

  Prueba los ejemplos en los docstring de las funciones y clases alcanzables desde el módulo m (o desde el módulo `__main__` si m no es proporcionado o es `None`), empezando con `m.__doc__`.

  Also test examples reachable from dict `m.__test__`, if it exists. `m.__test__` maps names (strings) to functions, classes and strings; function and class docstrings are searched for examples; strings are searched directly, as if they were docstrings.

  Sólo se buscan los docstrings anexados a los objetos pertenecientes al módulo m.

  Retorna `(failure_count, test_count)`.

  El argumento opcional name proporciona el nombre del módulo; por defecto, o si es `None`, se usa `m.__name__`.

  Optional argument exclude_empty defaults to false. If true, objects for which no doctests are found are excluded from consideration. The default is a backward compatibility hack, so that code still using `doctest.master.summarize` in conjunction with `testmod()` continues to get output for objects with no tests. The exclude_empty argument to the newer `DocTestFinder` constructor defaults to true.

  Los argumentos opcionales extraglobs, verbose, report, optionflags, raise_on_error, y globs son los mismos en cuanto a la función `testfile()` arriba, excepto que globs es por defecto `m.__dict__`.

doctest.run_docstring_examples(f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0)

  Prueba los ejemplos asociados con el objeto f; por ejemplo, f puede ser una cadena de caracteres, un módulo, una función, o un objeto clase.

  Una copia superficial del diccionario del argumento globs se usa para la ejecución del contexto.

  Se usa el argumento opcional name en mensajes de fallos, y por defecto es `"NoName"`.

  Si el argumento opcional verbose es verdadero, la salida se genera incluso si no hay fallas. Por defecto, la salida se genera sólo en caso de la falla de un ejemplo.

  El argumento opcional compileflags proporciona el conjunto de banderas que se deben usar por el compilador de Python cuando se corran los ejemplos. Por defecto, o si es `None`, las banderas se deducen correspondiendo al conjunto de características futuras encontradas en globs.

  El argumento opcional optionflags trabaja con respecto a la función `testfile()` de arriba.

## API de unittest

As your collection of doctest’ed modules grows, you’ll want a way to run all their doctests systematically. `doctest` provides two functions that can be used to create `unittest` test suites from modules and text files containing doctests. To integrate with `unittest` test discovery, include a load_tests function in your test module:

    import unittest
    import doctest
    import my_module_with_doctests

    def load_tests(loader, tests, ignore):
        tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
        return tests

Hay dos funciones principales para crear instancias de `unittest.TestSuite` desde los archivos de texto y módulos con doctests:

doctest.DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)

  Convierte las pruebas de doctest de uno o más archivos de texto a una `unittest.TestSuite`.

  El `unittest.TestSuite` que se retorne será ejecutado por el framework de unittest y ejecuta los ejemplos interactivos en cada archivo. Si un ejemplo en cualquier archivo falla, entonces la prueba unitaria sintetizada falla, y una excepción `failureException` se lanza mostrando el nombre del archivo conteniendo la prueba y un número de línea (algunas veces aproximado).

  Pasa una o más rutas (como cadenas de caracteres) a archivos de texto para ser examinados.

  Se pueden proporcionar las opciones como argumentos por palabra clave:

  El argumento opcional module_relative especifica cómo los nombres de archivos en paths se deben interpretar:

  - Si module_relative is `True` (el valor por defecto), entonces cada archivo de nombre en paths especifica una ruta relativa al módulo independiente del SO. Por defecto, esta ruta es relativa al directorio del módulo lo está invocando; pero si se especifica el argumento package, entonces es relativo a ese paquete. Para asegurar la independencia del SO, cada nombre de archivo debe usar caracteres `/` para separar los segmentos de rutas, y puede no ser una ruta absoluta (i.e., puede no empezar con `/`).

  - Si module_relative es `False`, entonces cada archivo de nombre en paths especifica una ruta especifica al SO. La ruta puede ser absoluta o relativa; las rutas relativas son resueltas con respecto a directorio de trabajo actual.

  El argumento opcional package es un paquete de Python o el nombre de un paquete de Python cuyo directorio debe ser usado como el directorio base para los nombres de archivos relativos al módulo en paths. Si no se especifica ningún paquete, entonces el directorio del módulo que lo está invocando se usa como el directorio base para los archivos de nombres relativos al módulo. Es un error especificar package si module_relative es `False`.

  El argumento opcional setUp especifica una función de configuración para el banco de pruebas. Es invocado antes de ejecutar las pruebas en cada archivo. La función setUp se pasará a un objeto `DocTest`. La función setUp puede acceder a las variables globales de prueba como el atributo globs de la prueba pasada.

  El argumento opcional tearDown especifica una función de destrucción para el banco de pruebas. Es invocado después de ejecutar las pruebas en cada archivo. Se pasará un objeto `DocTest` a la función tearDown. La función setUp de configuración puede acceder a los globales de la prueba como el atributo globs de la prueba pasada.

  El argumento opcional globs es un diccionario que contiene las variables globales iniciales para las pruebas. Se crea una nueva copia de este diccionario para cada prueba. Por defecto, globs es un nuevo diccionario vacío.

  El argumento opcional optionflags especifica las opciones de doctest por defecto para las pruebas, creado al juntar lógicamente las opciones de bandera individuales. Véase la sección Banderas de Opción. Véase la función `set_unittest_reportflags()` abajo para una mejor manera de definir las opciones de informe.

  El argumento opcional parser especifica un `DocTestParser` (o subclase) que debe ser usado para extraer las pruebas de los archivos. Su valor por defecto es un analizador sintáctico normal (i.e., `DocTestParser()`).

  El argumento opcional encoding especifica una codificación que debe ser usada para convertir el archivo a unicode.

  Se añade el global `__file__` a los globales proporcionados a los doctests cargados desde un archivo de texto usando `DocFileSuite()`.

doctest.DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, optionflags=0, checker=None)

  Convierte las pruebas de doctest para un módulo a un `unittest.TestSuite`.

  El `unittest.TestSuite` que se retorne será ejecutado por el framework de unittest y corre cada doctest en el módulo. Si cualquiera de los doctests falla, entonces la prueba unitaria combinada falla, y se lanza una excepción `failureException` mostrando el nombre del archivo que contiene la prueba y un número de línea (a veces aproximado).

  El argumento opcional module proporciona el módulo a probar. Puede ser un objeto de módulo o un nombre (posiblemente punteado) de módulo. Si no se especifica, se usa el módulo que invoca esta función.

  El argumento opcional globs es un diccionario que contiene las variables globales iniciales para las pruebas. Se crea una nueva copia de este diccionario para cada prueba. Por defecto, globs es un nuevo diccionario vacío.

  El argumento opcional extraglobs especifica un conjunto de variables globales adicionales que son mezcladas con globs. Por defecto, no se usa ningún global adicional.

  El argumento opcional test_finder es el objeto `DocTestFinder` (o un reemplazo directo) que se usa para extraer doctests desde el módulo.

  Los argumentos opcionales setUp, tearDown, y optionflags son lo mismo con respecto a la función `DocFileSuite()` arriba.

  Esta función usa la misma técnica de búsqueda que `testmod()`.

  Distinto en la versión 3.5: `DocTestSuite()` retorna un `unittest.TestSuite` vacío si module no contiene ningún docstring en vez de lanzar un `ValueError`.

exception doctest.failureException

  When doctests which have been converted to unit tests by `DocFileSuite()` or `DocTestSuite()` fail, this exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.

Under the covers, `DocTestSuite()` creates a `unittest.TestSuite` out of `doctest.DocTestCase` instances, and `DocTestCase` is a subclass of `unittest.TestCase`. `DocTestCase` isn’t documented here (it’s an internal detail), but studying its code can answer questions about the exact details of `unittest` integration.

Similarly, `DocFileSuite()` creates a `unittest.TestSuite` out of `doctest.DocFileCase` instances, and `DocFileCase` is a subclass of `DocTestCase`.

So both ways of creating a `unittest.TestSuite` run instances of `DocTestCase`. This is important for a subtle reason: when you run `doctest` functions yourself, you can control the `doctest` options in use directly, by passing option flags to `doctest` functions. However, if you’re writing a `unittest` framework, `unittest` ultimately controls when and how tests get run. The framework author typically wants to control `doctest` reporting options (perhaps, e.g., specified by command line options), but there’s no way to pass options through `unittest` to `doctest` test runners.

Por esta razón, `doctest` también admite una noción de banderas de informe de `doctest` específicas para la compatibilidad con `unittest`, a través de esta función:

doctest.set_unittest_reportflags(flags)

  Establece las banderas de informe de `doctest` a usar.

  El argumento flags toma la combinación por el operador OR de las banderas de opciones. Véase la sección Banderas de Opción. Sólo se pueden usar las «banderas de informe».

  This is a module-global setting, and affects all future doctests run by module `unittest`: the `runTest()` method of `DocTestCase` looks at the option flags specified for the test case when the `DocTestCase` instance was constructed. If no reporting flags were specified (which is the typical and expected case), `doctest`’s `unittest` reporting flags are bitwise ORed into the option flags, and the option flags so augmented are passed to the `DocTestRunner` instance created to run the doctest. If any reporting flags were specified when the `DocTestCase` instance was constructed, `doctest`’s `unittest` reporting flags are ignored.

  La función retorna el valor de las banderas de informe de `unittest` en efecto antes de que la función fuera invocada.

## API avanzada

La API básica es un simple envoltorio que sirve para hacer los doctest fáciles de usar. Es bastante flexible, y debe cumplir las necesidades de la mayoría de los usuarios; si requieres un control más preciso en las pruebas, o deseas extender las capacidades de doctest, entonces debes usar la API avanzada.

La API avanzada gira en torno a dos clases contenedoras, que se usan para guardar los ejemplos interactivos extraídos de los casos doctest:

- `Example`: Un statement de Python, emparejado con su salida esperada.

- `DocTest`: Una colección de clases `Example`, típicamente extraídos de un sólo docstring o archivo de texto.

Se definen clases de procesamiento adicionales para encontrar, analizar sintácticamente, y ejecutar, y comprobar ejemplos de doctest:

- `DocTestFinder`: Encuentra todos los docstrings en un módulo dado, y usa un `DocTestParser` para crear un `DocTest` de cada docstring que contiene ejemplos interactivos.

- `DocTestParser`: Crea un objeto `DocTest` de una cadena de caracteres (tal como un docstring de un objeto).

- `DocTestRunner`: Ejecuta los ejemplos en un `DocTest`, y usa un `OutputChecker` para verificar su salida.

- `OutputChecker`: Compara la salida real de un ejemplo de doctest con la salida esperada, y decide si coinciden.

Las relaciones entre estas clases de procesamiento se resumen en el siguiente diagrama:

                                list of:
    +------+                   +---------+
    |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
    +------+    |        ^     +---------+     |       ^    (printed)
                |        |     | Example |     |       |
                v        |     |   ...   |     v       |
               DocTestParser   | Example |   OutputChecker
                               +---------+

### Objetos DocTest

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)

  Una colección de ejemplos de doctest que deben ejecutarse en un sólo nombre de espacios. Se usan los argumentos del constructor para inicializar los atributos de los mismos nombres.

  `DocTest` define los siguientes atributos. Son inicializados por el constructor, y no deben ser modificados directamente.

  examples

    Una lista de objetos `Example` codificando los ejemplos interactivos de Python individuales que esta prueba debe ejecutar.

  globs

    El nombre de espacios (alias globals) en que los ejemplos se deben ejecutar. Este es un diccionario que mapea nombres a valores. Cualquier cambio al nombre de espacios hecho por los ejemplos (tal como juntar nuevas variables) se reflejará en `globs` después de que se ejecute la prueba.

  name

    Un nombre de cadena de caracteres que identifica el `DocTest`. Normalmente, este es el nombre del objeto o archivo del que se extrajo la prueba.

  filename

    El nombre del archivo del que se extrajo este `DocTest`; o `None` si el nombre del archivo se desconoce, o si `DocTest` no se extrajo de un archivo.

  lineno

    El número de línea dentro de `filename` donde este `DocTest` comienza, o `None` si el número de línea no está disponible. Este número de línea es comienza en 0 con respecto al comienzo del archivo.

  docstring

    La cadena de caracteres del que se extrajo la cadena, o `None` si la cadena no está disponible, o si la prueba no se extrajo de una cadena de caracteres.

### Objetos Example

class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)

  Un sólo ejemplo interactivo, que consta de una sentencia de Python y su salida esperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

  La clase `Example` define los siguientes atributos. Son inicializados por el constructor, y no deben ser modificados directamente.

  source

    Una cadena de caracteres que contiene el código fuente del ejemplo. Este código fuente consiste de una sola sentencia Python, y siempre termina en una nueva línea; el constructor añade una nueva línea cuando sea necesario.

  want

    La salida esperada de ejecutar el código fuente del ejemplo (o desde la salida estándar, o un seguimiento en caso de una excepción). `wants` termina con una nueva línea a menos que no se espera ninguna salida, en cuyo caso es una cadena vacía. El constructor añade una nueva línea cuando sea necesario.

  exc_msg

    El mensaje de excepción que el ejemplo genera, si se espera que el ejemplo genere una excepción; o `None` si no se espera que genere una excepción. Se compara este mensaje de excepción con el valor de retorno de `traceback.format_exception_only()`. `exc_msg` termina con una nueva línea a menos que sea `None`. El constructor añade una nueva línea si se necesita.

  lineno

    El número de línea dentro de la cadena de caracteres que contiene este ejemplo donde el ejemplo comienza. Este número de línea comienza en 0 con respecto al comienzo de la cadena que lo contiene.

  indent

    La sangría del ejemplo en la cadena que lo contiene; i.e., el número de caracteres de espacio que preceden la primera entrada del ejemplo.

  options

    A dictionary mapping from option flags to `True` or `False`, which is used to override default options for this example. Any option flags not contained in this dictionary are left at their default value (as specified by the `DocTestRunner`’s optionflags). By default, no options are set.

### Objetos DocTestFinder

class doctest.DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

  Una clase de procesamiento que se usa para extraer los `DocTest` que son relevantes para un objeto dado, desde su docstring y los docstring de sus objetos contenidos. Se puede extraer los `DocTest` de los módulos, clases, funciones, métodos, métodos estáticos, métodos de clase, y propiedades.

  Se puede usar el argumento opcional verbose para mostrar los objetos buscados por finder. Su valor por defecto es `False` (ninguna salida).

  El argumento opcional parser especifica el objeto `DocTestParser` (o un reemplazo directo) que se usa para extraer doctests desde docstrings.

  Si el argumento opcional recurse es falso, entonces el método `DocTestFinder.find()` sólo examinará el objeto dado, y no cualquier objeto contenido.

  Si el argumento opcional exclude_empty es falso, entonces `DocTestFinder.find()` incluirá pruebas para objetos con docstrings vacíos.

  `DocTestFinder` define los siguientes métodos:

  find(obj[, name][, module][, globs][, extraglobs])

    Retorna una lista de los `Doctest` que se definen por el docstring de obj, o por cualquiera de los docstring de sus objetos contenidos.

    El argumento opcional name especifica el nombre del objeto; este nombre será usado para construir los nombres de los `DocTest` retornados. Si name no se especifica, entonces se usa `obj.__name__`.

    El parámetro opcional module es el módulo que contiene el objeto dado. Si no se especifica el módulo o si es `None`, entonces el buscador de pruebas tratará de determinar automáticamente el módulo correcto. Se usa el módulo del objeto:

    - Como un espacio de nombres por defecto, si no se especifica globs.

    - Para evitar que DocTestFinder extraiga DocTests desde objetos que se importan desde otros módulos. (Se ignoran objetos contenidos con módulos aparte de module.)

    - Para encontrar el nombre del archivo conteniendo el objeto.

    - Para ayudar a encontrar el número de línea del objeto dentro de su archivo.

    Si module es falso, no se hará ningún intento de encontrar el módulo. Es poco claro, de uso mayormente para probar doctest en si mismo: si module es `False`, o es `None` pero no se puede encontrar automáticamente, entonces todos los objetos se consideran que pertenecen al módulo (inexistente), por lo que todos los objetos contenidos se buscarán (recursivamente) por doctests.

    Los globales para cada `DocTest` se forma al combinar globs y extraglobs (los enlaces en extraglobs anulan los enlaces en globs). Se crea una nueva copia superficial del diccionario de globales para cada `DocTest`. Si globs no se especifica, entonces su valor por defecto es el __dict__ del módulo, si se especifica, o es `{}` de lo contrario, si extraglobs no se especifica, entonces su valor por defecto es `{}`.

### Objetos DocTestParser

class doctest.DocTestParser

  Un clase de procesamiento usada para extraer ejemplos interactivos de una cadena de caracteres, y usarlos para crear un objeto `DocTest`.

  `DocTestParser` define los siguientes métodos:

  get_doctest(string, globs, name, filename, lineno)

    Extrae todos los ejemplos de doctest de una cadena dada, y los recolecta en un objeto `DocTest`.

    globs, name, filename, y lineno son atributos para el nuevo objeto `DocTest`. Véase la documentación de `DocTest` para más información.

  get_examples(string, name='<string>')

    Extrae todos los ejemplos de la cadena de caracteres dada, y los retorna como una lista de objetos `Example`. Los números de línea empiezan en 0. El argumento opcional name es una nombre identificando esta cadena, y sólo es usada para mensajes de errores.

  parse(string, name='<string>')

    Divide el string dado en ejemplos y texto intermedio, y los retorna como una lista que alterna entre objetos `Example` y cadenas de caracteres. Los números de línea para los objetos `Example` empiezan en 0. El argumento opcional name es un nombre identificando esta cadena, y sólo se usa en mensajes de error.

### Objetos DocTestRunner

class doctest.DocTestRunner(checker=None, verbose=None, optionflags=0)

  Una clase de procesamiento usada para ejecutar y verificar los ejemplos interactivos en un `DocTest`.

  La comparación entre salidas esperadas y salidas reales se hace por un `OutputChecker`. Esta comparación puede ser personalizada con un número de banderas de opción; véase la sección Banderas de Opción para más información. Si las banderas de opción son insuficientes, entonces la comparación también puede ser personalizada al pasar una subclase de `OutputChecker` al constructor.

  The test runner’s display output can be controlled in two ways. First, an output function can be passed to `run()`; this function will be called with strings that should be displayed. It defaults to `sys.stdout.write`. If capturing the output is not sufficient, then the display output can be also customized by subclassing DocTestRunner, and overriding the methods `report_start()`, `report_success()`, `report_unexpected_exception()`, and `report_failure()`.

  El argumento por palabra clave opcional checker especifica el objeto `OutputChecker` (o un reemplazo directo) que se debe usar para comparar las salidas esperadas con las salidas reales de los ejemplos de doctest.

  El argumento por palabra clave opcional verbose controla la verbosidad de `DocTestRunner`. Si verbose es `True`, entonces la información de cada ejemplo se imprime , mientras se ejecuta. Si verbose es `False`, entonces sólo las fallas se imprimen. Si verbose no se especifica, o es `None`, entonces la salida verbosa se usa si y sólo se usa el modificador de la línea de comandos `-v`.

  El argumento por palabra clave opcional optionflags se puede usar para controlar cómo el test runner compara la salida esperada con una salida real, y cómo muestra las fallas. Para más información, véase la sección Banderas de Opción.

  `DocTestRunner` defines the following methods:

  report_start(out, test, example)

    Notifica que el test runner está a punto de procesar el ejemplo dado. Este método es proporcionado para permitir que clases heredadas de `DocTestRunner` personalicen su salida; no debe ser invocado directamente.

    example es el ejemplo a punto de ser procesado. test es la prueba que contiene a example. out es la función de salida que se pasó a `DocTestRunner.run()`.

  report_success(out, test, example, got)

    Notifica que el ejemplo dado se ejecutó correctamente. Este método es proporcionado para permitir que las clases heredadas de `DocTestRunner` personalicen su salida; no debe ser invocado directamente.

    example es el ejemplo a punto de ser procesado. got es la salida real del ejemplo. test es la prueba conteniendo example. out es la función de salida que se pasa a `DocTestRunner.run()`.

  report_failure(out, test, example, got)

    Notifica que el ejemplo dado falló. Este método es proporcionado para permitir que clases heredadas de `DocTestRunner` personalicen su salida; no debe ser invocado directamente.

    example es el ejemplo a punto de ser procesado. got es la salida real del ejemplo. test es la prueba conteniendo example. out es la función de salida que se pasa a `DocTestRunner.run()`.

  report_unexpected_exception(out, test, example, exc_info)

    Notifica que el ejemplo dado lanzó una excepción inesperada. Este método es proporcionado para permitir que las clases heredadas de `DocTestRunner` personalicen su salida; no debe ser invocado directamente.

    example es el ejemplo a punto de ser procesado, exc_info es una tupla que contiene información sobre la excepción inesperada (como se retorna por `sys.exc_info()`). test es la prueba conteniendo example. out es la función de salida que debe ser pasada a `DocTestRunner.run()`.

  run(test, compileflags=None, out=None, clear_globs=True)

    Ejecuta los ejemplos en test (un objeto `DocTest`), y muestra los resultados usando función de escritura out.

    Los ejemplo se ejecutan en el espacio de nombres `test.globs`. Si clear_globs es verdadero (el valor por defecto), entonces este espacio de nombres será limpiado después de la prueba se ejecute, para ayudar con la colección de basura. Si quisieras examinar el espacio de nombres después de que la prueba se complete, entonces use clear_globs=False.

    compileflags da el conjunto de banderas que se deben usar por el compilador de Python cuando se ejecutan los ejemplos. Si no se especifica, entonces su valor por defecto será el conjunto de banderas de future-import que aplican a globs.

    The output of each example is checked using the `DocTestRunner`’s output checker, and the results are formatted by the `DocTestRunner.report_*()` methods.

  summarize(verbose=None)

    Imprime un resumen de todos los casos de prueba que han sido ejecutados por este DocTestRunner, y retorna un named tuple `TestResults(failed, attempted)`.

    El argumento opcional verbose controla qué tan detallado es el resumen. Si no se especifica la verbosidad, entonces se usa la verbosidad de `DocTestRunner`.

### Objetos OutputChecker

class doctest.OutputChecker

  Una clase que se usa para verificar si la salida real de un ejemplo de doctest coincide con la salida esperada. `OutputChecker` define dos métodos: `check_output()`, que compara un par de salidas dadas, y retorna `True` si coinciden; y `output_difference()`, que retorna una cadena que describe las diferencias entre las dos salidas.

  `OutputChecker` define los siguientes métodos:

  check_output(want, got, optionflags)

    Retorna `True` si y sólo si la salida real de un ejemplo (got) coincide con la salida esperada (want). Siempre se considera que estas cadenas coinciden si son idénticas; pero dependiendo de qué banderas de opción el test runner esté usando, varias coincidencias inexactas son posibles. Véase la sección Banderas de Opción para más información sobre las banderas de opción.

  output_difference(example, got, optionflags)

    Retorna una cadena que describe las diferencias entre la salida esperada para un ejemplo dado (example) y la salida real (got). optionflags es el conjunto de banderas de opción usado para comparar want y got.

## Depuración

Doctest proporciona varios mecanismos para depurar los ejemplos de doctest:

- Varias funciones convierten los doctest en programas de Python ejecutables, que pueden ser ejecutadas bajo el depurador de Python, `pdb`.

- La clase `DebugRunner` es una subclase de `DocTestRunner` que lanza una excepción por el primer ejemplo fallido, conteniendo información sobre ese ejemplo. Esta información se puede usar para realizar depuración a posteriori en el ejemplo.

- Los casos de `unittest` generados por `DocTestSuite()` admiten el método `debug()` definido por `unittest.TestCase`.

- Puedes añadir una llamada a `pdb.set_trace()` en un ejemplo de doctest, y bajarás al depurador de Python cuando esa línea sea ejecutada. Entonces puedes inspeccionar los valores de las variables, y demás. Por ejemplo, supongamos que `a.py` contiene sólo este docstring de módulo:

      """
      >>> def f(x):
      ...     g(x*2)
      >>> def g(x):
      ...     print(x+3)
      ...     import pdb; pdb.set_trace()
      >>> f(3)
      9
      """

  Entonces una sesión interactiva puede lucir como esta:

      >>> import a, doctest
      >>> doctest.testmod(a)
      --Return--
      > <doctest a[1]>(3)g()->None
      -> import pdb; pdb.set_trace()
      (Pdb) list
        1     def g(x):
        2         print(x+3)
        3  ->     import pdb; pdb.set_trace()
      [EOF]
      (Pdb) p x
      6
      (Pdb) step
      --Return--
      > <doctest a[0]>(2)f()->None
      -> g(x*2)
      (Pdb) list
        1     def f(x):
        2  ->     g(x*2)
      [EOF]
      (Pdb) p x
      3
      (Pdb) step
      --Return--
      > <doctest a[2]>(1)?()->None
      -> f(3)
      (Pdb) cont
      (0, 3)
      >>>

Funciones que convierten los doctest a código de Python, y posiblemente ejecuten el código sintetizado debajo del depurador:

doctest.script_from_examples(s)

  Convierte texto con ejemplos a un script.

  El argumento s es una cadena que contiene los ejemplos de doctest. La cadena se convierte a un script de Python, donde los ejemplos de doctest en s se convierten en código regular, y todo lo demás se convierte en comentarios de Python. El script generado se retorna como una cadena, Por ejemplo,

      import doctest
      print(doctest.script_from_examples(r"""
          Set x and y to 1 and 2.
          >>> x, y = 1, 2

          Print their sum:
          >>> print(x+y)
          3
      """))

  muestra:

      # Set x and y to 1 and 2.
      x, y = 1, 2
      #
      # Print their sum:
      print(x+y)
      # Expected:
      ## 3

  Esta función se usa internamente por otras funciones (véase más abajo), pero también pueden ser útiles cuando quieres transformar una sesión de Python interactiva en un script de Python.

doctest.testsource(module, name)

  Convierte el doctest para un objeto en un script.

  Argument module is a module object, or dotted name of a module, containing the object whose doctests are of interest. Argument name is the name (within the module) of the object with the doctests of interest. The result is a string, containing the object’s docstring converted to a Python script, as described for `script_from_examples()` above. For example, if module `a.py` contains a top-level function `f()`, then

      import a, doctest
      print(doctest.testsource(a, "a.f"))

  prints a script version of function `f()`”s docstring, with doctests converted to code, and the rest placed in comments.

doctest.debug(module, name, pm=False)

  Depura los doctest para un objeto.

  Los argumentos module y name son los mismos que para la función `testsource()` arriba. El script de Python sintetizado para el docstring del objeto nombrado es escrito en un archivo temporal, y entonces ese archivo es ejecutado bajo el control del depurador de PYthon, `pdb`.

  Se usa una copia superficial de `module.__dict__` para el contexto de ejecución local y global.

  El argumento opcional pm controla si se usa la depuración post-mortem. Si pm tiene un valor verdadero, el archivo de script es ejecutado directamente, y el depurador está involucrado sólo si el script termina a través del lanzamiento de una excepción. Si lo hace, entonces la depuración post-mortem es invocada, a través de `pdb.post_mortem()`, pasando el objeto de rastreo desde la excepción sin tratar. Si no se especifica pm, o si es falso, el script se ejecuta bajo el depurador desde el inicio, a través de una llamada de `exec()` apropiada a `pdb.run()`.

doctest.debug_src(src, pm=False, globs=None)

  Depura los doctest en una cadena de caracteres.

  Es como la función function `debug()` arriba, excepto que una cadena de caracteres que contiene los ejemplos de doctest se especifica directamente, a través del argumento src.

  El argumento opcional pm tiene el mismo significado como en la función `debug()` arriba.

  El argumento opcional globs proporciona un diccionario a usar como contexto de ejecución local y global. Si no se especifica, o es `None`, se usa un diccionario vacío. Si se especifica, se usa una copia superficial del diccionario.

La clase `DebugRunner`, y las excepciones especiales que puede lanzar, son de más interés a los autores de frameworks de pruebas, y sólo serán descritos brevemente aquí. Véase el código fuente, y especialmente el docstring de `DebugRunner` (¡que es un doctest!) para más detalles:

class doctest.DebugRunner(checker=None, verbose=None, optionflags=0)

  Una subclase de `DocTestRunner` que lanza una excepción tan pronto como se encuentra una falla. Si ocurre una excepción inesperada, se lanza una excepción `UnexpectedException`, conteniendo la prueba, el ejemplo, y la excepción original. Si la salida no coincide, entonces se lanza una excepción `DocTestFailure`, conteniendo la prueba, el ejemplo, y la salida real.

  Para información sobre los parámetros de construcción y los métodos, véase la documentación para `DocTestRunner` en la sección API avanzada.

Hay dos excepciones que se pueden lanzar por instancias de `DebugRunner`:

exception doctest.DocTestFailure(test, example, got)

  Una excepción lanzada por `DocTestRunner` para señalar que la salida real del ejemplo de un doctest no coincidió con su salida esperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

`DocTestFailure` define los siguientes atributos:

DocTestFailure.test

  El objeto `DocTest` que estaba siendo ejecutado cuando el ejemplo falló.

DocTestFailure.example

  El objeto `Example` que falló.

DocTestFailure.got

  La salida real del ejemplo.

exception doctest.UnexpectedException(test, example, exc_info)

  Una excepción lanzada por `DocTestRunner` para señalar que un ejemplo de doctest lanzó una excepción inesperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

`UnexpectedException` define los siguientes atributos:

UnexpectedException.test

  El objeto `DocTest` que estaba siendo ejecutado cuando el ejemplo falló.

UnexpectedException.example

  El objeto `Example` que falló.

UnexpectedException.exc_info

  Una tupla que contiene información sobre la excepción inesperada, como es retornado por `sys.exc_info()`.

## Plataforma improvisada

Como se menciona en la introducción, `doctest` ha crecido para tener tres usos primarios:

1. Verificar los ejemplos en los docstring.

2. Pruebas de regresión.

3. Documentación ejecutable / pruebas literarias.

Estos usos tienen diferentes requerimientos, y es importante distinguirlos. En particular, llenar tus docstring con casos de prueba desconocidos conduce a mala documentación.

Cuando se escribe un docstring, escoja ejemplos de docstring con cuidado. Hay un arte para eso que se debe aprender – puede no ser natural al comienzo. Los ejemplos deben añadir valor genuino a la documentación. Un buen ejemplo a menudo puede valer muchas palabras. Si se hace con cuidado, los ejemplos serán invaluables para tus usuarios, y compensarán el tiempo que toma recolectarlos varias veces mientras los años pasan y las cosas cambian. Todavía estoy sorprendido de qué tan frecuente uno de mis ejemplos de `doctest` paran de funcionar después de un cambio «inofensivo».

Doctest también es una excelente herramienta para pruebas de regresión, especialmente si no escatimas en texto explicativo. Al intercalar prosa y ejemplos, se hace mucho más fácil mantener el seguimiento de lo que realmente se está probando, y por qué. Cuando una prueba falla, buena prosa puede hacer mucho más fácil comprender cuál es el problema, y cómo debe ser arreglado. Es verdad que puedes escribir comentarios extensos en pruebas basadas en código, pero pocos programadores lo hacen. Quizás es porque simplemente doctest hace escribir pruebas mucho más fácil que escribir código, mientras que escribir comentarios en código es mucho más difícil. Pienso que va más allá de eso: la actitud natural cuando se escribe una prueba basada en doctest es que quieres explicar los puntos finos de tu software, e ilustrarlos con ejemplos. Esto naturalmente lleva a archivos de pruebas que empiezan con las características más simples, y lógicamente progresan a complicaciones y casos extremos. Una narrativa coherente es el resultado, en vez de una colección de funciones aisladas que pruebas trozos aislados de funcionalidad aparentemente al azar. Es una actitud diferente, y produce resultados diferentes, difuminando la distinción entre probar y explicar.

Pruebas de regresión se limitan mejor a objetos o archivos dedicados. Hay varias opciones para organizar pruebas:

- Escribe archivos de texto que contienen los casos de prueba como ejemplos interactivos, y prueba los archivos usando `testfile()` o `DocFileSuite()`. Esto es lo recomendado, aunque es más fácil hacerlo para nuevos proyectos, diseñados desde el comienzo para usar doctest.

- Define funciones nombradas `_regrtest_topic` que consisten en docstrings únicas, que contienen casos de prueba por los tópicos nombrados. Estas funciones se pueden incluir en el mismo archivo que el módulo, o separadas en un archivo de prueba separado.

- Define un diccionario `__test__` que asigna desde temas de prueba de integración a los docstring que contienen casos de prueba.

Cuando has puesto tus pruebas en un módulo, el módulo puede ser el mismo test runner. Cuando una prueba falla, puedes hacer que tu test runner vuelva a ejecutar sólo los doctest fallidos mientras que tu depuras el problema. Aquí hay un ejemplo mínimo de tal test runner:

    if __name__ == '__main__':
        import doctest
        flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
        if len(sys.argv) > 1:
            name = sys.argv[1]
            if name in globals():
                obj = globals()[name]
            else:
                obj = __test__[name]
            doctest.run_docstring_examples(obj, globals(), name=name,
                                           optionflags=flags)
        else:
            fail, total = doctest.testmod(optionflags=flags)
            print("{} failures out of {} tests".format(fail, total))

Notas al pie de página

[1]

No se admiten los ejemplos que contienen una salida esperada y una excepción. Intentar adivinar dónde una termina y la otra empieza es muy propenso a errores, y da lugar a una prueba confusa.