bdb --- Khung gỡ lỗi

Source code: Lib/bdb.py

---

Mô-đun bdb xử lý các chức năng gỡ lỗi cơ bản, như đặt điểm dừng hoặc quản lý việc thực thi thông qua trình gỡ lỗi.

Ngoại lệ sau đây được xác định:

exception bdb.BdbQuit

Ngoại lệ do lớp Bdb đưa ra để thoát khỏi trình gỡ lỗi.

Mô-đun bdb cũng định nghĩa hai lớp:

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

Lớp này triển khai các điểm dừng tạm thời, bỏ qua số lượng, vô hiệu hóa và (bật) lại cũng như các điều kiện.

Điểm dừng được lập chỉ mục theo số thông qua danh sách có tên là bpbynumber và theo cặp (file, line) thông qua bplist. Cái trước trỏ tới một thể hiện duy nhất của lớp Breakpoint. Cái sau trỏ đến danh sách các trường hợp như vậy vì có thể có nhiều điểm dừng trên mỗi dòng.

Khi tạo điểm ngắt, file name được liên kết với nó phải ở dạng chuẩn. Nếu funcname được xác định, điểm dừng hit sẽ được tính khi dòng đầu tiên của hàm đó được thực thi. Điểm dừng conditional luôn được tính là hit.

Các phiên bản Breakpoint có các phương thức sau:

deleteMe()

Xóa điểm ngắt khỏi danh sách liên kết với một tệp/dòng. Nếu đó là điểm dừng cuối cùng ở vị trí đó, nó cũng sẽ xóa mục nhập của tệp/dòng.

enable()

Đánh dấu điểm dừng là đã bật.

disable()

Đánh dấu điểm dừng là bị vô hiệu hóa.

bpformat()

Trả về một chuỗi có tất cả thông tin về điểm ngắt, được định dạng phù hợp:

• Số điểm dừng.

• Trạng thái tạm thời (xóa hoặc giữ).

• Vị trí tập tin/dòng.

• Tình trạng phá vỡ.

• Số lần bỏ qua.

• Số lần đánh.

Added in version 3.2.

bpprint(out=None)

In đầu ra của bpformat() ra tệp out, hoặc nếu là None, ra đầu ra tiêu chuẩn.

Các phiên bản Breakpoint có các thuộc tính sau:

file

Tên tệp của Breakpoint.

line

Số dòng của Breakpoint trong file.

temporary

True nếu Breakpoint tại (tệp, dòng) là tạm thời.

cond

Điều kiện để đánh giá Breakpoint tại (tệp, dòng).

funcname

Tên hàm xác định xem Breakpoint có được nhấn khi vào hàm hay không.

enabled

True nếu Breakpoint được bật.

bpbynumber

Chỉ mục số cho một phiên bản duy nhất của Breakpoint.

bplist

Từ điển các phiên bản Breakpoint được lập chỉ mục bởi các bộ dữ liệu (file, line).

ignore

Số lần bỏ qua Breakpoint.

hits

Đếm số lần Breakpoint bị tấn công.

class bdb.Bdb(skip=None, backend='settrace')

Lớp Bdb hoạt động như một lớp cơ sở của trình gỡ lỗi Python chung.

Lớp này quản lý các chi tiết của cơ sở theo dõi; một lớp dẫn xuất sẽ triển khai tương tác của người dùng. Lớp trình gỡ lỗi tiêu chuẩn (pdb.Pdb) là một ví dụ.

Đối số skip, nếu được đưa ra, phải là một đối số có thể lặp lại của các mẫu tên mô-đun kiểu toàn cầu. Trình gỡ lỗi sẽ không bước vào các khung bắt nguồn từ mô-đun khớp với một trong các mẫu này. Liệu một khung có được coi là có nguồn gốc từ một mô-đun nhất định hay không được xác định bởi __name__ trong toàn cục khung.

Đối số backend chỉ định phần phụ trợ sẽ sử dụng cho Bdb. Nó có thể là 'settrace' hoặc 'monitoring'. 'settrace' sử dụng sys.settrace() có khả năng tương thích ngược tốt nhất. Phần phụ trợ 'monitoring' sử dụng sys.monitoring mới được giới thiệu trong Python 3.12, có thể hiệu quả hơn nhiều vì nó có thể vô hiệu hóa các sự kiện không sử dụng. Chúng tôi đang cố gắng giữ các giao diện chính xác cho cả hai chương trình phụ trợ, nhưng có một số khác biệt. Các nhà phát triển trình gỡ lỗi được khuyến khích sử dụng chương trình phụ trợ 'monitoring' để đạt được hiệu suất tốt hơn.

Thay đổi trong phiên bản 3.1: Đã thêm tham số skip.

Thay đổi trong phiên bản 3.14: Đã thêm tham số backend.

Các phương thức sau của Bdb thường không cần phải ghi đè.

canonic(filename)

Trả về dạng chuẩn của filename.

Đối với tên tệp thực, dạng chuẩn phụ thuộc vào hệ điều hành, case-normalized absolute path. Một filename có dấu ngoặc nhọn, chẳng hạn như "<stdin>" được tạo ở chế độ tương tác, sẽ được trả về không thay đổi.

start_trace(self)

Bắt đầu truy tìm. Đối với phần phụ trợ 'settrace', phương thức này tương đương với sys.settrace(self.trace_dispatch)

Added in version 3.14.

stop_trace(self)

Dừng truy tìm. Đối với phần phụ trợ 'settrace', phương thức này tương đương với sys.settrace(None)

Added in version 3.14.

reset()

Đặt các thuộc tính botframe, stopframe, returnframe và quitting với các giá trị sẵn sàng để bắt đầu gỡ lỗi.

trace_dispatch(frame, event, arg)

Chức năng này được cài đặt làm chức năng theo dõi các khung đã được gỡ lỗi. Giá trị trả về của nó là hàm theo dõi mới (trong hầu hết các trường hợp, tức là chính nó).

Việc triển khai mặc định quyết định cách gửi một khung, tùy thuộc vào loại sự kiện (được truyền dưới dạng chuỗi) sắp được thực thi. event có thể là một trong những điều sau đây:

• "line": Một dòng mã mới sắp được thực thi.

• "call": Một hàm sắp được gọi hoặc một khối mã khác được nhập vào.

• "return": Một hàm hoặc khối mã khác sắp quay trở lại.

• "exception": Đã xảy ra ngoại lệ.

• "c_call": Hàm A sắp được gọi.

• "c_return": Hàm AC đã quay trở lại.

• "c_exception": Hàm C đã đưa ra một ngoại lệ.

Đối với các sự kiện Python, các hàm chuyên biệt (xem bên dưới) sẽ được gọi. Đối với các sự kiện C, không có hành động nào được thực hiện.

Thông số arg phụ thuộc vào sự kiện trước đó.

Xem tài liệu về sys.settrace() để biết thêm thông tin về chức năng theo dõi. Để biết thêm thông tin về các đối tượng mã và khung, hãy tham khảo Hệ thống phân cấp loại tiêu chuẩn.

dispatch_line(frame)

Nếu trình gỡ lỗi dừng ở dòng hiện tại, hãy gọi phương thức user_line() (cần được ghi đè trong các lớp con). Đưa ra ngoại lệ BdbQuit nếu cờ quitting được đặt (có thể được đặt từ user_line()). Trả về một tham chiếu đến phương thức trace_dispatch() để theo dõi thêm trong phạm vi đó.

dispatch_call(frame, arg)

Nếu trình gỡ lỗi dừng lệnh gọi hàm này, hãy gọi phương thức user_call() (cần được ghi đè trong các lớp con). Đưa ra ngoại lệ BdbQuit nếu cờ quitting được đặt (có thể được đặt từ user_call()). Trả về một tham chiếu đến phương thức trace_dispatch() để theo dõi thêm trong phạm vi đó.

dispatch_return(frame, arg)

Nếu trình gỡ lỗi dừng khi trả về hàm này, hãy gọi phương thức user_return() (cần được ghi đè trong các lớp con). Đưa ra ngoại lệ BdbQuit nếu cờ quitting được đặt (có thể được đặt từ user_return()). Trả về một tham chiếu đến phương thức trace_dispatch() để theo dõi thêm trong phạm vi đó.

dispatch_exception(frame, arg)

Nếu trình gỡ lỗi dừng ở ngoại lệ này, hãy gọi phương thức user_exception() (cần được ghi đè trong các lớp con). Đưa ra ngoại lệ BdbQuit nếu cờ quitting được đặt (có thể được đặt từ user_exception()). Trả về một tham chiếu đến phương thức trace_dispatch() để theo dõi thêm trong phạm vi đó.

Các lớp dẫn xuất thông thường không ghi đè các phương thức sau, nhưng chúng có thể ghi đè nếu chúng muốn xác định lại định nghĩa về điểm dừng và điểm dừng.

is_skipped_module(module_name)

Trả về True nếu module_name khớp với bất kỳ mẫu bỏ qua nào.

stop_here(frame)

Trả về True nếu frame ở dưới khung bắt đầu trong ngăn xếp.

break_here(frame)

Trả về True nếu có điểm ngắt hiệu quả cho dòng này.

Kiểm tra xem điểm ngắt dòng hoặc chức năng có tồn tại và có hiệu lực hay không. Xóa điểm dừng tạm thời dựa trên thông tin từ effective().

break_anywhere(frame)

Trả về True nếu có bất kỳ điểm ngắt nào tồn tại cho tên tệp của frame.

Các lớp dẫn xuất nên ghi đè các phương thức này để giành quyền kiểm soát hoạt động của trình gỡ lỗi.

user_call(frame, argument_list)

Được gọi từ dispatch_call() nếu ngắt có thể dừng bên trong hàm được gọi.

argument_list không được sử dụng nữa và sẽ luôn là None. Đối số được giữ để tương thích ngược.

user_line(frame)

Được gọi từ dispatch_line() khi stop_here() hoặc break_here() trả về True.

user_return(frame, return_value)

Được gọi từ dispatch_return() khi stop_here() trả về True.

user_exception(frame, exc_info)

Được gọi từ dispatch_exception() khi stop_here() trả về True.

do_clear(arg)

Xử lý cách loại bỏ điểm dừng khi nó là điểm dừng tạm thời.

Phương thức này phải được thực hiện bởi các lớp dẫn xuất.

Các lớp dẫn xuất và máy khách có thể gọi các phương thức sau để tác động đến trạng thái bước.

set_step()

Dừng lại sau một dòng mã.

set_next(frame)

Dừng ở dòng tiếp theo trong hoặc bên dưới khung đã cho.

set_return(frame)

Dừng lại khi quay lại từ khung đã cho.

set_until(frame, lineno=None)

Dừng khi đạt đến dòng có lineno lớn hơn dòng hiện tại hoặc khi quay lại từ khung hình hiện tại.

set_trace([frame])

Bắt đầu gỡ lỗi từ frame. Nếu frame không được chỉ định, quá trình gỡ lỗi sẽ bắt đầu từ khung của người gọi.

Thay đổi trong phiên bản 3.13: set_trace() sẽ vào trình gỡ lỗi ngay lập tức, thay vì vào dòng mã tiếp theo sẽ được thực thi.

set_continue()

Chỉ dừng lại ở điểm dừng hoặc khi hoàn thành. Nếu không có điểm dừng, hãy đặt chức năng theo dõi hệ thống thành None.

set_quit()

Đặt thuộc tính quitting thành True. Điều này làm tăng BdbQuit trong lệnh gọi tiếp theo tới một trong các phương thức dispatch_*().

Các lớp dẫn xuất và máy khách có thể gọi các phương thức sau để thao tác các điểm dừng. Các phương thức này trả về một chuỗi chứa thông báo lỗi nếu có sự cố hoặc None nếu tất cả đều ổn.

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

Đặt điểm dừng mới. Nếu dòng lineno không tồn tại cho filename được chuyển làm đối số, hãy trả về thông báo lỗi. filename phải ở dạng chuẩn, như được mô tả trong phương pháp canonic().

clear_break(filename, lineno)

Xóa các điểm ngắt trong filename và lineno. Nếu không được đặt, hãy trả lại thông báo lỗi.

clear_bpbynumber(arg)

Xóa điểm dừng có chỉ mục arg trong Breakpoint.bpbynumber. Nếu arg không phải là số hoặc nằm ngoài phạm vi, hãy trả về thông báo lỗi.

clear_all_file_breaks(filename)

Xóa tất cả các điểm dừng trong filename. Nếu không được đặt, hãy trả lại thông báo lỗi.

clear_all_breaks()

Xóa tất cả các điểm dừng hiện có. Nếu không được đặt, hãy trả lại thông báo lỗi.

get_bpbynumber(arg)

Trả về một điểm dừng được chỉ định bởi số đã cho. Nếu arg là một chuỗi thì nó sẽ được chuyển thành số. Nếu arg là một chuỗi không phải là số, nếu điểm ngắt đã cho chưa bao giờ tồn tại hoặc đã bị xóa thì ValueError sẽ được nâng lên.

Added in version 3.2.

get_break(filename, lineno)

Trả về True nếu có điểm dừng cho lineno trong filename.

get_breaks(filename, lineno)

Trả về tất cả các điểm dừng cho lineno trong filename hoặc một danh sách trống nếu không có điểm nào được đặt.

get_file_breaks(filename)

Trả về tất cả các điểm dừng trong filename hoặc một danh sách trống nếu không có điểm nào được đặt.

get_all_breaks()

Trả về tất cả các điểm dừng được đặt.

Các lớp phái sinh và máy khách có thể gọi các phương thức sau để vô hiệu hóa và khởi động lại các sự kiện nhằm đạt được hiệu suất tốt hơn. Các phương pháp này chỉ hoạt động khi sử dụng phụ trợ 'monitoring'.

disable_current_event()

Tắt sự kiện hiện tại cho đến lần gọi restart_events() tiếp theo. Điều này hữu ích khi trình gỡ lỗi không quan tâm đến dòng hiện tại.

Added in version 3.14.

restart_events()

Khởi động lại tất cả các sự kiện bị vô hiệu hóa. Hàm này được gọi tự động trong các phương thức dispatch_* sau khi các phương thức user_* được gọi. Nếu các phương thức dispatch_* không bị ghi đè, các sự kiện bị tắt sẽ được khởi động lại sau mỗi lần tương tác của người dùng.

Added in version 3.14.

Các lớp phái sinh và máy khách có thể gọi các phương thức sau để có được cấu trúc dữ liệu biểu thị dấu vết ngăn xếp.

get_stack(f, t)

Trả về danh sách các bộ dữ liệu (frame, lineno) trong dấu vết ngăn xếp và kích thước.

Khung được gọi gần đây nhất nằm cuối cùng trong danh sách. Kích thước là số lượng khung hình bên dưới khung nơi trình gỡ lỗi được gọi.

format_stack_entry(frame_lineno, lprefix=': ')

Trả về một chuỗi có thông tin về mục nhập ngăn xếp, đó là một bộ dữ liệu (frame, lineno). Chuỗi trả về chứa:

• Tên tệp chuẩn chứa khung.

• Tên hàm hoặc "<lambda>".

• Các đối số đầu vào.

• Giá trị trả về.

• Dòng mã (nếu nó tồn tại).

Hai phương thức sau đây có thể được máy khách gọi để sử dụng trình gỡ lỗi nhằm gỡ lỗi statement, được cung cấp dưới dạng chuỗi.

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

Gỡ lỗi câu lệnh được thực thi thông qua hàm exec(). globals mặc định là __main__.__dict__, locals mặc định là globals.

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

Gỡ lỗi biểu thức được thực thi thông qua hàm eval(). globals và locals có cùng ý nghĩa như trong run().

runctx(cmd, globals, locals)

Để tương thích ngược. Gọi phương thức run().

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

Gỡ lỗi một lệnh gọi hàm duy nhất và trả về kết quả của nó.

Cuối cùng, mô-đun xác định các chức năng sau:

bdb.checkfuncname(b, frame)

Trả về True nếu chúng ta phá vỡ ở đây, tùy thuộc vào cách thiết lập Breakpoint b.

Nếu nó được đặt thông qua số dòng, nó sẽ kiểm tra xem b.line có giống với frame hay không. Nếu điểm dừng được đặt thông qua function name, chúng ta phải kiểm tra xem chúng ta có ở đúng frame (chức năng bên phải) không và liệu chúng ta có đang ở trên dòng thực thi đầu tiên của nó hay không.

bdb.effective(file, line, frame)

Trả về (active breakpoint, delete temporary flag) hoặc (None, None) làm điểm dừng để hành động.

active breakpoint là mục đầu tiên trong bplist cho (file, line) (phải tồn tại) là enabled, trong đó checkfuncname() là đúng và không có số condition sai cũng như số ignore dương. flag, nghĩa là điểm dừng tạm thời sẽ bị xóa, chỉ là False khi không thể đánh giá cond (trong trường hợp đó, số lượng ignore bị bỏ qua).

Nếu không có mục nào như vậy tồn tại thì (None, None) sẽ được trả về.

bdb.set_trace()

Bắt đầu gỡ lỗi với phiên bản Bdb từ khung của người gọi.