"trace" --- Rastrear la ejecución de la declaración de Python
*************************************************************

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

Nuevo en la versión 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)

      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.

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