<type>documentation</type>
<domain>debug</domain>
<id>shell-debugging</id>
<title>Debugging Code in the Python Shell</title>
<date>$Date: 2006-12-28 17:21:05 -0500 (Thu, 28 Dec 2006) $</date>
<version>$Revision: 14455 $</version>
<product>all</product>
<product-version>6+</product-version>

Code executed in the ``Python Shell`` can be run with or without debug.  This is
controlled by clicking on the bug icon in the upper right of the tool, or using 
``Enable Debugging`` in the ``Options`` menu.

When debugging is enabled, a breakpoint margin appears at the left of the ``Python Shell``
tool, and breakpoints can be set, as in editors. This works for code previously typed,
dragged, or pasted into the shell. Breakpoints set in editors are also reached, if
that code is executed. Wing copies breakpoints from a source file and stops
in the ``Python Shell`` itself when ``Evaluate Selection`` is used on a short enough range of
code. However, when using `active ranges <ref:debug/shell-active-range>`__, or when evaluating a long
selection or a whole file, Wing instead stops at breakpoints set within the code editor, since
in those cases the code is not visible in the shell.

Note that the debugger only appears active when code is actually running, and not when
waiting at the ``Python Shell`` prompt.

Whenever code is being debugged from a shell prompt, ``Stop Debugging`` and ``Start/Continue`` 
in the ``Debug`` menu, and their keyboard and toolbar equivalents, will return to the
prompt in the shell.  Both will continue executing code to complete the invocation from 
the prompt but ``Stop Debugging`` will do so with debug temporarily disabled.  The fact
that code is not preemptively interrupted is a limitation stemming
from the way Python is implemented.  In cases where this is a problem, the
``Python Shell`` can be restarted instead.

~~~if WINGPRO:
**Recursive Debugging**

In Wing Pro, to interact recursively with code debugged from the ``Python Shell``, use the
``Debug Console`` or turn on ``Enable Recursive Prompt`` in the ``Options`` menu.
The latter presents a new prompt in the ``Python Shell`` whenever the debugger
is paused or at a breakpoint, even if that shell is already in the process of 
executing code.
~~~

**Debugging Threaded Code**

Threads are treated differently in the ``Python Shell`` and Wing Pro's ``Debug Console`` 
depending on whether or not debug is enabled and/or whether the shell is at the prompt, as
follows:

In the ``Python Shell``, when debugging is disabled, threads are run continuously
in the background without debug and whether or not the shell is at a prompt.  When
debugging is enabled in the ``Python Shell`` it will also debug threads.  However,
it will allow threads to run only while code is being executed from the shell and the 
``Python Shell`` is not at the prompt.  This matches the behavior of the debugger
when it is running stand-alone files, where it halts all threads if any thread is halted.
When the ``Python Shell`` is debugged, Wing treats execution of code from the shell
prompt as continuing the debugger until the prompt is reached again.  Thus it also allows
other threads to run during this time.

~~~if WINGPRO:
In the ``Debug Console``, when debugging is disabled in its ``Options`` menu, threads are 
debugged but are halted whenever the main thread is halted in the debugger.  Threads 
are not run even while executing code from the prompt in the ``Debug Console`` so that 
data in all threads can be inspected without any unexpected change in runtime state 
caused by running of a thread.  Threads will only continue running when the main debug
program is continued.  This is true whether or not the debug program was started from
a file, or from within the ``Python Shell``.  As in the ``Python Shell``, when debugging 
is enabled in the ``Debug Console`` child threads will also be allowed to run whenever 
code is being executed recursively and the ``Debug Console`` is not at the prompt.  Threads
are still halted whenever the ``Debug Console`` is at the prompt
~~~

These subtle but necessary differences in threading behavior may affect how threaded code
performs within the ``Python Shell`` and Wing Pro's ``Debug Console``. Currently there are
no options for selecting other behaviors, such as always letting threads run even when at
the prompt, or never letting threads run even when executing code from the prompt. If you
run into a situation where one of these options is needed, please send details of your use
case to support@wingware.com.
