trace — 跟踪或追溯 Python 语句的执行¶
源代码： Lib/trace.py
trace 模块允许你跟踪程序执行，生成带注释的语句覆盖率列表，打印调用者/被调用者关系，并列出程序运行期间执行的函数。它可以用于另一个程序或从命令行使用。
另请参阅
- Coverage.py
一个流行的第三方覆盖率工具，提供 HTML 输出以及诸如分支覆盖率等高级功能。
命令行用法¶
可以从命令行调用 trace 模块。它可以像下面这样简单：
python -m trace --count -C . somefile.py ...
以上命令将执行 somefile.py，并在当前目录下生成执行期间导入的所有 Python 模块的带注释列表。
- --help¶
显示用法并退出。
- --version¶
显示模块版本并退出。
3.8 版本新增: 添加了 --module 选项，允许运行可执行模块。
主要选项¶
在调用 trace 时，必须至少指定以下选项之一。--listfuncs 选项与 --trace 和 --count 选项互斥。当提供 --listfuncs 时，--count 和 --trace 均不接受，反之亦然。
- -c, --count¶
在程序完成后生成一组带注释的列表文件，显示每个语句执行的次数。另请参阅下面的
--coverdir、--file和--no-report。
- -t, --trace¶
显示执行的行。
- -l, --listfuncs¶
显示运行程序执行的函数。
- -T, --trackcalls¶
显示运行程序暴露的调用关系。
修饰符¶
- -C, --coverdir=<dir>¶
报告文件所在的目录。
package.module的覆盖率报告写入文件dir/package/module.cover。
- -m, --missing¶
在生成带注释的列表时，用
>>>>>>标记未执行的行。
- -g, --timing¶
在每行的开头添加程序启动以来的时间。仅在跟踪时使用。
过滤器¶
这些选项可以重复多次。
- --ignore-module=<mod>¶
忽略每个给定的模块名称及其子模块（如果它是一个包）。参数可以是逗号分隔的名称列表。
- --ignore-dir=<dir>¶
忽略指定目录和子目录中的所有模块和包。参数可以是
os.pathsep分隔的目录列表。
程序化接口¶
- class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)¶
创建一个对象来跟踪单个语句或表达式的执行。所有参数都是可选的。count 启用行号计数。trace 启用行执行跟踪。countfuncs 启用在运行期间调用的函数列表。countcallers 启用调用关系跟踪。ignoremods 是要忽略的模块或包的列表。ignoredirs 是应忽略其模块或包的目录列表。infile 是从中读取存储的计数信息的文件名。outfile 是在其中写入更新的计数信息的文件名。timing 启用显示相对于跟踪开始时间的 时间戳。
- runctx(cmd, globals=None, locals=None)¶
在定义的全局和本地环境中，执行命令并使用当前跟踪参数从执行中收集统计信息。如果未定义，则 globals 和 locals 默认为空字典。
- results()¶
返回一个
CoverageResults对象，该对象包含给定Trace实例之前所有对run、runctx和runfunc的累积结果。不重置累积的跟踪结果。
- class trace.CoverageResults¶
由
Trace.results()创建的覆盖率结果的容器。不应由用户直接创建。- update(other)¶
合并来自另一个
CoverageResults对象的数据。
- write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)¶
写入覆盖率结果。设置 show_missing 以显示没有命中的行。设置 summary 以在输出中包含每个模块的覆盖率摘要。coverdir 指定覆盖率结果文件将输出到的目录。如果为
None，则每个源文件的结果都将放置在其目录中。如果 ignore_missing_files 为
True，则会静默忽略不再存在的文件覆盖率计数。否则，缺少的文件将引发FileNotFoundError。3.13 版本更改: 添加了 ignore_missing_files 参数。
一个简单的示例，演示了程序化接口的使用
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=".")