Mr.Combet Webshell 🔥

Edit File Name : trace.html

<!DOCTYPE html>

<title>trace — Trace or track Python statement execution &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
 
 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />
 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />
 
 <script src="../_static/documentation_options.js?v=2c828074"></script>
 <script src="../_static/doctools.js?v=888ff710"></script>
 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
 
 <script src="../_static/sidebar.js"></script>
 
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python 3.12.3 documentation"
 href="../_static/opensearch.xml"/>
 <link rel="author" title="About these documents" href="../about.html" />
 <link rel="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.html" />
 <link rel="copyright" title="Copyright" href="../copyright.html" />
 <link rel="next" title="tracemalloc — Trace memory allocations" href="tracemalloc.html" />
 <link rel="prev" title="timeit — Measure execution time of small code snippets" href="timeit.html" />
 <link rel="canonical" href="https://docs.python.org/3/library/trace.html" />

</head>
<body>
<div class="mobile-nav">
 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
 <nav class="nav-content" role="navigation">
 <label for="menuToggler" class="toggler__label">
 
 </label>
 
 <a href="https://www.python.org/" class="nav-logo">
 <img src="../_static/py.svg" alt="Python logo"/>
 </a>
 
 <form role="search" class="search" action="../search.html" method="get">
 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
 </svg>
 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
 <input type="submit" value="Go"/>
 </form>
 
 </nav>
 <div class="menu-wrapper">
 <nav class="menu" role="navigation" aria-label="main navigation">
 <div class="language_switcher_placeholder"></div>
 
<label class="theme-selector-label">
 Theme
 <select class="theme-selector" oninput="activateTheme(this.value)">
 <option value="auto" selected>Auto</option>
 <option value="light">Light</option>
 <option value="dark">Dark</option>
 </select>
</label>
 <div>
 <h3><a href="../contents.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate">trace</code> — Trace or track Python statement execution</a><ul>
<li><a class="reference internal" href="#command-line-usage">Command-Line Usage</a><ul>
<li><a class="reference internal" href="#main-options">Main options</a></li>
<li><a class="reference internal" href="#modifiers">Modifiers</a></li>
<li><a class="reference internal" href="#filters">Filters</a></li>
</ul>
</li>
<li><a class="reference internal" href="#programmatic-interface">Programmatic Interface</a></li>
</ul>
</li>
</ul>

</div>
 <div>
 <h4>Previous topic</h4>
 <a href="timeit.html"
 title="previous chapter"><code class="xref py py-mod docutils literal notranslate">timeit</code> — Measure execution time of small code snippets</a>
 </div>
 <div>
 <h4>Next topic</h4>
 <a href="tracemalloc.html"
 title="next chapter"><code class="xref py py-mod docutils literal notranslate">tracemalloc</code> — Trace memory allocations</a>
 </div>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../bugs.html">Report a Bug</a></li>
 <li>
 <a href="https://github.com/python/cpython/blob/main/Doc/library/trace.rst"
 rel="nofollow">Show Source
 </a>
 </li>
 </ul>
 </div>
 </nav>
 </div>
</div>

<div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="tracemalloc.html" title="tracemalloc — Trace memory allocations"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="timeit.html" title="timeit — Measure execution time of small code snippets"
 accesskey="P">previous</a> |</li>

