:mod:`!trace` --- Trace or track Python statement execution
Python 3.14 Docs · نسخهٔ 3.14.10 · PSF License
:mod:!trace --- Trace or track Python statement execution
:synopsis: Trace or track Python statement execution.
Source code: Lib/trace.py
--------------
The !trace 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.
Coverage.py <https://coverage.readthedocs.io/>_ A popular third-party coverage tool that provides HTML output along with advanced features such as branch coverage.
Command-Line Usage
The !trace module can be invoked from the command line. It can be as simple as ::
python -m trace --count -C . somefile.py ...
The above will execute somefile.py and generate annotated listings of all Python modules imported during the execution into the current directory.
Display usage and exit.
Display the version of the module and exit.
Added `--module` option that allows running an executable module.
Main options
At least one of the following options must be specified when invoking !trace. The --listfuncs <-l> option is mutually exclusive with the --trace <-t> and --count <-c> options. When --listfuncs <-l> is provided, neither --count <-c> nor --trace <-t> are accepted, and vice versa.
Produce a set of annotated listing files upon program completion that shows how many times each statement was executed. See also --coverdir <-C>, --file <-f> and --no-report <-R> below.
Display lines as they are executed.
Display the functions executed by running the program.
Produce an annotated list from an earlier program run that used the --count <-c> and --file <-f> option. This does not execute any code.
Display the calling relationships exposed by running the program.
Modifiers
Name of a file to accumulate counts over several tracing runs. Should be used with the --count <-c> option.
Directory where the report files go. The coverage report for `package.module is written to file {dir}/{package}/{module}.cover`.
When generating annotated listings, mark lines which were not executed with `>>>>>>`.
When using --count <-c> or --report <-r>, write a brief summary to stdout for each file processed.
Do not generate annotated listings. This is useful if you intend to make several runs with --count <-c>, and then produce a single set of annotated listings at the end.
Prefix each line with the time since the program started. Only used while tracing.
Filters
These options may be repeated multiple times.
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.
Ignore all modules and packages in the named directory and subdirectories. The argument can be a list of directories separated by os.pathsep.
Programmatic Interface
ignoredirs=(), infile=None, outfile=None, timing=False)
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.
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 exec.
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.
Call *func* with the given arguments under control of the Trace object with the current tracing parameters.
Return a CoverageResults object that contains the cumulative results of all previous calls to `run, runctx and runfunc for the given Trace` instance. Does not reset the accumulated trace results.
A container for coverage results, created by Trace.results. Should not be created directly by the user.
Merge in data from another CoverageResults object.
*, ignore_missing_files=False)
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 `None`, the results for each source file are placed in its directory.
If *ignore_missing_files* is `True, coverage counts for files that no longer exist are silently ignored. Otherwise, a missing file will raise a FileNotFoundError`.
Added *ignore_missing_files* parameter.
A simple example demonstrating the use of the programmatic interface::
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=".")