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