| \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} |
| |
| 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 \code{somefile.py}. |
| |
| \subsection{Command Line Arguments} |
| |
| \begin{description} |
| \item[--trace, -t]{Display lines as they are executed.} |
| \item[--count, -c]{Produce a set of annotated listing files upon program |
| completion that shows how many times each statement was executed.} |
| \item[--report, -r]{Produce an annotated list from an earlier program run that |
| used the \code{--count} and \code{--file} arguments.} |
| \item[--no-report, -R]{Do not generate annotated listings. This is useful |
| if you intend to make several runs with \code{--count} then produce a single |
| set of annotated listings at the end.} |
| \item[--listfuncs, -l]{List the functions executed by running the program.} |
| \item[--trackcalls, -T]{Generate calling relationships exposed by running the |
| program.} |
| \item[--file, -f]{Name a file containing (or to contain) counts.} |
| \item[--coverdir, -C]{Name a directory in which to save annotated listing |
| files.} |
| \item[--missing, -m]{When generating annotated listings, mark lines which |
| were not executed with \code{>>>>>>}.} |
| \item[--summary -s]{When using \code{--count} or \code{--report}, write a |
| brief summary to stdout for each file processed.} |
| \item[--ignore-module]{Ignore the named module and its submodules (if it is |
| a package). May be given multiple times.} |
| \item[--ignore-dir]{Ignore all modules and packages in the named directory |
| and subdirectories. May be given multiple times.} |
| \end{description} |
| |
| \subsection{Program Usage} |
| |
| \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 \code{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 \code{cmd} under control of the Trace object with the current tracing |
| parameters in the defined global and local environments. If not defined, |
| \code{globals} and \code{locals} default to empty dictionaries. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds} |
| Call \code{function} with the given arguments under control of the Trace |
| object with the current tracing parameters. |
| \end{methoddesc} |
| |
| \subsubsection{Example} |
| |
| \begin{verbatim} |
| import sys |
| |
| # 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} |