<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="https://www.python.org/">Python</a> &#187;</li>
 <li class="switchers">
 <div class="language_switcher_placeholder"></div>
 <div class="version_switcher_placeholder"></div>
 </li>
 <li>
 
 </li>
 <li id="cpython-language-and-version">
 <a href="../index.html">3.12.3 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="debug.html" accesskey="U">Debugging and Profiling</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate">trace</code> — Trace or track Python statement execution</a></li>
 <li class="right">

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="module-trace">
<h1><a class="reference internal" href="#module-trace" title="trace: Trace or track Python statement execution."><code class="xref py py-mod docutils literal notranslate">trace</code></a> — Trace or track Python statement execution<a class="headerlink" href="#module-trace" title="Link to this heading">¶</a></h1>
Source code: <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/trace.py">Lib/trace.py</a>
<hr class="docutils" />
The <a class="reference internal" href="#module-trace" title="trace: Trace or track Python statement execution."><code class="xref py py-mod docutils literal notranslate">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.
<div class="admonition seealso">
See also
<dl class="simple">
<dt><a class="reference external" href="https://coverage.readthedocs.io/">Coverage.py</a></dt><dd>A popular third-party coverage tool that provides HTML
output along with advanced features such as branch coverage.
</dd>
</dl>
</div>
<section id="command-line-usage">
<h2>Command-Line Usage<a class="headerlink" href="#command-line-usage" title="Link to this heading">¶</a></h2>
The <a class="reference internal" href="#module-trace" title="trace: Trace or track Python statement execution."><code class="xref py py-mod docutils literal notranslate">trace</code></a> module can be invoked from the command line. It can be as
simple as
<div class="highlight-python3 notranslate"><div class="highlight"><pre>python -m trace --count -C . somefile.py ...
</pre></div>
</div>
The above will execute <code class="file docutils literal notranslate">somefile.py</code> and generate annotated listings of
all Python modules imported during the execution into the current directory.
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-help">
--help<a class="headerlink" href="#cmdoption-trace-help" title="Link to this definition">¶</a></dt>
<dd>Display usage and exit.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-version">
--version<a class="headerlink" href="#cmdoption-trace-version" title="Link to this definition">¶</a></dt>
<dd>Display the version of the module and exit.
</dd></dl>

<div class="versionadded">
New in version 3.8: Added <code class="docutils literal notranslate">--module</code> option that allows to run an executable module.
</div>
<section id="main-options">
<h3>Main options<a class="headerlink" href="#main-options" title="Link to this heading">¶</a></h3>
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 class="xref py py-mod docutils literal notranslate">trace</code></a>. The <a class="reference internal" href="#cmdoption-trace-l"><code class="xref std std-option docutils literal notranslate">--listfuncs</code></a> option is mutually exclusive with
the <a class="reference internal" href="#cmdoption-trace-t"><code class="xref std std-option docutils literal notranslate">--trace</code></a> and <a class="reference internal" href="#cmdoption-trace-c"><code class="xref std std-option docutils literal notranslate">--count</code></a> options. When
<a class="reference internal" href="#cmdoption-trace-l"><code class="xref std std-option docutils literal notranslate">--listfuncs</code></a> is provided, neither <a class="reference internal" href="#cmdoption-trace-c"><code class="xref std std-option docutils literal notranslate">--count</code></a> nor
<a class="reference internal" href="#cmdoption-trace-t"><code class="xref std std-option docutils literal notranslate">--trace</code></a> are accepted, and vice versa.
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-c">
-c, --count<a class="headerlink" href="#cmdoption-trace-c" title="Link to this definition">¶</a></dt>
<dd>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 class="xref std std-option docutils literal notranslate">--coverdir</code></a>, <a class="reference internal" href="#cmdoption-trace-f"><code class="xref std std-option docutils literal notranslate">--file</code></a> and
<a class="reference internal" href="#cmdoption-trace-R"><code class="xref std std-option docutils literal notranslate">--no-report</code></a> below.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-t">
-t, --trace<a class="headerlink" href="#cmdoption-trace-t" title="Link to this definition">¶</a></dt>
<dd>Display lines as they are executed.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-l">
-l, --listfuncs<a class="headerlink" href="#cmdoption-trace-l" title="Link to this definition">¶</a></dt>
<dd>Display the functions executed by running the program.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-r">
-r, --report<a class="headerlink" href="#cmdoption-trace-r" title="Link to this definition">¶</a></dt>
<dd>Produce an annotated list from an earlier program run that used the
<a class="reference internal" href="#cmdoption-trace-c"><code class="xref std std-option docutils literal notranslate">--count</code></a> and <a class="reference internal" href="#cmdoption-trace-f"><code class="xref std std-option docutils literal notranslate">--file</code></a> option. This does not
execute any code.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-T">
-T, --trackcalls<a class="headerlink" href="#cmdoption-trace-T" title="Link to this definition">¶</a></dt>
<dd>Display the calling relationships exposed by running the program.
</dd></dl>

