bdb — 偵錯程式框架

原始碼： Lib/bdb.py

bdb 模組處理基本的偵錯程式功能，例如設定斷點或透過偵錯程式管理執行。

定義了以下異常

exception bdb.BdbQuit

Bdb 類引發的異常，用於退出偵錯程式。

bdb 模組還定義了兩個類

class bdb.Breakpoint(self, file, line, temporary=False, cond=None, funcname=None)

此類實現臨時斷點、忽略計數、停用和（重新）啟用以及條件。

斷點透過名為 bpbynumber 的列表按數字索引，並透過 (file, line) 對透過 bplist 索引。前者指向 Breakpoint 類的單個例項。後者指向此類例項的列表，因為每行可能存在多個斷點。

建立斷點時，其關聯的 file name 應該採用規範形式。如果定義了 funcname，則當執行該函式的第一行時，將計算斷點 hit。conditional 斷點始終計算 hit。

Breakpoint 例項具有以下方法

deleteMe()

從與檔案/行關聯的列表中刪除斷點。如果它是該位置的最後一個斷點，它還會刪除檔案/行的條目。

enable()

將斷點標記為啟用。

disable()

將斷點標記為停用。

bpformat()

返回一個字串，其中包含有關斷點的所有資訊，格式良好

  • 斷點編號。

  • 臨時狀態（刪除或保留）。

  • 檔案/行位置。

  • 斷點條件。

  • 要忽略的次數。

  • 命中的次數。

3.2 版本新增。

bpprint(out=None)

將 bpformat() 的輸出列印到檔案 out，如果它是 None，則列印到標準輸出。

Breakpoint 例項具有以下屬性

file

Breakpoint 的檔名。

line

file 中 Breakpoint 的行號。

temporary

如果 (file, line) 處的 Breakpoint 是臨時的，則為 True。

cond

用於評估 (file, line) 處的 Breakpoint 的條件。

funcname

定義是否在進入函式時命中 Breakpoint 的函式名。

enabled

如果 Breakpoint 已啟用，則為 True。

bpbynumber

Breakpoint 單個例項的數字索引。

bplist

由 (file, line) 元組索引的 Breakpoint 例項的字典。

ignore

忽略 Breakpoint 的次數。

hits

Breakpoint 被命中的次數計數。

class bdb.Bdb(skip=None)

Bdb 類充當通用的 Python 偵錯程式基類。

此類負責跟蹤工具的細節；派生類應實現使用者互動。標準偵錯程式類 (pdb.Pdb) 就是一個例子。

如果給定 skip 引數，它必須是 glob 樣式的模組名稱模式的可迭代物件。偵錯程式不會步入與這些模式之一匹配的模組中產生的幀。一個幀是否被認為起源於某個模組，由幀全域性變數中的 __name__ 決定。

在 3.1 版本中更改: 添加了 skip 引數。

Bdb 的以下方法通常不需要被重寫。

canonic(filename)

返回 *filename* 的規範形式。

對於真實的檔名，規範形式是作業系統相關的、大小寫規範化 的 絕對 路徑。帶有尖括號的 *filename*，例如互動模式下生成的 "<stdin>"，將保持不變地返回。

reset()

使用準備開始除錯的值設定 botframe, stopframe, returnframe 和 quitting 屬性。

trace_dispatch(frame, event, arg)

此函式作為被除錯幀的跟蹤函式安裝。其返回值是新的跟蹤函式（在大多數情況下，就是它本身）。

預設實現根據將要執行的事件型別（作為字串傳遞）決定如何排程幀。*event* 可以是以下之一

  • "line": 即將執行新的程式碼行。

  • "call": 即將呼叫函式，或進入另一個程式碼塊。

  • "return": 函式或其他程式碼塊即將返回。

  • "exception": 發生了一個異常。

  • "c_call": 即將呼叫 C 函式。

  • "c_return": C 函式已返回。

  • "c_exception": C 函式引發了一個異常。

