# `trace` — Trace or track Python statement execution

Código fuente: Lib/trace.py

El módulo `trace` le permite rastrear la ejecución del programa, generar listas de cobertura de declaraciones anotadas, imprimir relaciones entre llamador/destinatario y listar funciones ejecutadas durante la ejecución de un programa. Se puede utilizar en otro programa o desde la línea de comandos.

Ver también

Coverage.py

  Una herramienta popular de terceros de cobertura que proporciona salida HTML junto con funciones avanzadas como cobertura de sucursales.

## Uso de la línea de comandos

El módulo `trace` se puede invocar desde la línea de comandos. Puede ser tan simple como

    python -m trace --count -C . somefile.py ...

Lo anterior ejecutará `somefile.py` y generará listados anotados de todos los módulos de Python importados durante la ejecución en el directorio actual.

--help

  Muestra uso y sale.

--version

  Muestra la versión del módulo y sale.

Added in version 3.8: Se agregó la opción `--module` que permite ejecutar un módulo ejecutable.

### Opciones principales

Se debe especificar al menos una de las siguientes opciones al invocar `trace`. La opción `--listfuncs` es mutuamente excluyente con las opciones `--trace` y `--count`. Cuando se proporciona `--listfuncs`, no se aceptan `--count` ni `--trace`, y viceversa.

-c, --count

  Genera un conjunto de archivos de lista anotados al finalizar el programa que muestra cuántas veces se ejecutó cada instrucción. Vea también `--coverdir`, `--file` y `--no-report` a continuación.

-t, --trace

  Muestra las líneas a medida que se ejecutan.

-l, --listfuncs

  Muestra las funciones ejecutadas al ejecutar el programa.

-r, --report

  Genera una lista anotada de una ejecución del programa anterior que utilizó la opción `--count` y `--file`. Esto no ejecuta ningún código.

-T, --trackcalls

  Muestra las relaciones de llamada expuestas al ejecutar el programa.

### Modificadores

-f, --file=<file>

  Nombre de un archivo para acumular recuentos durante varias ejecuciones de seguimiento. Debe usarse con la opción `--count`.

-C, --coverdir=<dir>

  Directorio donde van los archivos del informe. El informe de cobertura para `paquete.modulo` se escribe en el archivo `directorio/paquete/modulo.cobertura`.

-m, --missing

  Al generar listados anotados, marque las líneas que no se ejecutaron con `>>>>>>`.

-s, --summary

  Cuando use `--count` o `--report`, escriba un breve resumen en stdout para cada archivo procesado.

-R, --no-report

  No genera listados anotados. Esto es útil si tiene la intención de realizar varias ejecuciones con `--count`, y luego producir un solo conjunto de listados anotados al final.

-g, --timing

  Prefija cada línea con la hora desde que se inició el programa. Solo se usa durante el rastreo.

### Filtros

Estas opciones pueden repetirse varias veces.

--ignore-module=<mod>

  Ignora cada uno de los nombres de módulo dados y sus submódulos (si es un paquete). El argumento puede ser una lista de nombres separados por una coma.

--ignore-dir=<dir>

  Ignora todos los módulos y paquetes en el directorio y subdirectorios nombrados. El argumento puede ser una lista de directorios separados por `os.pathsep`.

## Interfaz programática

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

  Crea un objeto para rastrear la ejecución de una sola declaración o expresión. Todos los parámetros son opcionales. count habilita el conteo de números de línea. trace habilita el seguimiento de ejecución de línea. countfuncs habilita la lista de las funciones llamadas durante la ejecución. countcallers habilita el seguimiento de la relación de llamadas. ignoremods es una lista de módulos o paquetes para ignorar. ignoredirs es una lista de directorios cuyos módulos o paquetes deben ignorarse. infile es el nombre del archivo desde el cual leer la información de conteo almacenada. outfile es el nombre del archivo en el que se escribe la información de conteo actualizada. timing permite mostrar una marca de tiempo relativa al momento en que se inició el seguimiento.

  run(cmd)

    Ejecuta el comando y recopile estadísticas de la ejecución con los parámetros de seguimiento actuales. cmd debe ser una cadena o un objeto de código, adecuado para pasar a `exec()`.

  runctx(cmd, globals=None, locals=None)

    Ejecuta el comando y recopile estadísticas de la ejecución con los parámetros de seguimiento actuales, en los entornos globales y locales definidos. Si no está definido, globals y locals por defecto son diccionarios vacíos.

  runfunc(func, /, *args, **kwds)

    Llama a func con los argumentos dados bajo el control del objeto `Trace` con los parámetros de rastreo actuales.

  results()

    Retorna un objeto `CoverageResults` que contiene los resultados acumulativos de todas las llamadas anteriores a `run`, `runctx` y `runfunc` para la instancia dada `Trace`. No restablece los resultados de seguimiento acumulados.

class trace.CoverageResults

  Un contenedor para los resultados de la cobertura, creado por `Trace.results()`. No debe ser creado directamente por el usuario.

  update(other)

    Fusiona datos de otro objeto `CoverageResults`.

  write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)

    Escribe los resultados de la cobertura. Configure show_missing para mostrar las líneas que no tuvieron coincidencias. Configurar summary para incluir en la salida el resumen de cobertura por módulo. coverdir especifica el directorio en el que se enviarán los archivos de resultado de cobertura. Si es `None`, los resultados de cada archivo fuente se colocan en su directorio.

    If ignore_missing_files is `True`, coverage counts for files that no longer exist are silently ignored. Otherwise, a missing file will raise a `FileNotFoundError`.

    Distinto en la versión 3.13: Added ignore_missing_files parameter.

Un ejemplo simple que demuestra el uso de la interfaz programática:

    import sys
    import trace

    # create a Trace object, telling it what to ignore, and whether to
    # do tracing or line-counting or both.
    tracer = trace.Trace(
        ignoredirs=[sys.prefix, sys.exec_prefix],
        trace=0,
        count=1)

    # run the new command using the given tracer
    tracer.run('main()')

    # make a report, placing output in the current directory
    r = tracer.results()
    r.write_results(show_missing=True, coverdir=".")