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

源代码： Lib / trace.py

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

27.6.1. Command-Line Usage

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

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

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

--help

显示用法并退出。

--version

显示模块和退出的版本。

27.6.1.1. Main options

调用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. Modifiers

-f, --file=<file>

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

-C, --coverdir=<dir>

在哪里报告文件的目录。package.module的覆盖率报告写入文件dir / package / modulecover。

-m, --missing

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

-s, --summary

当使用--count或--report时，为每个处理的文件写入一个简短摘要到stdout。

-R, --no-report

不会产生附加说明的清单。如果您打算使用--count进行多个运行，然后在末尾生成一组带注释的列表，这将非常有用。

-g, --timing

自项目开始以来的前缀与时俱进的每一行。仅用于跟踪时。

27.6.1.3. Filters

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

--ignore-module=<mod>

每个给定的模块名称和其模忽略 （如果它是一个包）。参数可以是以逗号分隔的名称的列表。

--ignore-dir=<dir>

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

27.6.2. Programmatic Interface

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

创建跟踪执行单个语句或表达式的对象。所有参数都是可选的。计数，使计数的行号。跟踪启用行执行跟踪。countfuncs使上市期间调用的函数中运行。countcallers使调用关系跟踪。ignoremods是一个模块或忽视的包的列表。ignoredirs是应忽略其模块或软件包的目录列表。infile是要从中读取存储的计数信息文件的名称。文件的输出是文件的在其中写入更新的计数信息的名称。时已启动跟踪显示，定时启用相对于一个时间戳。

run(cmd)

Execute the command and gather statistics from the execution with the current tracing parameters. cmd must be a string or code object, suitable for passing into exec().

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

Execute the command and gather statistics from the execution with the current tracing parameters, in the defined global and local environments. If not defined, globals and locals default to empty dictionaries.

runfunc(func, *args, **kwds)

Call func with the given arguments under control of the Trace object with the current tracing parameters.

results()

Return a CoverageResults object that contains the cumulative results of all previous calls to run, runctx and runfunc for the given Trace instance. Does not reset the accumulated trace results.

class trace.CoverageResults

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

update(other)

Merge in data from another CoverageResults object.

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

Write coverage results. Set show_missing to show lines that had no hits. Set summary to include in the output the coverage summary per module. coverdir specifies the directory into which the coverage result files will be output. If None, the results for each source file are placed in its directory.

一个简单的示例演示使用的编程接口：

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