Skip to main content

27.6. trace —跟踪或跟踪Python语句执行

源代码: Lib/trace.py


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

27.6.1. 命令行用法

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

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

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

--help

显示使用和退出。

--version

显示模块的版本并退出。

27.6.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

显示通过运行程序暴露的调用关系。

27.6.1.2. 修饰符

-f, --file=<file>

要累积的文件的名称在多个跟踪运行中计数。应与 --count 选项一起使用。

-C, --coverdir=<dir>

报告文件所在的目录。 package.module 的覆盖报告写入文件 dir/package/module.cover

-m, --missing

生成带注释的列表时,请标记未使用 >>>>>> 执行的行。

-s, --summary

当使用 --count--report 时,为每个处理的文件写入stdout的简要摘要。

-R, --no-report

不生成带注释的商家信息。如果您打算使用 --count 进行多次运行,然后在最后生成一组带注释的列表,这将非常有用。

-g, --timing

前缀每行与自程序启动以来的时间。仅在跟踪时使用。

27.6.1.3. 过滤器

这些选项可以重复多次。

--ignore-module=<mod>

忽略每个给定的模块名称及其子模块(如果它是一个包)。参数可以是由逗号分隔的名称列表。

--ignore-dir=<dir>

忽略命名目录和子目录中的所有模块和软件包。参数可以是由 os.pathsep 分隔的目录的列表。

27.6.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)

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

runfunc(func, *args, **kwds)

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

results()

返回包含给定 Trace 实例的所有先前对 runrunctxrunfunc 的调用的累积结果的 CoverageResults 对象。不复位累积的跟踪结果。

class trace.CoverageResults

覆盖结果的容器,由 Trace.results() 创建。不应该由用户直接创建。

update(other)

合并来自另一个 CoverageResults 对象的数据。

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

写覆盖结果。设置 show_missing 以显示没有命中的行。设置 summary 以在输出中包括每个模块的coverage概要。 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=".")