對於 Python 事件，會呼叫專門的函式（見下文）。對於 C 事件，不採取任何操作。

arg 引數取決於之前的事件。

有關跟蹤函式的更多資訊，請參閱 sys.settrace() 的文件。有關程式碼和幀物件的更多資訊，請參閱 標準型別層級結構。

dispatch_line(frame)

如果偵錯程式應該在當前行停止，則呼叫 user_line() 方法（應在子類中重寫）。如果設定了 quitting 標誌（可以從 user_line() 設定），則引發 BdbQuit 異常。返回對 trace_dispatch() 方法的引用，以便在該範圍內進行進一步跟蹤。

dispatch_call(frame, arg)

如果偵錯程式應該在此函式呼叫時停止，則呼叫 user_call() 方法（應在子類中重寫）。如果設定了 quitting 標誌（可以從 user_call() 設定），則引發 BdbQuit 異常。返回對 trace_dispatch() 方法的引用，以便在該範圍內進行進一步跟蹤。

dispatch_return(frame, arg)

如果偵錯程式應該在此函式返回時停止，則呼叫 user_return() 方法（應在子類中重寫）。如果設定了 quitting 標誌（可以從 user_return() 設定），則引發 BdbQuit 異常。返回對 trace_dispatch() 方法的引用，以便在該範圍內進行進一步跟蹤。

dispatch_exception(frame, arg)

如果偵錯程式應該在此異常處停止，則呼叫 user_exception() 方法（應在子類中重寫）。如果設定了 quitting 標誌（可以從 user_exception() 設定），則引發 BdbQuit 異常。返回對 trace_dispatch() 方法的引用，以便在該範圍內進行進一步跟蹤。

通常，派生類不會重寫以下方法，但如果他們想重新定義停止和斷點的定義，則可以重寫。

is_skipped_line(module_name)

如果 *module_name* 與任何跳過模式匹配，則返回 True。

stop_here(frame)

如果 *frame* 低於堆疊中的起始幀，則返回 True。

break_here(frame)

如果此行存在有效的斷點，則返回 True。

檢查是否存在行或函式斷點並且是否有效。根據 effective() 中的資訊刪除臨時斷點。

break_anywhere(frame)

如果 *frame* 的檔名存在任何斷點，則返回 True。

派生類應該重寫這些方法以獲得對偵錯程式操作的控制權。

user_call(frame, argument_list)

如果斷點可能會在被呼叫的函式內部停止，則從 dispatch_call() 中呼叫。

argument_list 不再使用，並且將始終為 None。保留此引數是為了向後相容。

user_line(frame)

當 stop_here() 或 break_here() 返回 True 時，從 dispatch_line() 中呼叫。

user_return(frame, return_value)

當 stop_here() 返回 True 時，從 dispatch_return() 中呼叫。

user_exception(frame, exc_info)

當 stop_here() 返回 True 時，從 dispatch_exception() 中呼叫。

do_clear(arg)

處理如何刪除臨時斷點。

此方法必須由派生類實現。

派生類和客戶端可以呼叫以下方法來影響單步執行狀態。

set_step()

在執行一行程式碼後停止。

set_next(frame)

在給定幀內或下方的下一行程式碼處停止。

set_return(frame)

從給定幀返回時停止。

set_until(frame, lineno=None)

當到達行號大於當前行的行時，或從當前幀返回時停止。

set_trace([frame])

從 frame 開始除錯。如果未指定 frame，則從呼叫者的幀開始除錯。

在 3.13 版本中變更: set_trace() 將立即進入偵錯程式，而不是在下一行要執行的程式碼處進入。

set_continue()

僅在斷點處或完成時停止。如果沒有斷點，則將系統跟蹤函式設定為 None。

set_quit()

將 quitting 屬性設定為 True。這會在下次呼叫 dispatch_*() 方法之一時引發 BdbQuit。

