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