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, *, ignore_missing_files=False)¶
寫入覆蓋率結果。將 show_missing 設定為顯示沒有被執行的行。將 summary 設定為在輸出中包含每個模組的覆蓋率摘要。coverdir 指定覆蓋率結果檔案將輸出到的目錄。如果為
None，則每個原始檔的結果將放置在其目錄中。如果 ignore_missing_files 為
True，則對於不再存在的檔案，其覆蓋率計數將被靜默忽略。否則，缺少檔案將引發FileNotFoundError。在 3.13 版本中修改: 添加了 ignore_missing_files 引數。
一個演示程式設計介面使用的簡單示例
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=".")