26.7. 痕迹 — 跟踪或跟踪 Python 语句的执行

源代码： :source:`Lib/trace.py`

trace 模块允许您跟踪程序执行、生成带注释的语句覆盖列表、打印调用者/被调用者关系并列出程序运行期间执行的函数。它可以在另一个程序中或从命令行中使用。

26.7.1. 命令行使用

trace 模块可以从命令行调用。它可以很简单

python -m trace --count -C . somefile.py ...

以上将执行 somefile.py 并生成在执行期间导入到当前目录中的所有 Python 模块的带注释的列表。

--help: 显示使用情况并退出。

--version: 显示模块版本并退出。

26.7.1.1. 主要选项

调用 trace 时，必须至少指定以下选项之一。 --listfuncs 选项与 --trace 和 --count 选项互斥。当提供 --listfuncs 时，既不接受 --count 也不接受 --trace，反之亦然。

-c, --count: 在程序完成时生成一组带注释的列表文件，显示每个语句的执行次数。另请参阅下面的 --coverdir、--file 和 --no-report。

-t, --trace: 在执行时显示行。

-l, --listfuncs: 显示通过运行程序执行的功能。

-r, --report: 从使用 --count 和 --file 选项的较早程序运行生成带注释的列表。这不会执行任何代码。

-T, --trackcalls: 显示通过运行程序暴露的调用关系。

26.7.1.2. 修饰符

-f, --file=<file>: 在多次跟踪运行中累积计数的文件名称。应与 --count 选项一起使用。

-C, --coverdir=<dir>: 报告文件所在的目录。 package.module 的覆盖率报告写入文件 dir/package/module.cover。

-m, --missing: 生成带注释的列表时，标记未使用 >>>>>> 执行的行。

-s, --summary: 使用 --count 或 --report 时，为每个处理的文件向标准输出写入简要摘要。

-R, --no-report: 不要生成带注释的列表。如果您打算使用 --count 进行多次运行，然后在最后生成一组带注释的列表，这将非常有用。

-g, --timing: 用程序启动以来的时间作为每行的前缀。仅在跟踪时使用。

26.7.1.3. 过滤器

这些选项可能会重复多次。

--ignore-module=<mod>: 忽略每个给定的模块名称及其子模块（如果它是一个包）。参数可以是用逗号分隔的名称列表。

--ignore-dir=<dir>: 忽略命名目录和子目录中的所有模块和包。参数可以是由 os.pathsep 分隔的目录列表。

26.7.2. 编程接口

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 启用与开始显示跟踪时间相关的时间戳。

run(cmd)

执行命令并使用当前跟踪参数从执行中收集统计信息。 cmd 必须是字符串或代码对象，适合传入exec()。

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

在定义的全局和本地环境中，使用当前跟踪参数执行命令并从执行中收集统计信息。如果未定义，globals 和 locals 默认为空字典。

runfunc(func, *args, **kwds)

在具有当前跟踪参数的 Trace 对象的控制下，使用给定参数调用 func。

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