Home » Support » Index of All Documentation » Wing IDE Reference Manual » Advanced Debugging Topics » Debugging Externally Launched Code »

11.0.2. Debugger API

A simple API can be used to control debugging more closely, once you have imported wingdbstub.py the first time, as was described in section Importing the Debugger.

This is useful in cases where you want to be able to start and stop debugging on the fly several times during a debug run, for example to avoid debug overhead except within a small sub-section of your code. It can also be useful in embedded scripting environments.

To use the API, take the following steps: (1) Configure and import wingdbstub.py as described in section Importing the Debugger. (2) Subsequently, use the instance variable wingdbstub.debugger to make any of the following calls:

  • StartDebug(stophere=0, autoquit=1, connect=1) -- Start debugging, optionally connecting back to the IDE and/or stopping immediately afterwards. Set autoquit=0 to avoid automatically terminating debug when program exit is detected (this is the same as setting kEmbedded in wingdbstub.py).
  • StopDebug() - Stop debugging completely and disconnect from Wing IDE. The debug program continues executing in non-debug mode and must be restarted to resume debugging.
  • SuspendDebug() - This will leave the connection to the debug client intact but disables the debugger so that connection overhead is avoided during subsequent execution.
  • ResumeDebug() - This will resume debugging using an existing connection to Wing.
  • Break() -- This pauses the free-running debug program on the current line, as if at a breakpoint.
  • ProgramQuit() - This must be called before the debug program is exited if kEmbedded was set to 1 in wingdbstub.py or if autoquit=0 in the preceding StartDebug() API call (if any). This makes sure the debug connection to the IDE is closed cleanly.
  • SetDebugThreads(threads={}, default_policy=1) - This can be used in multi-threaded code to tell Wing's debugger which threads to debug. Pass in a dictionary that maps from thread id (as obtained from thread.get_ident()) to one of the following values: 0 to ignore the thread (do not debug it), or 1 to debug the thread and immediately stop it if any thread stops. The default_policy sets the action to take when a thread is not found in the thread map.

Here is a simple usage example:

import wingdbstub
a = 1 # This line is debugged
wingdbstub.debugger.SuspendDebug()
x = 1 # This is executed without debugging
wingdbstub.debugger.ResumeDebug()
y = 2 # This line is debugged again

SuspendDebug() and ResumeDebug() can be called as many times as desired, and nested calls will be handled so that debugging is only resumed when the number of ResumeDebug() calls matches the number of SuspendDebug() calls.

« 11.0.1. Debug Server ConfigurationTable of Contents11.1. Remote Debugging »