Debugger API

Index of All Documentation » Wing Pro Reference Manual » Advanced Debugging Topics » Debugging Externally Launched Code »

A simple API can be used to control debugging more closely, once you have imported the first time. 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, particularly in those that alter the thread state or discard and recreate the Python instance across invocations.

To use the API, you must first configure and import as described in Debugging Externally Launched Code (or Debugging Remotely Launched Code if you are debugging code running on another machine).

High-Level API

The wingdbstub.Ensure(require_connection=1, require_debugger=1) function may be used to ensure the debugger is running and connected to the IDE. If require_connection is true, ValueError will be raised if a connection to the IDE cannot be made. If require_debugger is true, ValueError will be raised if the debugger binaries cannot be found or the debugger cannot be started.

Low-Level API

After importing wingdbstub, the following calls may be made on wingdbstub.debugger to control the debugger:

  • StopDebug() - Stop debugging completely and disconnect from Wing. The debug program continues executing in non-debug mode and must be restarted to resume debugging.
  • StartDebug(stophere=0, connect=1) -- Start debugging, optionally connecting back to the IDE and/or stopping immediately afterwards.
  • 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 or if autoquit=0 in the preceding StartDebug() API call (if any). This makes sure the debug connection to the IDE is closed cleanly.
  • SetDebugThreadIdents(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() or the PyThreadState's thread_id) to one of the following values: 0 to ignore the thread (do not debug it and let it keep running), 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.
  • SuspendDebug() - This will leave the connection to the debug client intact but disables the debugger so that connection overhead is avoided during subsequent execution. This should be used only to exempt a particular section of code from debug overhead. In most cases StopDebug is preferable.
  • ResumeDebug() - This will resume debugging using an existing connection to Wing.

Here is a simple usage example:

import wingdbstub
a = 1 # This line is debugged
x = 1 # This is executed without debugging
y = 2 # This line is debugged

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.