trace — Trace or track Python statement execution跟踪或跟踪Python语句执行

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. trace模块允许您跟踪程序执行、生成带注释的语句覆盖率列表、打印调用者/被调用者关系以及在程序运行期间执行的函数列表。It can be used in another program or from the command line.它可以在其他程序中使用，也可以从命令行使用。

See also

Coverage.py

A popular third-party coverage tool that provides HTML output along with advanced features such as branch coverage.一种流行的第三方覆盖工具，提供HTML输出以及分支覆盖等高级功能。

Command-Line Usage命令行用法

The trace module can be invoked from the command line. 可以从命令行调用trace模块。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.上面的命令将执行somefile.py并生成在执行过程中导入当前目录的所有Python模块的注释列表。

--help

Display usage and exit.显示用法并退出。

--version

Display the version of the module and exit.显示模块版本并退出。

New in version 3.8.版本3.8中新增。Added --module option that allows to run an executable module.添加了--module选项，允许运行可执行模块。

Main options主要选项

At least one of the following options must be specified when invoking trace. 调用trace时，必须至少指定以下选项之一。The --listfuncs option is mutually exclusive with the --trace and --count options. --listfuncs选项与--trace和--count选项互斥。When --listfuncs is provided, neither --count nor --trace are accepted, and vice versa.当提供--listfuncs时，不接受--count和--trace，反之亦然。

-c,--count

Produce a set of annotated listing files upon program completion that shows how many times each statement was executed. 在程序完成时生成一组带注释的列表文件，显示每个语句执行的次数。See also --coverdir, --file and --no-report below.另请参阅下面的--coverdir、--file和--no-report。

-t,--trace

Display lines as they are executed.执行时显示行。

-l,--listfuncs

Display the functions executed by running the program.显示通过运行程序执行的功能。

-r,--report

Produce an annotated list from an earlier program run that used the --count and --file option. 从使用--count和--file选项的早期程序运行中生成一个带注释的列表。This does not execute any code.这不会执行任何代码。

-T,--trackcalls

Display the calling relationships exposed by running the program.显示通过运行程序公开的调用关系。

Modifiers修饰符

-f,--file=<file>

Name of a file to accumulate counts over several tracing runs. 要在多次跟踪运行中累积计数的文件的名称。Should be used with the --count option.应与--count选项一起使用。

-C,--coverdir=<dir>

Directory where the report files go. 报告文件所在的目录。The coverage report for package.module is written to file dir/package/module.cover.package.module的覆盖率报告写入文件dir/package/module.cover。

-m,--missing

When generating annotated listings, mark lines which were not executed with >>>>>>.生成带注释的列表时，标记未使用>>>>>>执行的行。

-s,--summary

When using --count or --report, write a brief summary to stdout for each file processed.当使用--count或--report时，为处理的每个文件向stdout写入一个简短摘要。

-R,--no-report

Do not generate annotated listings. 不要生成带注释的列表。This is useful if you intend to make several runs with --count, and then produce a single set of annotated listings at the end.如果您打算使用--count进行多次运行，然后在最后生成一组带注释的列表，这将非常有用。

-g,--timing

Prefix each line with the time since the program started. Only used while tracing.在每行前面加上程序启动后的时间。仅在跟踪时使用。

Filters筛选器

These options may be repeated multiple times.这些选项可以重复多次。

--ignore-module=<mod>

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-dir=<dir>

Ignore all modules and packages in the named directory and subdirectories. 忽略命名目录和子目录中的所有模块和包。The argument can be a list of directories separated by os.pathsep.参数可以是由os.pathsep分隔的目录列表。

Programmatic Interface编程接口

classtrace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), 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. count启用行号计数。trace enables line execution tracing. trace启用行执行跟踪。countfuncs enables listing of the functions called during the run. countfuncs允许列出运行期间调用的函数。countcallers enables call relationship tracking. countcallers启用呼叫关系跟踪。ignoremods is a list of modules or packages to ignore. ignoremods是要忽略的模块或包的列表。ignoredirs is a list of directories whose modules or packages should be ignored. ignoredirs是应忽略其模块或包的目录列表。infile is the name of the file from which to read stored count information. infile是从中读取存储的计数信息的文件的名称。outfile is the name of the file in which to write updated count information. outfile是要在其中写入更新计数信息的文件的名称。timing enables a timestamp relative to when tracing was started to be displayed.timing允许显示与跟踪开始时间相关的时间戳。

run(cmd)

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().cmd必须是字符串或代码对象，适合传递给exec()。

runctx(cmd, globals=None, locals=None)

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.如果未定义，globals和locals默认为空字典。

runfunc(func, /, *args, **kwds)

Call func with the given arguments under control of the Trace object with the current tracing parameters.使用当前跟踪参数在Trace对象的控制下使用给定参数调用func。

results()

Return a CoverageResults object that contains the cumulative results of all previous calls to run, runctx and runfunc for the given Trace instance. 返回CoverageResults对象，该对象包含给定Trace实例的所有先前调用run、runctx和runfunc的累积结果。Does not reset the accumulated trace results.不重置累积的跟踪结果。

classtrace.CoverageResults

A container for coverage results, created by Trace.results(). 覆盖率结果的容器，由Trace.results()创建。Should not be created directly by the user.不应由用户直接创建。

update(other)

Merge in data from another CoverageResults object.合并来自另一个CoverageResults对象的数据。

write_results(show_missing=True, summary=False, coverdir=None)

Write coverage results. 写入覆盖率结果。Set show_missing to show lines that had no hits. 设置show_missing以显示没有命中的行。Set summary to include in the output the coverage summary per module. 设置summary以在输出中包含每个模块的覆盖率摘要。coverdir specifies the directory into which the coverage result files will be output. coverdir指定覆盖率结果文件将输出到的目录。If None, the results for each source file are placed in its directory.如果为None，则每个源文件的结果将放置在其目录中。

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=".")