派生類和客戶端可以呼叫以下方法來操作斷點。如果出現問題，這些方法會返回包含錯誤訊息的字串，否則返回 None。

set_break(filename, lineno, temporary=False, cond=None, funcname=None)

設定新的斷點。如果作為引數傳遞的 filename 不存在 lineno 行，則返回錯誤訊息。 filename 應採用規範形式，如 canonic() 方法中所述。

clear_break(filename, lineno)

刪除 filename 和 lineno 中的斷點。如果沒有設定斷點，則返回錯誤訊息。

clear_bpbynumber(arg)

刪除在 Breakpoint.bpbynumber 中索引為 arg 的斷點。如果 arg 不是數字或超出範圍，則返回錯誤訊息。

clear_all_file_breaks(filename)

刪除 filename 中的所有斷點。如果沒有設定斷點，則返回錯誤訊息。

clear_all_breaks()

刪除所有現有斷點。如果沒有設定斷點，則返回錯誤訊息。

get_bpbynumber(arg)

返回由給定數字指定的斷點。如果 arg 是字串，它將被轉換為數字。如果 arg 是非數字字串，如果給定的斷點從未存在或已被刪除，則會引發 ValueError。

3.2 版本新增。

get_break(filename, lineno)

如果 filename 中的 lineno 存在斷點，則返回 True。

get_breaks(filename, lineno)

返回 filename 中 lineno 的所有斷點，如果沒有設定，則返回空列表。

get_file_breaks(filename)

返回 filename 中的所有斷點，如果沒有設定，則返回空列表。

get_all_breaks()

返回已設定的所有斷點。

派生類和客戶端可以呼叫以下方法來獲取表示堆疊跟蹤的資料結構。

get_stack(f, t)

返回堆疊跟蹤中的 (幀, 行號) 元組列表和一個大小。

最近呼叫的幀在列表的末尾。大小是偵錯程式被呼叫時所在幀下方的幀數。

format_stack_entry(frame_lineno, lprefix=': ')

返回一個包含堆疊條目資訊的字串，該條目是一個 (frame, lineno) 元組。返回的字串包含：

  • 包含幀的規範檔案名。

  • 函式名或 "<lambda>"。

  • 輸入引數。

  • 返回值。

  • 程式碼行（如果存在）。

以下兩個方法可以被客戶端呼叫，以使用偵錯程式來除錯給定的字串形式的 語句。

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

除錯透過 exec() 函式執行的語句。globals 預設為 __main__.__dict__，locals 預設為 globals。

runeval(expr, globals=None, locals=None)

除錯透過 eval() 函式執行的表示式。globals 和 locals 的含義與 run() 中相同。

runctx(cmd, globals, locals)

為了向後相容。呼叫 run() 方法。

runcall(func, /, *args, **kwds)

除錯單個函式呼叫，並返回其結果。

最後，該模組定義了以下函式：

bdb.checkfuncname(b, frame)

如果應該在此處中斷，則返回 True，具體取決於 Breakpoint b 的設定方式。

如果它是透過行號設定的，則它會檢查 b.line 是否與 frame 中的相同。如果斷點是透過 函式 名 設定的，則我們必須檢查我們是否在正確的 frame（正確的函式）中，以及我們是否在其第一個可執行行上。

bdb.effective(file, line, frame)

返回 (活動斷點, 刪除臨時標記) 或 (None, None) 作為要操作的斷點。

活動斷點 是 bplist 中 ( file，line )（必須存在）的第一個條目，該條目是 enabled，對於該條目，checkfuncname() 為真，並且既沒有假的 condition，也沒有正的 ignore 計數。當 cond 無法計算時，標誌（意味著應刪除臨時斷點）才為 False（在這種情況下，ignore 計數將被忽略）。

如果不存在這樣的條目，則返回 (None, None)。

bdb.set_trace()

從呼叫者的框架開始使用 Bdb 例項進行除錯。