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

源代码: Lib/trace.py


trace模块允许您跟踪程序执行,生成带 Comments 的语句覆盖列表,打印调用方/被调用方关系以及列出在程序运行期间执行的Function。可以在其他程序中或从命令行中使用它。

26.7.1. 命令行用法

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

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

上面的代码将执行somefile.py并生成在执行过程中导入到当前目录中的所有 Python 模块的带 Comments 的列表。

  • --help ``

    • 显示用法并退出。
  • --version ``

    • 显示模块的版本并退出。

26.7.1.1. 主要选项

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

  • -c `,` `--count`

    • 在程序完成时产生一组带 Comments 的 Lists 文件,该文件显示每个语句执行了多少次。另请参见下面的--coverdir--file--no-report
  • -t `,` `--trace`

    • 在执行时显示行。
  • -l `,` `--listfuncs`

    • 显示pass运行程序执行的Function。
  • -r `,` `--report`

    • 从使用--count--file选项的较早程序运行中生成带 Comments 的列表。这不会执行任何代码。
  • -T `,` `--trackcalls`

    • 显示pass运行程序公开的呼叫关系。

26.7.1.2. Modifiers

  • -f `` , --file =<file>

    • 要在多个跟踪运行中累积计数的文件名。应该与--count选项一起使用。
  • -C `` , --coverdir =<dir>

    • 报告文件所在的目录。 package.module的覆盖率报告已写入文件dir/package/module.cover
  • -m `,` `--missing`

    • 生成带 Comments 的列表时,标记未使用>>>>>>执行的行。
  • -s `,` `--summary`

    • 使用--count--report时,为每个处理的文件向 stdout 编写一个简短的摘要。
  • -R `,` `--no-report`

    • 不要生成带 Comments 的列表。如果您打算使用--count进行多次运行,然后在末尾生成一组带 Comments 的 Lists,则这很有用。
  • -g `,` `--timing`

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

26.7.1.3. Filters

这些选项可以重复多次。

  • --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 *启用相对于开始显示跟踪的时间戳。

Note

  • run(* cmd *)

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

  • runctx(* cmd globals = None locals = None *)

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

  • runfunc(* func *, *args * kwds *)

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

  • results ( )

  • 返回一个CoverageResults对象,该对象包含给定Trace实例以前对runrunctxrunfunc的所有先前调用的累积结果。不重置累积的跟踪结果。

  • 类别 trace. CoverageResults
    • Trace.results()创建的用于覆盖结果的容器。不应由用户直接创建。

Note

  • update(其他)

  • 合并来自另一个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=".")