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)¶
写入覆盖率结果。将 show_missing 设置为显示没有命中的行。将 summary 设置为在输出中包含每个模块的覆盖率摘要。coverdir 指定覆盖率结果文件将输出到的目录。如果
None，则每个源文件的覆盖率结果将放置在该目录中。
演示如何使用编程接口的一个简单示例
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=".")