\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, generateannotated statement coverage listings, print caller/callee relationships andlist functions executed during a program run.  It can be used in anotherprogram 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 beas simple as \begin{verbatim}python -m trace --count somefile.py ...\end{verbatim} The above will generate annotated listings of all Python modules importedduring 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 programcompletion that shows how many times each statement was executed. \item[\longprogramopt{report}, \programopt{-r}]Produce an annotated list from an earlier program run thatused 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 makeseveral runs with \longprogramopt{count} then produce a single setof 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 whichwere not executed with `\code{>>>>>>}'. \item[\longprogramopt{summary}, \programopt{-s}]When using \longprogramopt{count} or \longprogramopt{report}, write abrief summary to stdout for each file processed. \item[\longprogramopt{ignore-module}]Ignore the named module and its submodules (if it isa package).  May be given multiple times. \item[\longprogramopt{ignore-dir}]Ignore all modules and packages in the named directoryand 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} enableslisting of the functions called during the run.  \var{countcallers} enablescall relationship tracking.  \var{ignoremods} is a list of modules orpackages to ignore.  \var{ignoredirs} is a list of directories whose modulesor packages should be ignored.  \var{infile} is the file from which to readstored count information.  \var{outfile} is a file in which to write updatedcount information.\end{classdesc} \begin{methoddesc}[Trace]{run}{cmd}Run \var{cmd} under control of the Trace object with the current tracingparameters.\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 tracingparameters 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 sysimport 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 tracertracer.run('main()') # make a report, placing output in /tmpr = tracer.results()r.write_results(show_missing=True, coverdir="/tmp")\end{verbatim}