126 lines
4.6 KiB
TeX
126 lines
4.6 KiB
TeX
\section{\module{trace} ---
|
|
Trace or track Python statement execution}
|
|
|
|
\declaremodule{standard}{trace}
|
|
\modulesynopsis{Trace or track Python statement execution.}
|
|
|
|
The \module{trace} module allows you to trace program execution, generate
|
|
annotated statement coverage listings, print caller/callee relationships and
|
|
list functions executed during a program run. It can be used in another
|
|
program or from the command line.
|
|
|
|
\subsection{Command Line Usage\label{trace-cli}}
|
|
|
|
The \module{trace} module can be invoked from the command line. It can be
|
|
as simple as
|
|
|
|
\begin{verbatim}
|
|
python -m trace --count somefile.py ...
|
|
\end{verbatim}
|
|
|
|
The above will generate annotated listings of all Python modules imported
|
|
during the execution of \file{somefile.py}.
|
|
|
|
The following command-line arguments are supported:
|
|
|
|
\begin{description}
|
|
\item[\longprogramopt{trace}, \programopt{-t}]
|
|
Display lines as they are executed.
|
|
|
|
\item[\longprogramopt{count}, \programopt{-c}]
|
|
Produce a set of annotated listing files upon program
|
|
completion that shows how many times each statement was executed.
|
|
|
|
\item[\longprogramopt{report}, \programopt{-r}]
|
|
Produce an annotated list from an earlier program run that
|
|
used the \longprogramopt{count} and \longprogramopt{file} arguments.
|
|
|
|
\item[\longprogramopt{no-report}, \programopt{-R}]
|
|
Do not generate annotated listings. This is useful if you intend to make
|
|
several runs with \longprogramopt{count} then produce a single set
|
|
of annotated listings at the end.
|
|
|
|
\item[\longprogramopt{listfuncs}, \programopt{-l}]
|
|
List the functions executed by running the program.
|
|
|
|
\item[\longprogramopt{trackcalls}, \programopt{-T}]
|
|
Generate calling relationships exposed by running the program.
|
|
|
|
\item[\longprogramopt{file}, \programopt{-f}]
|
|
Name a file containing (or to contain) counts.
|
|
|
|
\item[\longprogramopt{coverdir}, \programopt{-C}]
|
|
Name a directory in which to save annotated listing files.
|
|
|
|
\item[\longprogramopt{missing}, \programopt{-m}]
|
|
When generating annotated listings, mark lines which
|
|
were not executed with `\code{>>>>>>}'.
|
|
|
|
\item[\longprogramopt{summary}, \programopt{-s}]
|
|
When using \longprogramopt{count} or \longprogramopt{report}, write a
|
|
brief summary to stdout for each file processed.
|
|
|
|
\item[\longprogramopt{ignore-module}]
|
|
Ignore the named module and its submodules (if it is
|
|
a package). May be given multiple times.
|
|
|
|
\item[\longprogramopt{ignore-dir}]
|
|
Ignore all modules and packages in the named directory
|
|
and subdirectories. May be given multiple times.
|
|
\end{description}
|
|
|
|
\subsection{Programming Interface\label{trace-api}}
|
|
|
|
\begin{classdesc}{Trace}{\optional{count=1\optional{, trace=1\optional{,
|
|
countfuncs=0\optional{, countcallers=0\optional{,
|
|
ignoremods=()\optional{, ignoredirs=()\optional{,
|
|
infile=None\optional{, outfile=None}}}}}}}}}
|
|
Create an object to trace execution of a single statement or expression.
|
|
All parameters are optional. \var{count} enables counting of line numbers.
|
|
\var{trace} enables line execution tracing. \var{countfuncs} enables
|
|
listing of the functions called during the run. \var{countcallers} enables
|
|
call relationship tracking. \var{ignoremods} is a list of modules or
|
|
packages to ignore. \var{ignoredirs} is a list of directories whose modules
|
|
or packages should be ignored. \var{infile} is the file from which to read
|
|
stored count information. \var{outfile} is a file in which to write updated
|
|
count information.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}[Trace]{run}{cmd}
|
|
Run \var{cmd} under control of the Trace object with the current tracing
|
|
parameters.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Trace]{runctx}{cmd\optional{, globals=None\optional{,
|
|
locals=None}}}
|
|
Run \var{cmd} under control of the Trace object with the current tracing
|
|
parameters in the defined global and local environments. If not defined,
|
|
\var{globals} and \var{locals} default to empty dictionaries.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds}
|
|
Call \var{func} with the given arguments under control of the
|
|
\class{Trace} object with the current tracing parameters.
|
|
\end{methoddesc}
|
|
|
|
This is a simple example showing the use of this module:
|
|
|
|
\begin{verbatim}
|
|
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 /tmp
|
|
r = tracer.results()
|
|
r.write_results(show_missing=True, coverdir="/tmp")
|
|
\end{verbatim}
|