</section>
<section id="modifiers">
<h3>Modifiers<a class="headerlink" href="#modifiers" title="Link to this heading">¶</a></h3>
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-f">
-f, --file=&lt;file&gt;<a class="headerlink" href="#cmdoption-trace-f" title="Link to this definition">¶</a></dt>
<dd>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 class="xref std std-option docutils literal notranslate">--count</code></a> option.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-C">
-C, --coverdir=&lt;dir&gt;<a class="headerlink" href="#cmdoption-trace-C" title="Link to this definition">¶</a></dt>
<dd>Directory where the report files go. The coverage report for
<code class="docutils literal notranslate">package.module</code> is written to file <code class="file docutils literal notranslate">dir/package/module.cover</code>.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-m">
-m, --missing<a class="headerlink" href="#cmdoption-trace-m" title="Link to this definition">¶</a></dt>
<dd>When generating annotated listings, mark lines which were not executed with
<code class="docutils literal notranslate">&gt;&gt;&gt;&gt;&gt;&gt;</code>.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-s">
-s, --summary<a class="headerlink" href="#cmdoption-trace-s" title="Link to this definition">¶</a></dt>
<dd>When using <a class="reference internal" href="#cmdoption-trace-c"><code class="xref std std-option docutils literal notranslate">--count</code></a> or <a class="reference internal" href="#cmdoption-trace-r"><code class="xref std std-option docutils literal notranslate">--report</code></a>, write a brief
summary to stdout for each file processed.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-R">
-R, --no-report<a class="headerlink" href="#cmdoption-trace-R" title="Link to this definition">¶</a></dt>
<dd>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 class="xref std std-option docutils literal notranslate">--count</code></a>, and then produce a single set of
annotated listings at the end.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-g">
-g, --timing<a class="headerlink" href="#cmdoption-trace-g" title="Link to this definition">¶</a></dt>
<dd>Prefix each line with the time since the program started. Only used while
tracing.
</dd></dl>

</section>
<section id="filters">
<h3>Filters<a class="headerlink" href="#filters" title="Link to this heading">¶</a></h3>
These options may be repeated multiple times.
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-ignore-module">
--ignore-module=&lt;mod&gt;<a class="headerlink" href="#cmdoption-trace-ignore-module" title="Link to this definition">¶</a></dt>
<dd>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.
</dd></dl>

<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-trace-ignore-dir">
--ignore-dir=&lt;dir&gt;<a class="headerlink" href="#cmdoption-trace-ignore-dir" title="Link to this definition">¶</a></dt>
<dd>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.html#os.pathsep" title="os.pathsep"><code class="xref py py-data docutils literal notranslate">os.pathsep</code></a>.
</dd></dl>

