Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 1 | \section{\module{trace} --- |
| 2 | Trace or track Python statement execution} |
| 3 | |
| 4 | \declaremodule{standard}{trace} |
| 5 | \modulesynopsis{Trace or track Python statement execution.} |
| 6 | |
| 7 | The \module{trace} module allows you to trace program execution, generate |
| 8 | annotated statement coverage listings, print caller/callee relationships and |
| 9 | list functions executed during a program run. It can be used in another |
| 10 | program or from the command line. |
| 11 | |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 12 | \subsection{Command Line Usage\label{trace-cli}} |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 13 | |
| 14 | The \module{trace} module can be invoked from the command line. It can be |
| 15 | as simple as |
| 16 | |
| 17 | \begin{verbatim} |
| 18 | python -m trace --count somefile.py ... |
| 19 | \end{verbatim} |
| 20 | |
| 21 | The above will generate annotated listings of all Python modules imported |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 22 | during the execution of \file{somefile.py}. |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 23 | |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 24 | The following command-line arguments are supported: |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 25 | |
| 26 | \begin{description} |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 27 | \item[\longprogramopt{trace}, \programopt{-t}] |
| 28 | Display lines as they are executed. |
| 29 | |
| 30 | \item[\longprogramopt{count}, \programopt{-c}] |
| 31 | Produce a set of annotated listing files upon program |
| 32 | completion that shows how many times each statement was executed. |
| 33 | |
| 34 | \item[\longprogramopt{report}, \programopt{-r}] |
| 35 | Produce an annotated list from an earlier program run that |
| 36 | used the \longprogramopt{count} and \longprogramopt{file} arguments. |
| 37 | |
| 38 | \item[\longprogramopt{no-report}, \programopt{-R}] |
| 39 | Do not generate annotated listings. This is useful if you intend to make |
| 40 | several runs with \longprogramopt{count} then produce a single set |
| 41 | of annotated listings at the end. |
| 42 | |
| 43 | \item[\longprogramopt{listfuncs}, \programopt{-l}] |
| 44 | List the functions executed by running the program. |
| 45 | |
| 46 | \item[\longprogramopt{trackcalls}, \programopt{-T}] |
| 47 | Generate calling relationships exposed by running the program. |
| 48 | |
| 49 | \item[\longprogramopt{file}, \programopt{-f}] |
| 50 | Name a file containing (or to contain) counts. |
| 51 | |
| 52 | \item[\longprogramopt{coverdir}, \programopt{-C}] |
| 53 | Name a directory in which to save annotated listing files. |
| 54 | |
| 55 | \item[\longprogramopt{missing}, \programopt{-m}] |
| 56 | When generating annotated listings, mark lines which |
Fred Drake | f25fa6d | 2006-05-03 02:04:40 +0000 | [diff] [blame] | 57 | were not executed with `\code{>>>>>>}'. |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 58 | |
| 59 | \item[\longprogramopt{summary}, \programopt{-s}] |
| 60 | When using \longprogramopt{count} or \longprogramopt{report}, write a |
| 61 | brief summary to stdout for each file processed. |
| 62 | |
| 63 | \item[\longprogramopt{ignore-module}] |
| 64 | Ignore the named module and its submodules (if it is |
| 65 | a package). May be given multiple times. |
| 66 | |
| 67 | \item[\longprogramopt{ignore-dir}] |
| 68 | Ignore all modules and packages in the named directory |
| 69 | and subdirectories. May be given multiple times. |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 70 | \end{description} |
| 71 | |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 72 | \subsection{Programming Interface\label{trace-api}} |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 73 | |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 74 | \begin{classdesc}{Trace}{\optional{count=1\optional{, trace=1\optional{, |
| 75 | countfuncs=0\optional{, countcallers=0\optional{, |
| 76 | ignoremods=()\optional{, ignoredirs=()\optional{, |
| 77 | infile=None\optional{, outfile=None}}}}}}}}} |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 78 | Create an object to trace execution of a single statement or expression. |
| 79 | All parameters are optional. \var{count} enables counting of line numbers. |
| 80 | \var{trace} enables line execution tracing. \var{countfuncs} enables |
| 81 | listing of the functions called during the run. \var{countcallers} enables |
| 82 | call relationship tracking. \var{ignoremods} is a list of modules or |
| 83 | packages to ignore. \var{ignoredirs} is a list of directories whose modules |
| 84 | or packages should be ignored. \var{infile} is the file from which to read |
| 85 | stored count information. \var{outfile} is a file in which to write updated |
| 86 | count information. |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 87 | \end{classdesc} |
| 88 | |
| 89 | \begin{methoddesc}[Trace]{run}{cmd} |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 90 | Run \var{cmd} under control of the Trace object with the current tracing |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 91 | parameters. |
| 92 | \end{methoddesc} |
| 93 | |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 94 | \begin{methoddesc}[Trace]{runctx}{cmd\optional{, globals=None\optional{, |
| 95 | locals=None}}} |
| 96 | Run \var{cmd} under control of the Trace object with the current tracing |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 97 | parameters in the defined global and local environments. If not defined, |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 98 | \var{globals} and \var{locals} default to empty dictionaries. |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 99 | \end{methoddesc} |
| 100 | |
| 101 | \begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds} |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 102 | Call \var{func} with the given arguments under control of the |
| 103 | \class{Trace} object with the current tracing parameters. |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 104 | \end{methoddesc} |
| 105 | |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 106 | This is a simple example showing the use of this module: |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 107 | |
| 108 | \begin{verbatim} |
Skip Montanaro | 9ab2f45 | 2006-04-23 19:30:50 +0000 | [diff] [blame] | 109 | import sys |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 110 | import trace |
Skip Montanaro | 9ab2f45 | 2006-04-23 19:30:50 +0000 | [diff] [blame] | 111 | |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 112 | # create a Trace object, telling it what to ignore, and whether to |
| 113 | # do tracing or line-counting or both. |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 114 | tracer = trace.Trace( |
| 115 | ignoredirs=[sys.prefix, sys.exec_prefix], |
| 116 | trace=0, |
| 117 | count=1) |
| 118 | |
Skip Montanaro | 9ab2f45 | 2006-04-23 19:30:50 +0000 | [diff] [blame] | 119 | # run the new command using the given tracer |
| 120 | tracer.run('main()') |
Fred Drake | 2afbf96 | 2006-04-26 05:15:41 +0000 | [diff] [blame] | 121 | |
Skip Montanaro | 9ab2f45 | 2006-04-23 19:30:50 +0000 | [diff] [blame] | 122 | # make a report, placing output in /tmp |
| 123 | r = tracer.results() |
| 124 | r.write_results(show_missing=True, coverdir="/tmp") |
Skip Montanaro | 47767c3 | 2006-04-23 19:14:27 +0000 | [diff] [blame] | 125 | \end{verbatim} |