path: root/devdocs/python~3.12/library%2Ftrace.html

 <span id="trace-trace-or-track-python-statement-execution"></span><h1>trace — Trace or track Python statement execution</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/trace.py">Lib/trace.py</a></p>  <p>The <a class="reference internal" href="#module-trace" title="trace: Trace or track Python statement execution."><code>trace</code></a> 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.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt><a class="reference external" href="https://coverage.readthedocs.io/">Coverage.py</a></dt>
<dd>
<p>A popular third-party coverage tool that provides HTML output along with advanced features such as branch coverage.</p> </dd> </dl> </div> <section id="command-line-usage"> <span id="trace-cli"></span><h2>Command-Line Usage</h2> <p>The <a class="reference internal" href="#module-trace" title="trace: Trace or track Python statement execution."><code>trace</code></a> module can be invoked from the command line. It can be as simple as</p> <pre data-language="python">python -m trace --count -C . somefile.py ...
</pre> <p>The above will execute <code>somefile.py</code> and generate annotated listings of all Python modules imported during the execution into the current directory.</p> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-help">
<code>--help</code> </dt> <dd>
<p>Display usage and exit.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-version">
<code>--version</code> </dt> <dd>
<p>Display the version of the module and exit.</p> </dd>
</dl> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.8: </span>Added <code>--module</code> option that allows to run an executable module.</p> </div> <section id="main-options"> <h3>Main options</h3> <p>At least one of the following options must be specified when invoking <a class="reference internal" href="#module-trace" title="trace: Trace or track Python statement execution."><code>trace</code></a>. The <a class="reference internal" href="#cmdoption-trace-l"><code>--listfuncs</code></a> option is mutually exclusive with the <a class="reference internal" href="#cmdoption-trace-t"><code>--trace</code></a> and <a class="reference internal" href="#cmdoption-trace-c"><code>--count</code></a> options. When <a class="reference internal" href="#cmdoption-trace-l"><code>--listfuncs</code></a> is provided, neither <a class="reference internal" href="#cmdoption-trace-c"><code>--count</code></a> nor <a class="reference internal" href="#cmdoption-trace-t"><code>--trace</code></a> are accepted, and vice versa.</p> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-c">
<code>-c, --count</code> </dt> <dd>
<p>Produce a set of annotated listing files upon program completion that shows how many times each statement was executed. See also <a class="reference internal" href="#cmdoption-trace-C"><code>--coverdir</code></a>, <a class="reference internal" href="#cmdoption-trace-f"><code>--file</code></a> and <a class="reference internal" href="#cmdoption-trace-R"><code>--no-report</code></a> below.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-t">
<code>-t, --trace</code> </dt> <dd>
<p>Display lines as they are executed.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-l">
<code>-l, --listfuncs</code> </dt> <dd>
<p>Display the functions executed by running the program.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-r">
<code>-r, --report</code> </dt> <dd>
<p>Produce an annotated list from an earlier program run that used the <a class="reference internal" href="#cmdoption-trace-c"><code>--count</code></a> and <a class="reference internal" href="#cmdoption-trace-f"><code>--file</code></a> option. This does not execute any code.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-T">
<code>-T, --trackcalls</code> </dt> <dd>
<p>Display the calling relationships exposed by running the program.</p> </dd>
</dl> </section> <section id="modifiers"> <h3>Modifiers</h3> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-f">
<code>-f, --file=&lt;file&gt;</code> </dt> <dd>
<p>Name of a file to accumulate counts over several tracing runs. Should be used with the <a class="reference internal" href="#cmdoption-trace-c"><code>--count</code></a> option.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-C">
<code>-C, --coverdir=&lt;dir&gt;</code> </dt> <dd>
<p>Directory where the report files go. The coverage report for <code>package.module</code> is written to file <code><em>dir</em>/<em>package</em>/<em>module</em>.cover</code>.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-m">
<code>-m, --missing</code> </dt> <dd>
<p>When generating annotated listings, mark lines which were not executed with <code>&gt;&gt;&gt;&gt;&gt;&gt;</code>.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-s">
<code>-s, --summary</code> </dt> <dd>
<p>When using <a class="reference internal" href="#cmdoption-trace-c"><code>--count</code></a> or <a class="reference internal" href="#cmdoption-trace-r"><code>--report</code></a>, write a brief summary to stdout for each file processed.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-R">
<code>-R, --no-report</code> </dt> <dd>
<p>Do not generate annotated listings. This is useful if you intend to make several runs with <a class="reference internal" href="#cmdoption-trace-c"><code>--count</code></a>, and then produce a single set of annotated listings at the end.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-g">
<code>-g, --timing</code> </dt> <dd>
<p>Prefix each line with the time since the program started. Only used while tracing.</p> </dd>
</dl> </section> <section id="filters"> <h3>Filters</h3> <p>These options may be repeated multiple times.</p> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-ignore-module">
<code>--ignore-module=&lt;mod&gt;</code> </dt> <dd>
<p>Ignore each of the given module names and its submodules (if it is a package). The argument can be a list of names separated by a comma.</p> </dd>
</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-trace-ignore-dir">
<code>--ignore-dir=&lt;dir&gt;</code> </dt> <dd>
<p>Ignore all modules and packages in the named directory and subdirectories. The argument can be a list of directories separated by <a class="reference internal" href="os#os.pathsep" title="os.pathsep"><code>os.pathsep</code></a>.</p> </dd>
</dl> </section> </section> <section id="programmatic-interface"> <span id="trace-api"></span><h2>Programmatic Interface</h2> <dl class="py class"> <dt class="sig sig-object py" id="trace.Trace">
<code>class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)</code> </dt> <dd>
<p>Create an object to trace execution of a single statement or expression. All parameters are optional. <em>count</em> enables counting of line numbers. <em>trace</em> enables line execution tracing. <em>countfuncs</em> enables listing of the functions called during the run. <em>countcallers</em> enables call relationship tracking. <em>ignoremods</em> is a list of modules or packages to ignore. <em>ignoredirs</em> is a list of directories whose modules or packages should be ignored. <em>infile</em> is the name of the file from which to read stored count information. <em>outfile</em> is the name of the file in which to write updated count information. <em>timing</em> enables a timestamp relative to when tracing was started to be displayed.</p> <dl class="py method"> <dt class="sig sig-object py" id="trace.Trace.run">
<code>run(cmd)</code> </dt> <dd>
<p>Execute the command and gather statistics from the execution with the current tracing parameters. <em>cmd</em> must be a string or code object, suitable for passing into <a class="reference internal" href="functions#exec" title="exec"><code>exec()</code></a>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="trace.Trace.runctx">
<code>runctx(cmd, globals=None, locals=None)</code> </dt> <dd>
<p>Execute the command and gather statistics from the execution with the current tracing parameters, in the defined global and local environments. If not defined, <em>globals</em> and <em>locals</em> default to empty dictionaries.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="trace.Trace.runfunc">
<code>runfunc(func, /, *args, **kwds)</code> </dt> <dd>
<p>Call <em>func</em> with the given arguments under control of the <a class="reference internal" href="#trace.Trace" title="trace.Trace"><code>Trace</code></a> object with the current tracing parameters.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="trace.Trace.results">
<code>results()</code> </dt> <dd>
<p>Return a <a class="reference internal" href="#trace.CoverageResults" title="trace.CoverageResults"><code>CoverageResults</code></a> object that contains the cumulative results of all previous calls to <code>run</code>, <code>runctx</code> and <code>runfunc</code> for the given <a class="reference internal" href="#trace.Trace" title="trace.Trace"><code>Trace</code></a> instance. Does not reset the accumulated trace results.</p> </dd>
</dl> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="trace.CoverageResults">
<code>class trace.CoverageResults</code> </dt> <dd>
<p>A container for coverage results, created by <a class="reference internal" href="#trace.Trace.results" title="trace.Trace.results"><code>Trace.results()</code></a>. Should not be created directly by the user.</p> <dl class="py method"> <dt class="sig sig-object py" id="trace.CoverageResults.update">
<code>update(other)</code> </dt> <dd>
<p>Merge in data from another <a class="reference internal" href="#trace.CoverageResults" title="trace.CoverageResults"><code>CoverageResults</code></a> object.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="trace.CoverageResults.write_results">
<code>write_results(show_missing=True, summary=False, coverdir=None)</code> </dt> <dd>
<p>Write coverage results. Set <em>show_missing</em> to show lines that had no hits. Set <em>summary</em> to include in the output the coverage summary per module. <em>coverdir</em> specifies the directory into which the coverage result files will be output. If <code>None</code>, the results for each source file are placed in its directory.</p> </dd>
</dl> </dd>
</dl> <p>A simple example demonstrating the use of the programmatic interface:</p> <pre data-language="python">import sys
import 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 tracer
tracer.run('main()')

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")
</pre> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/trace.html" class="_attribution-link">https://docs.python.org/3.12/library/trace.html</a>
  </p>
</div>