Wing Python IDE

Class CAPIDebugger

API for the debugger as a whole. This class should not be instantiated directly. Use wingapi.gApplication.GetDebugger() instead.

Signals

A callback can be connected to the following signals using Connect(signal, cb):

new-runstate: A new runstate has been created. Calls cb(runstate:CAPIDebugRunState).

current-runstate-changed: A new runstate has been selected as the current runstate. Calls cb(runstate:CAPIDebugRunState).

Use Disconnect(signal_id) to preemptively disconnect a signal handler, where signal_id is the signal ID previously returned from Connect.

CAPIDebugger.GetRunStates()

Get the list of all CAPIDebugRunState objects that currently exist in the debugger.

CAPIDebugger.GetCurrentRunState()

Get the currently active CAPIDebugRunState.

CAPIDebugger.SetCurrentRunState(rs)

Set the currently active CAPIDebugRunState.

Class CAPIDebugRunState

API to access an individual debug process. This class should not be instantiated directly. Use the methods on CAPIDebugger instead.

Each run state is associated with a single debug process. It is created before any debug process is started, takes care of starting and controlling individual debug sessions, and outlives individual debug process termination in order to support subsequent inspection or launch of a new debug process.

Signals

A callback can be connected to the following signals using Connect(signal, cb):

debug-started: A debug session has been started. Calls cb().

debug-terminated: The debug session has ended. Calls cb().

exception: The debug process has encountered an exception. Calls cb().

paused: The debug process has paused or reached a breakpoint. Calls cb().

running: The debug process has started running again. Calls cb().

Use Disconnect(signal_id) to preemptively disconnect a signal handler, where signal_id is the signal ID previously returned from Connect.

Starting and Stopping Debug

CAPIDebugRunState.Run(filename, stop_on_first=0, launch_id=None)

Start debug, using the given file as the main entry point.

filename is the full path of the file to debug. For remote files, filename is in the form ssh://hostname/path/to/file.py where hostname is the Identifier of a Remote Host.

Set stop_on_first to stop immediately on the first line of code. Otherwise debugging continues until it reaches a breakpoint, exception, or program termination.

Set launch_id to the internal ID of a Launch Configuration to use for the debug environment, or to None to use the file's default environment configured in Project Properties or File Properties.

CAPIDebugRunState.RunNamedEntryPoint(name, stop_on_first=0)

Run the given Named Entry Point with its configured launch environment.

Set stop_on_first to stop immediately on the first line of code. Otherwise debugging continues until it reaches a breakpoint, exception, or program termination.

CAPIDebugRunState.Kill()

Stop debugging by terminating the debug process. If the debug process was launched by Wing, all its child processes are also terminated.

Flow Control

CAPIDebugRunState.Step(over=1, out=0)

Step in the code, either into, over, or out of the current execution point, as follows:

CAPIDebugRunState.RunToCursor()

Run until the current editor caret location is reached, or to the next breakpoint, exception, or program termination if the caret's location is not reached first.

CAPIDebugRunState.Continue()

Contine running the debug process to the next breakpoint, exception, or termination.

Threads and Stacks

CAPIDebugRunState.GetThreads()

Get a list of (thread_id, name, running) for the active debug process, where thread_id is the thread ID, name is the thread function name, and running is True if the thread is running or False if the thread is paused a breakpoint or exception.

Returns None if no thread in the process is paused at a breakpoint or exception.

The currently selected thread can be determined by calling GetStackFrame.

CAPIDebugRunState.GetStackIndex()

Get (thread_id, stack_index) where thread_id is the currently selected thread id and stack_index is (stack_no, frame_idx) where stack_no is the stack number (0=primary stack) and frame_idx is the frame index (0=outermost frame).

If the thread is still running then thread_id and stack_index will both me None.

Stacks 1+ are PEP 3134 chained exception stacks, in order of the chain.

CAPIDebugRunState.SetStackFrame(thread_id, idx)

Set the currently selected thread ID (None to use current thread) and stack index. The stack index is in the form (stack_no, frame_idx) to allow access to chained exception stacks. Set stack_no to 0 for the primary stack and frame_idx to 0 for the outermost frame.

Returns (thread_id, stack_index) where thread_id is the actual thread ID and stack_index is the stack index that was actually set. If the thread is still running then thread_id and stack_index will both me None.

Compatibility note:

This call changed in Wing 7.0 to support PEP 3134 chained exceptions. However, it still accepts idx set to an integer to indicate a frame in the primary stack. When idx is passed as an integer, the return value's stack index is also an integer.

CAPIDebugRunState.GetStack()

Get the stack for the currently selected debug thread as a list of frames, each of which is a tuple containing (filename, lineno, line_text, scope, local_varnames) where:

filename is the full path of the file, or for remote files a URL in the form ssh://hostname/path/to/file.py where hostname is the Identifier of a Remote Host.

lineno is the line number (0=first line) or a tuple (start, end) to indicate the position of the current statement in template files.

line_text is the text of the line or statement.

scope is the name of the scope for this frame (for example, MyClass.MethodName)

local_varnames is a list of the local variable names for the frame.

Returns None instead if the currently selected thread is not paused, at a breakpoint, or at an exception.

The currently selected thread is changed by calling SetStackFrame.

Breakpoints

CAPIDebugRunState.SetBreak(filename, lineno, temp=0, cond=None, enable=1, ignore=0)

Set a new breakpoint at the given position.

filename is the full path of the file, or for remote files a URL in the form ssh://hostname/path/to/file.py where hostname is the Identifier of a Remote Host.

lineno is the line number at which to set the breakpoint (0=first line)

temp is True to set a temporary breakpoint that will be removed the first time it is reached.

cond is a conditional string that must evaluate to True in the context of the breakpoint's stack frame for the breakpoint to stop, or None to always stop on this breakpoint.

enable can be set to False to disable stopping on the breakpoint.

ignore is set to a value above 0 to ignore hitting the breakpoint that number of times before stopping on it.

If a breakpoint already exists here, it is replaced.

Returns (lineno, err) where lineno is the actual line the breakpoint was placed at and err is either None or an error string.

CAPIDebugRunState.ClearBreak(filename, lineno)

Clear a breakpoint.

filename is the full path of the file, or for remote files a URL in the form ssh://hostname/path/to/file.py where hostname is the Identifier of a Remote Host.

lineno is the breakpoint's line numbert (0=first line)

CAPIDebugRunState.ClearAllBreaks()

Clear all breakpoints.

Utilities

CAPIDebugRunState.GetProcessID()

Get the process ID of the active debug process. Returns None if there is no active process.

CAPIDebugRunState.GetStatus()

Get the status of the debug process. Returns an integer, as follows:

0 -- disconnected (no debug process)
1 -- listening for a connection from an IDE-launched debug process
2 -- connected to a debug process
3 -- the debug process is running
4 -- the debug process is stopped at a breakpoint or paused
5 -- the debug process is stopped on an exception
6 -- listening for a connection from a externally launched debug process