<type>documentation</type>
<domain>debug</domain>
<id>python-shell</id>
<title>Integrated Python Shell</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

The integrated `Python Shell <script:show-panel-python-shell>`__ is used to execute or
debug commands and expressions interactively, in a way that is tightly integrated with
Wing's editor, code inspection, and debugger features.

The ``Python Shell``'s auto-completer uses introspection of the runtime environment 
as a powerful way to find and inspect functionality and craft new code interactively.
~~~if WING101:
In Wing 101, the auto-completer is disabled by default but can be enabled with
the `Editor > Auto-completion > Auto-show Completer 
<script:show_preferences_gui#prefname="edit.autocomplete-autoshow-option">`__ 
preference.
~~~
~~~if not WING101:
The `Source Assistant <ref:edit/source-assistant>`__ in Wing Pro and Wing Personal
displays documentation, call signature, and other information about symbols as
you work in the ``Python Shell``
~~~

Goto-definition will also work in the ``Python Shell``, using a combination of runtime and
static analysis to find the definition of the symbol or its type.

**Evaluating Code from the Editor**

There are several ways to evaluate code from an editor within the ``Python Shell``:

  **Copy and Paste** and **Drag and Drop** adjust leading indentation and execute the code.
  
  **Evaluate File in Python Shell** in the ``Source`` menu restarts the ``Python 
  Shell`` and then evaluates the top level of the current file.  Restarting
  can be disabled by unchecking ``Auto-restart When Evaluate File`` in the ``Options`` 
  menu at the top right of the tool.  This operation sets the value of ``sys.argv``
  to match the value that would be used if the file were debugged.  If a launch 
  configuration has been selected in the Python Shell's ``Options`` menu then
  its run arguments are used instead.
  
  **Evaluate Selection in Python Shell** in the ``Source`` menu evaluates the current 
  selection in the shell.  This is also available in the editor's right-click context
  menu.
  
~~~if WINGPRO:
  **Set an Active Range** from the editor into the ``Python Shell`` so it can be executed 
  or debugged repeatedly during editing.  See `Active Ranges in the Python Shell 
  <ref:debug/shell-active-range>`__ for details.
~~~
  
  **The Options menu** in the ``Python Shell`` tool also contains items for evaluating the
  current file or selection

To clear the shell's state at any time, use ``Restart Shell`` in the ``Options`` menu.

**Debugging**

Code entered into the ``Python Shell`` may be executed with or without debug. When
debugging is enabled, execution will reach breakpoints, allow stepping through code, and
support inspection of runtime state. See `Debugging Code in the Python Shell
<ref:debug/shell-debugging>`__ for details.

~~~if WINGPRO:
In Wing Pro, the `Debug Console <ref:debug/debug-console>`__ can be 
used to interact in a similar way with the current frame of a debug process.
~~~

**Command History**

The ``Up`` and ``Down`` arrow keys traverse the history of the code you have entered
and the ``Return`` key executes the code if it is complete, or prompts for another
line if it is not.  If ``Filter History by Entered Prefix`` in the ``Options``menu 
is checked then any text typed before pressing ``Up`` will be used to filter the
history items that are traversed.

Code recalled from history can be edited within the ``Python Shell``. Use ``Ctrl-Up`` and
``Ctrl-Down`` to move the caret up and down and ``Ctrl-Return`` to insert a new line at
the caret position.

To save the contents of the shell, use ``Save a Copy`` in the ``Options`` menu or the
tool's right-click context menu. The context menu also provides items for copying
text from the shell, with or without prompts.


