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