命令列用法¶

trace 模組可從命令列執行，用法可以非常簡單，如：:

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

上述命令會執行 somefile.py，並將產生執行期間所引入的所有 Python 模組的帶註解串列，輸出至目前目錄。

--help¶

顯示用法並結束程式。

--version¶

顯示模組版本並結束程式。

程式介面¶

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, *, ignore_missing_files=False)¶

寫入涵蓋範圍結果。將 show_missing 設為真可顯示未被執行的程式碼行；將 summary 設為真則會在輸出中加入每個模組的涵蓋範圍摘要。coverdir 指定輸出涵蓋範圍結果檔案的目錄，若為 None，則每個原始檔案的結果會輸出至其所在目錄中。

若 ignore_missing_files 為 True，則會忽略那些已不存在的檔案的涵蓋範圍資料，不會顯示任何錯誤。否則，缺少的檔案將會引發 FileNotFoundError。

在 3.13 版的變更: 新增 ignore_missing_files 參數。

以下是一個簡單範例，展示如何使用程式介面：

import sys
import trace

# 建立一個 Trace 物件，指定要忽略的目錄，
# 並設定是否進行追蹤、行數統計或兩者皆做。
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# 使用該 tracer 執行新的命令
tracer.run('main()')

# 建立報告，將輸出放在目前目錄中
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")