</section>
</section>
<section id="programmatic-interface">
<h2>Programmatic Interface<a class="headerlink" href="#programmatic-interface" title="Link to this heading">¶</a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="trace.Trace">
class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)<a class="headerlink" href="#trace.Trace" title="Link to this definition">¶</a></dt>
<dd>Create an object to trace execution of a single statement or expression. All
parameters are optional. count enables counting of line numbers. trace
enables line execution tracing. countfuncs enables listing of the
functions called during the run. countcallers enables call relationship
tracking. ignoremods is a list of modules or packages to ignore.
ignoredirs is a list of directories whose modules or packages should be
ignored. infile is the name of the file from which to read stored count
information. outfile is the name of the file in which to write updated
count information. timing enables a timestamp relative to when tracing was
started to be displayed.
<dl class="py method">
<dt class="sig sig-object py" id="trace.Trace.run">
run(cmd)<a class="headerlink" href="#trace.Trace.run" title="Link to this definition">¶</a></dt>
<dd>Execute the command and gather statistics from the execution with
the current tracing parameters. cmd must be a string or code object,
suitable for passing into <a class="reference internal" href="functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate">exec()</code></a>.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="trace.Trace.runctx">
runctx(cmd, globals=None, locals=None)<a class="headerlink" href="#trace.Trace.runctx" title="Link to this definition">¶</a></dt>
<dd>Execute the command and gather statistics from the execution with the
current tracing parameters, in the defined global and local
environments. If not defined, globals and locals default to empty
dictionaries.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="trace.Trace.runfunc">
runfunc(func, /, *args, **kwds)<a class="headerlink" href="#trace.Trace.runfunc" title="Link to this definition">¶</a></dt>
<dd>Call func with the given arguments under control of the <a class="reference internal" href="#trace.Trace" title="trace.Trace"><code class="xref py py-class docutils literal notranslate">Trace</code></a>
object with the current tracing parameters.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="trace.Trace.results">
results()<a class="headerlink" href="#trace.Trace.results" title="Link to this definition">¶</a></dt>
<dd>Return a <a class="reference internal" href="#trace.CoverageResults" title="trace.CoverageResults"><code class="xref py py-class docutils literal notranslate">CoverageResults</code></a> object that contains the cumulative
results of all previous calls to <code class="docutils literal notranslate">run</code>, <code class="docutils literal notranslate">runctx</code> and <code class="docutils literal notranslate">runfunc</code>
for the given <a class="reference internal" href="#trace.Trace" title="trace.Trace"><code class="xref py py-class docutils literal notranslate">Trace</code></a> instance. Does not reset the accumulated
trace results.
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="trace.CoverageResults">
class trace.CoverageResults<a class="headerlink" href="#trace.CoverageResults" title="Link to this definition">¶</a></dt>
<dd>A container for coverage results, created by <a class="reference internal" href="#trace.Trace.results" title="trace.Trace.results"><code class="xref py py-meth docutils literal notranslate">Trace.results()</code></a>. Should
not be created directly by the user.
<dl class="py method">
<dt class="sig sig-object py" id="trace.CoverageResults.update">
update(other)<a class="headerlink" href="#trace.CoverageResults.update" title="Link to this definition">¶</a></dt>
<dd>Merge in data from another <a class="reference internal" href="#trace.CoverageResults" title="trace.CoverageResults"><code class="xref py py-class docutils literal notranslate">CoverageResults</code></a> object.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="trace.CoverageResults.write_results">
write_results(show_missing=True, summary=False, coverdir=None)<a class="headerlink" href="#trace.CoverageResults.write_results" title="Link to this definition">¶</a></dt>
<dd>Write coverage results. Set show_missing to show lines that had no
hits. Set summary to include in the output the coverage summary per
module. coverdir specifies the directory into which the coverage
result files will be output. If <code class="docutils literal notranslate">None</code>, the results for each source
file are placed in its directory.
</dd></dl>

</dd></dl>

A simple example demonstrating the use of the programmatic interface:
<div class="highlight-python3 notranslate"><div class="highlight"><pre>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(&#39;main()&#39;)

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=&quot;.&quot;)
</pre></div>
</div>
</section>
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <div>
 <h3><a href="../contents.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate">trace</code> — Trace or track Python statement execution</a><ul>
<li><a class="reference internal" href="#command-line-usage">Command-Line Usage</a><ul>
<li><a class="reference internal" href="#main-options">Main options</a></li>
<li><a class="reference internal" href="#modifiers">Modifiers</a></li>
<li><a class="reference internal" href="#filters">Filters</a></li>
</ul>
</li>
<li><a class="reference internal" href="#programmatic-interface">Programmatic Interface</a></li>
</ul>
</li>
</ul>

</div>
 <div class="clearer"></div>
 </div> 
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="tracemalloc.html" title="tracemalloc — Trace memory allocations"
 >next</a> |</li>
 <li class="right" >
 <a href="timeit.html" title="timeit — Measure execution time of small code snippets"
 >previous</a> |</li>

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="debug.html" >Debugging and Profiling</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate">trace</code> — Trace or track Python statement execution</a></li>
 <li class="right">

<div class="inline-search" role="search">
 <form class="inline-search" action="../search.html" method="get">
 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
 <input type="submit" value="Go" />
 </form>
 </div>
 |
 </li>
 <li class="right">
<label class="theme-selector-label">
 Theme
 <select class="theme-selector" oninput="activateTheme(this.value)">
 <option value="auto" selected>Auto</option>
 <option value="light">Light</option>
 <option value="dark">Dark</option>
 </select>
</label> |</li>
 
 </ul>
 </div> 
 <div class="footer">
 &copy; 
 <a href="../copyright.html">
 
 Copyright
 
 </a>
 2001-2024, Python Software Foundation.
 
 This page is licensed under the Python Software Foundation License Version 2.
 
 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
 
 
 See <a href="/license.html">History and License</a> for more information.

The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
 
 
 Last updated on Apr 09, 2024 (13:47 UTC).
 
 <a href="/bugs.html">Found a bug</a>?

Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
 </div>

</body>
</html>