new repository

1 files changed, 94 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Ftrace.html b/devdocs/python~3.12/library%2Ftrace.html
new file mode 100644
index 00000000..4633bb5d
--- /dev/null
+++ b/devdocs/python~3.12/library%2Ftrace.html
@@ -0,0 +1,94 @@
+ <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>