<type>documentation</type>
<domain>scripting</domain>
<id>debugger</id>
<title>API Reference - Debugger</title>
<product>per+</product>


The debugger API consists of two parts:

**(1)** ``CAPIDebugger`` is the debug manager, which is used to manage multiple debug
processes.

**(2)** ``CAPIDebugRunState`` is used to start, control, inspect, and terminate a
single debug process.


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 <ref:proj/remote-hosts>`__.

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
<ref:proj/launch-configs>`__ 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 <ref:debug/named-entry-points>`__ 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:

* If ``out`` is True then step out
* If ``over`` is ``CAPIDebugRunState.kStepOverInstruction`` step over the
  current instruction
* If ``over`` is ``CAPIDebugRunState.kStepOverLine`` step over the current
  physical line
* If ``over`` is ``CAPIDebugRunState.kStepOverStatement`` step over the
  current statement
* If ``over`` is ``CAPIDebugRunState.kStepOverBlock`` step over or finish
  the current block
* If ``over`` is a ``(start_line, end_line)`` tuple, step until debugging
  leaves that range of lines (0=first line)
* In all other cases, step in

**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 <ref:proj/remote-hosts>`__.

``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 <ref:proj/remote-hosts>`__.

``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 <ref:proj/remote-hosts>`__.

``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


Deprecated Methods
==================

**CAPIDebugRunState.GetStackFrame()**

Get the currently selected thread ID (None if no thread is paused or stopped at a
breakpoint or exception) and stack frame (0=outermost frame, or ``None`` if the thread
is still running).

When there are chained exception stack, the index is in the currently selected stack.
Use GetStackIndex() to get the stack number as well.

Deprecated in Wing 7.0.  Use ``GetStackIndex`` instead.

