Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`trace` --- Trace or track Python statement execution |
| 2 | ========================================================== |
| 3 | |
| 4 | .. module:: trace |
| 5 | :synopsis: Trace or track Python statement execution. |
| 6 | |
Raymond Hettinger | 1048094 | 2011-01-10 03:26:08 +0000 | [diff] [blame] | 7 | **Source code:** :source:`Lib/trace.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
Raymond Hettinger | 4f707fd | 2011-01-10 19:54:11 +0000 | [diff] [blame] | 9 | -------------- |
| 10 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | The :mod:`trace` module allows you to trace program execution, generate |
| 12 | annotated statement coverage listings, print caller/callee relationships and |
| 13 | list functions executed during a program run. It can be used in another program |
| 14 | or from the command line. |
| 15 | |
Brett Cannon | 9d07ace | 2017-03-03 12:58:17 -0800 | [diff] [blame^] | 16 | .. seealso:: |
| 17 | |
| 18 | `Coverage.py <https://coverage.readthedocs.io/>`_ |
| 19 | A popular third-party coverage tool that provides HTML |
| 20 | output along with advanced features such as branch coverage. |
| 21 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | .. _trace-cli: |
| 23 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 24 | Command-Line Usage |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 25 | ------------------ |
| 26 | |
| 27 | The :mod:`trace` module can be invoked from the command line. It can be as |
| 28 | simple as :: |
| 29 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 30 | python -m trace --count -C . somefile.py ... |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 32 | The above will execute :file:`somefile.py` and generate annotated listings of |
| 33 | all Python modules imported during the execution into the current directory. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 34 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 35 | .. program:: trace |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 37 | .. cmdoption:: --help |
| 38 | |
| 39 | Display usage and exit. |
| 40 | |
| 41 | .. cmdoption:: --version |
| 42 | |
| 43 | Display the version of the module and exit. |
| 44 | |
| 45 | Main options |
| 46 | ^^^^^^^^^^^^ |
| 47 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 48 | At least one of the following options must be specified when invoking |
| 49 | :mod:`trace`. The :option:`--listfuncs <-l>` option is mutually exclusive with |
Senthil Kumaran | f5c3405 | 2014-04-06 10:59:47 -0700 | [diff] [blame] | 50 | the :option:`--trace <-t>` and :option:`--count <-c>` options. When |
| 51 | :option:`--listfuncs <-l>` is provided, neither :option:`--count <-c>` nor |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 52 | :option:`--trace <-t>` are accepted, and vice versa. |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 53 | |
| 54 | .. program:: trace |
| 55 | |
| 56 | .. cmdoption:: -c, --count |
| 57 | |
| 58 | Produce a set of annotated listing files upon program completion that shows |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 59 | how many times each statement was executed. See also |
| 60 | :option:`--coverdir <-C>`, :option:`--file <-f>` and |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 61 | :option:`--no-report <-R>` below. |
| 62 | |
| 63 | .. cmdoption:: -t, --trace |
| 64 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | Display lines as they are executed. |
| 66 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 67 | .. cmdoption:: -l, --listfuncs |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 69 | Display the functions executed by running the program. |
| 70 | |
| 71 | .. cmdoption:: -r, --report |
| 72 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | Produce an annotated list from an earlier program run that used the |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 74 | :option:`--count <-c>` and :option:`--file <-f>` option. This does not |
| 75 | execute any code. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 77 | .. cmdoption:: -T, --trackcalls |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 79 | Display the calling relationships exposed by running the program. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 81 | Modifiers |
| 82 | ^^^^^^^^^ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 84 | .. program:: trace |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 86 | .. cmdoption:: -f, --file=<file> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 88 | Name of a file to accumulate counts over several tracing runs. Should be |
| 89 | used with the :option:`--count <-c>` option. |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 90 | |
| 91 | .. cmdoption:: -C, --coverdir=<dir> |
| 92 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 93 | Directory where the report files go. The coverage report for |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 94 | ``package.module`` is written to file :file:`{dir}/{package}/{module}.cover`. |
| 95 | |
| 96 | .. cmdoption:: -m, --missing |
| 97 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | When generating annotated listings, mark lines which were not executed with |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 99 | ``>>>>>>``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 101 | .. cmdoption:: -s, --summary |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 103 | When using :option:`--count <-c>` or :option:`--report <-r>`, write a brief |
| 104 | summary to stdout for each file processed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 106 | .. cmdoption:: -R, --no-report |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 108 | Do not generate annotated listings. This is useful if you intend to make |
| 109 | several runs with :option:`--count <-c>`, and then produce a single set of |
| 110 | annotated listings at the end. |
| 111 | |
| 112 | .. cmdoption:: -g, --timing |
| 113 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 114 | Prefix each line with the time since the program started. Only used while |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 115 | tracing. |
| 116 | |
| 117 | Filters |
| 118 | ^^^^^^^ |
| 119 | |
| 120 | These options may be repeated multiple times. |
| 121 | |
| 122 | .. program:: trace |
| 123 | |
| 124 | .. cmdoption:: --ignore-module=<mod> |
| 125 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 126 | Ignore each of the given module names and its submodules (if it is a |
| 127 | package). The argument can be a list of names separated by a comma. |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 128 | |
| 129 | .. cmdoption:: --ignore-dir=<dir> |
| 130 | |
| 131 | Ignore all modules and packages in the named directory and subdirectories. |
| 132 | The argument can be a list of directories separated by :data:`os.pathsep`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 133 | |
| 134 | .. _trace-api: |
| 135 | |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 136 | Programmatic Interface |
| 137 | ---------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 139 | .. class:: Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(),\ |
| 140 | ignoredirs=(), infile=None, outfile=None, timing=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 142 | Create an object to trace execution of a single statement or expression. All |
| 143 | parameters are optional. *count* enables counting of line numbers. *trace* |
| 144 | enables line execution tracing. *countfuncs* enables listing of the |
| 145 | functions called during the run. *countcallers* enables call relationship |
| 146 | tracking. *ignoremods* is a list of modules or packages to ignore. |
| 147 | *ignoredirs* is a list of directories whose modules or packages should be |
| 148 | ignored. *infile* is the name of the file from which to read stored count |
| 149 | information. *outfile* is the name of the file in which to write updated |
| 150 | count information. *timing* enables a timestamp relative to when tracing was |
| 151 | started to be displayed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 153 | .. method:: run(cmd) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 154 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 155 | Execute the command and gather statistics from the execution with |
| 156 | the current tracing parameters. *cmd* must be a string or code object, |
| 157 | suitable for passing into :func:`exec`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 158 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 159 | .. method:: runctx(cmd, globals=None, locals=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 160 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 161 | Execute the command and gather statistics from the execution with the |
| 162 | current tracing parameters, in the defined global and local |
| 163 | environments. If not defined, *globals* and *locals* default to empty |
| 164 | dictionaries. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 165 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 166 | .. method:: runfunc(func, *args, **kwds) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 167 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 168 | Call *func* with the given arguments under control of the :class:`Trace` |
| 169 | object with the current tracing parameters. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 170 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 171 | .. method:: results() |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 172 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 173 | Return a :class:`CoverageResults` object that contains the cumulative |
| 174 | results of all previous calls to ``run``, ``runctx`` and ``runfunc`` |
| 175 | for the given :class:`Trace` instance. Does not reset the accumulated |
| 176 | trace results. |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 177 | |
| 178 | .. class:: CoverageResults |
| 179 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 180 | A container for coverage results, created by :meth:`Trace.results`. Should |
| 181 | not be created directly by the user. |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 182 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 183 | .. method:: update(other) |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 184 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 185 | Merge in data from another :class:`CoverageResults` object. |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 186 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 187 | .. method:: write_results(show_missing=True, summary=False, coverdir=None) |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 188 | |
Éric Araujo | 67f0b6c | 2010-12-15 19:30:15 +0000 | [diff] [blame] | 189 | Write coverage results. Set *show_missing* to show lines that had no |
| 190 | hits. Set *summary* to include in the output the coverage summary per |
| 191 | module. *coverdir* specifies the directory into which the coverage |
| 192 | result files will be output. If ``None``, the results for each source |
| 193 | file are placed in its directory. |
Éric Araujo | d00862a | 2010-12-15 19:09:58 +0000 | [diff] [blame] | 194 | |
| 195 | A simple example demonstrating the use of the programmatic interface:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 196 | |
| 197 | import sys |
| 198 | import trace |
| 199 | |
| 200 | # create a Trace object, telling it what to ignore, and whether to |
| 201 | # do tracing or line-counting or both. |
| 202 | tracer = trace.Trace( |
| 203 | ignoredirs=[sys.prefix, sys.exec_prefix], |
| 204 | trace=0, |
| 205 | count=1) |
| 206 | |
| 207 | # run the new command using the given tracer |
| 208 | tracer.run('main()') |
| 209 | |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 210 | # make a report, placing output in the current directory |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 211 | r = tracer.results() |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 212 | r.write_results(show_missing=True, coverdir=".") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |