Module implementing a debugger / call tracer based on sys.monitoring.
Since Python 3.12 there is a new interface to implement debugger / call tracer with much better performance compared to sys.set_trace.
If raising ImportError, the old debugger will be used.
| Code |
| Frame |
| _recursion_limit |
| events |
| monitoring |
| DebugBase | Class implementing base class of the debugger. |
| printerr | Module function used for debugging the debug client. |
| setRecursionLimit | Module function to set the recursion limit. |
Class implementing base class of the debugger.
Provides methods for the 'owning' client to call to step etc.
| code_has_breakpoints |
| filename_cache |
| files_to_skip |
| lib |
| paths_to_skip |
| pollTimerEnabled |
| profile_active |
| step_over_frames |
| step_single_threads |
| timer_thread |
| trace_active |
| None |
| DebugBase | Constructor of DebugBase. |
| __disassemble | Private method to generate a disassembly of the given code object. |
| __event_poll_timer | Private method to check every second for new commands. |
| __extractSystemExitMessage | Private method to get the SystemExit code and message. |
| __extract_stack | Private member to return a list of stack frames. |
| __fix_frame_filename | Private method used to fixup the filename for a given frame. |
| __monitor_exception | Private method to handle exception events. |
| __monitor_line | Private method to handle line events. |
| __monitor_py_return | Private method to handle return events. |
| __monitor_py_start | Private method to handle event when entering the next Python frame. |
| __profile_c_return | Private method to profile the return from C-code frame. |
| __profile_call | Private method to profile the next function / method call. |
| __profile_py_return | Private method to profile the return from current Python frame. |
| __sendCallTrace | Private method to send a call/return trace. |
| __set_stepinstr | Private method to stop before the next instruction. |
| __skip_file | Private method to filter out debugger files. |
| _has_breakpoint | Protected method to check if there is a breakpoint inside the code object. |
| bootstrap | Public method to bootstrap a thread. |
| getFrame | Public method to return the frame "frmnr" down the stack. |
| getFrameLocals | Public method to return the locals dictionary of the current frame or a frame below. |
| getStack | Public method to get the stack. |
| go | Public method to resume the thread. |
| move_instruction_pointer | Public method to move the instruction pointer to another line. |
| reset_debug_information | Public method to reset the cached debug information. |
| reset_profile | Public method to disable call trace profiling. |
| reset_trace | Public method to disable debugging. |
| run | Public method to start a given command under debugger control. |
| setRecursionDepth | Public method to determine the current recursion depth. |
| set_profile | Public method to enable call trace profiling. |
| set_quit | Public method to quit debugging. |
| set_trace | Public method to enable debugging. |
| set_until | Public method to stop when the line with the lineno greater than the current one is reached or when returning from current frame. |
| step | Public method to perform a step operation in this thread. |
| stepOut | Public method to perform a step out of the current call. |
| storeFrameLocals | Public method to store the locals into the frame, so an access to frame.f_locals returns the last data. |
| tracePythonLibs | Public method to update the settings to trace into Python libraries. |
| user_exception | Public method to report an exception to the debug server and wait for user. |
| user_line | Public method to handle the user interaction of a particular line. |
| None |
Constructor of DebugBase.
Private method to generate a disassembly of the given code object.
Private method to check every second for new commands.
Private method to get the SystemExit code and message.
Private member to return a list of stack frames.
Private method used to fixup the filename for a given frame.
The logic employed here is that if a module was loaded from a .pyc file, then the correct .py to operate with should be in the same path as the .pyc. The reason this logic is needed is that when a .pyc file is generated, the filename embedded and thus what is readable in the code object of the frame object is the fully qualified filepath when the pyc is generated. If files are moved from machine to machine this can break debugging as the .pyc will refer to the .py on the original machine. Another case might be sharing code over a network... This logic deals with that.
Private method to handle exception events.
Every exception is handled here. It's not possible to disable it.
Because user_exception() requires a triple like returned by sys.exc_info() but sys.exc_info() is returning None at this point, an artificial exc_info is created here.
Private method to handle line events.
When stepping through the code, for each line we have to wait for the user. Otherwise we check, if current line has a breakpoint. If so, wait for user else just continue because in one of those code lines should be a breakpoint. Watchpoints are handled the same as breakpoints.
Private method to handle return events.
When leaving a Python frame this event is triggered if PY_RETURN is enabled. This is used to activate line events when leaving a frame with the command step over, because the step over command want to stop at the current frame.
Private method to handle event when entering the next Python frame.
Check if this code object could be of interest, e.g. is there a breakpoint or are we stepped in. In those cases enable line events to get __monitor_line called, otherwise just return monitoring.DISABLE and we don't visit this code object till reenabled by calling monitoring.restart_events().
Private method to profile the return from C-code frame. # NOTE: Maybe unused...
Private method to profile the next function / method call.
Private method to profile the return from current Python frame.
Private method to send a call/return trace.
Private method to stop before the next instruction.
Private method to filter out debugger files.
Tracing is turned off for files that are part of the debugger that are called from the application being debugged.
Protected method to check if there is a breakpoint inside the code object.
Public method to bootstrap a thread.
It wraps the call to the user function to enable tracing before hand.
Public method to return the frame "frmnr" down the stack.
Public method to return the locals dictionary of the current frame or a frame below.
Public method to get the stack.
Public method to resume the thread.
It resumes the thread stopping only at breakpoints or exceptions.
Public method to move the instruction pointer to another line.
Public method to reset the cached debug information.
This is needed to enable newly set breakpoints or watches, because the debugger might stepped already through some of those code objects and disabled further processing for speed optimization.
Public method to disable call trace profiling.
Public method to disable debugging.
Public method to start a given command under debugger control.
Public method to determine the current recursion depth.
Public method to enable call trace profiling.
Public method to quit debugging.
Disables the trace functions and resets all frame pointer.
Public method to enable debugging.
Public method to stop when the line with the lineno greater than the current one is reached or when returning from current frame.
The name "until" is borrowed from gdb.
Public method to perform a step operation in this thread.
Public method to perform a step out of the current call.
Public method to store the locals into the frame, so an access to frame.f_locals returns the last data.
Public method to update the settings to trace into Python libraries.
Public method to report an exception to the debug server and wait for user.
Public method to handle the user interaction of a particular line.
Module function used for debugging the debug client.
Module function to set the recursion limit.