<type>how-to</type>
<domain>install</domain>
<id>quickstart</id>
<title>~~PRODUCT_NAME~~ Quick Start Guide</title>
<date>$Date$</date>
<product>all</product>
<summary>Get started quickly using ~~PRODUCT_NAME~~ to develop and debug Python code.</summary>

~~~if not WEBSITE and not PDF:
.. image:: ../~~MANUAL_HEADER_IMAGE~~
  :class: header
~~~

.. image:: /images/screenshots/wing7-screenshot-dark.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

~~~if WEBSITE:
.. note::
  **"The best Python IDE. And I have tried them all!"**
  *-- Ahmed Ali*
~~~

This is a minimalist guide for getting started quickly with ~~PRODUCT_NAME~~. For a more
in-depth introduction, try the `Tutorial <ref:intro/tutorial>`__.

~~~if WINGPRO: 
Wing Pro is a light-weight yet powerful integrated development environment that was
designed from the ground up for Python. Once you're up to speed with Wing you should find
that:

* Wing speeds up your development of new code
  
* Wing makes it easier to understand and work with existing code
  
* Wing reveals errors earlier in the development process

* Wing makes it easier to find and fix bugs
  
* Wing adapts to your needs and style
  
This is made possible through deep code analysis (both static and runtime), a focus
on interactive development in the live runtime, high-level editing operations and
refactoring, continuous early error detection, support for test-driven development,
powerful always-on debugger, seamless support for remote development, and extreme
configurability.
~~~

~~~if WINGPER:
Wing Personal is a simple Python IDE designed for students and hobbyists or those using
Python occasionally for fairly simple development tasks. If you are working intensively
with Python, you should try Wing Pro instead. You will be much more productive, and
chances are you will have no problem understanding and appreciating Wing Pro's more
advanced features.
~~~

~~~if WING101:
Wing 101 was designed to be the simplest Python IDE possible that fully supports students
learning to program for the first time. If you already know how to program, or if you are
using Wing for development outside of introductory course work, you should use Wing
Personal or Wing Pro instead. You will be much more productive, and chances are you will
have no problem understanding and using the additional features provided by those
products.
~~~

Let's get started with ~~PRODUCT_NAME~~!

Install Python
--------------

If you don't already have Python on your system, install it now.  Two good options are:

* Obtain the standard Python distribution from `python.org <https://python.org/download>`__
* Use `Anaconda <https://www.anaconda.com/>`__ for seamless access to many third party 
  Python libraries. See `Anaconda package lists
  <https://docs.anaconda.com/anaconda/packages/pkg-docs>`__ for a list of the available
  libraries.

See `Supported Python Versions <ref:install/supported-python-versions>`__ for other 
options.

~~~if not WEBSITE:
You may need to restart Wing after installing Python, so that it can recognize the
new installation.
~~~

~~~if WEBSITE:
Install Wing
------------

If you don't already have Wing installed, `download it now
<https://wingware.com/downloads>`__. For detailed installation instructions, see
`Installing Wing <ref:install/installing>`__.

Start Wing
----------

Wing can be launched from the start menu on Windows, by double clicking on the application
on OS X, or with ``~~FULL_EXECUTABLE~~`` on Linux. In Wing Personal the executable is
instead named ``wing-personal~~MAJOR_VERSION~~.~~MINOR_VERSION~~`` and in Wing 101 it is
named ``wing-101-~~MAJOR_VERSION~~.~~MINOR_VERSION~~``.

For more information, see `Running Wing <ref:install/running-the-ide>`__.

Wing Pro requires a license to run. If you don't have a license, you can obtain a 30-day
trial the first time you start it. Wing Personal and Wing 101 are free to run without 
a license.

.. note::
  Once Wing is running, you should switch to using the ``Quick Start Guide`` listed in
  Wing's ``Help`` menu because it contains links directly into the IDE's functionality.
  That copy also omits features not available in your selected product level.
~~~

~~~if WING101:
Configure Python
----------------

Wing finds the latest installed Python and uses that with your code. If you want to change
which Python is used, set the ``Python Executable`` using ``Configure Python`` in the
``Edit`` menu.
~~~

~~~if not WING101:
Set up a Project
----------------

After Wing is running, create a new project from the ``Project`` menu. If you want to
create a new virtualenv to use with your project, select the ``Create New Virtualenv``
project type, enter the name and parent directory for the new virtualenv, and select
the base Python interpreter to use.

Alternatively, if you don't want to create a new virtualenv, select ``Empty Python
Project`` project type. Then configure your project with the following steps:

1) Use ``Add Existing Directory`` in the ``Project`` menu to add your sources to the
   project. It's best to constrain this to the directories you are actively working with
   and let Wing find the libraries you use through the ``Python Path``.

2) Use ``Project Properties`` in the ``Project`` menu to set ``Python Executable`` to the
   ``python.exe`` or other interpreter executable you want to use with your project. If
   Python is not on the ``PATH``, set this to the the full path that is in 
   ``sys.executable`` in the desired Python installation.
   
3) If your code alters ``sys.path`` or loads modules in a non-standard way then you may
   need to set ``Python Path`` in ``Project Properties`` so that Wing can find your 
   modules for auto-completion, refactoring, debugging, testing, and other features.
  
4) You may want to right-click on your main entry point in the ``Project`` tool and select
   ``Set As Main Entry Point`` so that debugging always starts there.

5) Use ``Save Project As`` in the ``Project`` menu to save your project to disk.

See `Project-Wide Properties <ref:proj/project-properties>`__ and `Per-File
Properties <ref:proj/file-properties>`__ for a description of all available
properties. 

Notice that Wing also offers other project types in the ``New Project`` dialog,
including 
~~~
~~~if WINGPRO:
remote project types for connecting to a `remote host via SSH <ref:proj/remote-hosts>`__, 
accessing a `Vagrant <ref:howtos/vagrant>`__ instance, or working with `Windows
Subsystem for Linux <ref:howtos/wsl>`__, and
~~~
~~~if not WING101:
a project type for each of the frameworks, tools, and libraries listed in
`How-Tos <ref:howtos/index>`__.

Wing may consume significant CPU time when it first analyzes your code base. Progress is
indicated in the lower left of the IDE window. Once this is done, the results are cached
across sessions and Wing should run with a snappy and responsive interface. See `Source
Code Analysis <ref:edit/source-code-analysis>`__ to learn how Wing's source analysis
system works.
~~~

~~~if WEBSITE:
Wing 101 does not have projects.  Configuring the Python environment is instead
done with ``Configure Python`` in the ``Edit`` menu.
~~~

Basic Configuration
-------------------

You are now ready to start working with code, but may want to make a few
configuration changes first:

**Display Colors -** The `User Interface > Color Palette
<script:show_preferences_gui#prefname="gui.qt-color-palette">`__ preference chooses the
colors used in the editor or the whole user interface if the `User Interface > Use Color
Palette Throughout the UI
<script:show_preferences_gui#prefname="gui.use-palette-throughout-ui">`__ preference is
enabled.

**Key Bindings -** Wing can emulate VI/Vim, Visual Studio, Emacs, Eclipse, XCode, MATLAB,
and Brief editors, as selected from ``Keyboard Personality`` in the ``Edit`` menu or with
the `User Interface > Keyboard > Personality
<script:show_preferences_gui#prefname="edit.personality">`__ preference.

**Tab Key -** The default tab key action depends on the selected keyboard personality and
in some cases file type, context, and whether or not there is a selection in the editor.
This can be changed from the `User Interface > Keyboard > Tab Key Action
<script:show_preferences_gui#prefname="edit.tab-key-action">`__ preference.

~~~if not WING101:
**Completion Keys -** By default, the auto-completer uses the ``Tab`` key for completion,
but other keys can be added using the `Editor > Auto-completion > Completion Keys
<script:show_preferences_gui#prefname="edit.autocomplete-keys">`__ preference.
~~~

There are many other options in `Preferences <script:show_preferences_gui>`__.

Navigating Code
---------------

~~~if not WING101:
~~PRODUCT_NAME~~ provides a number of different ways to navigate the structure of your
code, and several methods for quickly finding symbols or files by name:
~~~
~~~if WING101:
Wing 101 provides severals ways to navigate and search your code:
~~~

**Source Index** menus at the top of the editor provide quick access to other parts of a
source file.
  
**Goto-definition** is available from the ``Source`` menu, and by right-clicking on
symbols in the
~~~if WINGPRO:
editor, `Python Shell <script:show-panel-python-shell>`__ and `Debug Console
<script:show-panel-debug-console>`__.
~~~
~~~if not WINGPRO:
editor and , `Python Shell <script:show-panel-python-shell>`__.
~~~
Use the forward/back history buttons at the top left of the editor to return from the
point of definition.

~~~if WINGPRO:
**Find Points of Use** in Wing Pro's ``Source`` menu shows where the current symbol is
being used. This distinguishes between separate but like-named symbols.
~~~

~~~if not WING101:
**Find Symbol** in the ``Source`` menu in Wing Pro and Wing Personal jumps to a symbol
defined in the current file when you type a fragment of its name.
~~~

~~~if WINGPRO:
**Find Symbol in Project** in the ``Source`` menu in Wing Pro works the same way but
searches all files in the project.
~~~

~~~if not WING101:
**Open From Project** in the ``File`` menu in Wing Pro and Wing Personal provides a
similar interface for quickly opening project files.
~~~

See `Navigating Source <ref:edit/navigating-source>`__ for details on the above.

~~~if not WING101:
**Source Browser** in the ``Tools`` menu in Wing Pro and Wing Personal provides module or
class oriented display of the structure of your code.  `Details <ref:browser/index>`__

**Source Assistant** in the ``Tools`` menu shows detailed information about symbols
selected in the editor, auto-completer, `Source Browser <script:show-panel-browser>`__,
`Python Shell <script:show-panel-python-shell>`__, `Project <script:show-panel-project>`__,
and other tools. `Details <ref:edit/source-assistant>`__
~~~

~~~if not WING101:
Searching
---------

~~PRODUCT_NAME~~ provides several different interfaces for searching your code. Which you
use depends on what you want to search and how you prefer to interact with the search and
replace functionality:
~~~

**Toolbar search** is a quick way to search the current file. `Details
<ref:edit/toolbar-quick-search>`__

**Search** in the ``Tools`` menu shows the `Search
<script:show-panel-interactive-search>`__ tool, which provides incremental text, wildcard,
and regular expression search and replace in selections and the current file or
documentation page. `Details <ref:edit/search-tool>`__

~~~if not WING101:
**Mini-search** in Wing Pro and Wing Personal provides powerful keyboard-driven search 
and replace. The key bindings listed in the ``Mini-search`` area of the ``Edit`` menu
display the search entry area at the bottom of the window.  `Details <ref:edit/mini-search>`__

**Search in Files** in the ``Tools`` menu in Wing Pro and Wing Personal shows the 
`Search in Files <script:show-panel-batch-search>`__ tool, which provides wildcard
and regular expression search and replace in filtered sets of files, directories, named
file sets, and within the project and documentation.  `Details <ref:edit/search-in-files>`__.
~~~

Editing Code
------------

~~PRODUCT_NAME~~'s editor is designed to speed up the process of writing and modifying 
Python code, and to reduce the incidence of coding errors.  Its features include:

**Auto-completion** in Wing's
~~~if WINGPRO:
editor, `Python Shell <script:show-panel-python-shell>`__ and `Debug Console
<script:show-panel-debug-console>`__
~~~
~~~if not WINGPRO:
editor and , `Python Shell <script:show-panel-python-shell>`__
~~~
speeds up typing and reduces coding errors. The auto-completer uses ``Tab`` by default for
completion, but this can be changed in the `Editor > Auto-completion > Completion Keys
<script:show_preferences_gui#prefname="edit.autocomplete-keys">`__ preference. This
feature is disabled by default in Wing 101.  `Details <ref:edit/auto-completion>`__
  
~~~if not WING101:
**Auto-indent** in Wing Pro and Wing Personal matches the file's existing indentation.
When multiple lines are pasted, they are re-indented according to context. A single
``Undo`` reverts an unwanted indentation change. A selected range of code may be
re-indented as a block using ``Indentation`` in the ``Source`` menu or the indentation
toolbar group. The `Indentation <script:show-panel-indent>`__ tool may be used to convert
a whole file's indentation style.  `Details <ref:edit/indentation>`__
~~~

~~~if WINGPRO:
**Auto-Editing** in Wing Pro implements a range of operations such as auto-entering
closing parentheses, brackets, braces, and quotes. Among other things, Wing also
auto-enters invocation arguments, manages new blocks with the ``:`` key, and corrects
out-of-order typing. Auto-editing operations can be enabled and disabled in the `Editor >
Auto-editing <script:show_preferences_gui#prefname="edit.auto-edit-enabled">`__
preferences group. The default set includes those operations that don't affect finger
memory. The others are well worth learning. `Details <ref:edit/auto-editing>`__
  
**Refactoring** operations in Wing Pro, accessed from the ``Refactoring`` menu, implement
automated renaming and moving of symbols, creating functions or methods out of existing
code, and introducing variables much more quickly than by manually editing code. `Details
<ref:refactoring/index>`__
~~~

**Multiple Selections** can be made with ``Multiple Selections`` in the ``Edit`` menu, the
multiple selections toolbar item, and by pressing ``Ctrl+Alt`` (or ``Command+Option`` on
OS X) while making a selection with the mouse. Once multiple selections have been made,
edits made will be applied to all the selections at once. `Details
<ref:edit/multiple-selections>`__

~~~if WINGPRO:
**Code Warnings** are shown in Wing Pro for syntax errors, indentation problems,
unreachable code, use of undefined variables and attributes, unresolvable imports, and
some other problems. External checkers like pylint, pep8, and mypy may also be configured
as sources for the code warnings. Warnings are shown on the editor with details shown
in a tooltip when the mouse hovers over the warning indicator.  Warnings can be navigated
from the warnings menu in the top right of the editor and managed from the `Code Warnings
<script:show-panel-code-warnings>`__ tool. `Details <ref:warnings/index>`__

**Snippets** in Wing Pro are included in Wing's auto-completer as a quick way to enter
commonly repeated patterns for coding standards, documentation, testing, and so forth.
Data entry for snippet arguments is inline in the editor. Use the ``Tab`` key to move
between the fields. Edit or add snippets in the `Snippets <script:show-panel-snippets>`__
tool.  `Details <ref:edit/snippets>`__
  
**Turbo Completion** in Wing Pro is an optional auto-completion mode for Python, made
possible by Wing's powerful source analysis engine. When the `Editor > Auto-completion >
Python Turbo Mode <script:show_preferences_gui#prefname="edit.autocomplete-turbo-mode">`__
preference is enabled, Wing turns every non-symbol key into a completion key in contexts
where a new symbol name is not being typed. `Details <ref:edit/turbo-completion>`__
~~~

**Quick Selection** operations in the ``Edit > Select`` menu allow selecting whole 
statements, blocks, or scopes before copying, editing, or searching through them. `Details
<ref:edit/selecting>`__

Debugging Code
--------------

Wing's debugger is a powerful tool for finding and fixing bugs, understanding unfamiliar
code, and writing new code interactively. You can launch code from the ``Debug`` menu or
toolbar, `from the Python Shell <ref:debug/shell-debugging>`__, or from outside of the IDE
either `on the same machine <ref:debug/debugging-externally-launched-code>`__ or `on
another host <ref:debug/remote-debugging>`__.

`Breakpoints <ref:debug/setting-breakpoints>`__ can be set by clicking on the breakpoint
margin to the left of the editor. `Stepping operations <ref:debug/flow-control>`__ are in
the ``Debug`` menu and toolbar.

The `Stack Data <script:show-panel-debug-data>`__ tool is used to inspect or change
program data.
~~~if WINGPRO:
Right-click on items to display the item as an `array or in textual form
<ref:debug/details-view>`__.
~~~
Hovering the mouse over a `symbol in the editor <ref:debug/editor-data>`__ shows the value
for that symbol in a tooltip, if available on the active debug stack.
~~~if WINGPRO:
Pressing ``Shift-Space`` shows tooltips for all symbols visible in the editor.
~~~

Debug process I/O is shown in the `Debug I/O <script:show-panel-debug-io>`__ tool, or
`optionally in an external console <ref:debug/external-i-o-consoles>`__.

~~~if not WING101:
Other debugger features include:
~~~

~~~if WINGPRO:
**Interactive Debugging** is supported by Wing Pro's `Debug Console
<script:show-panel-debug-console>`__, which provides a Python prompt that executes code in
the current debug stack frame. When the debugger is paused, Wing also uses the live
runtime state to populate the auto-completer in the editor, `Source Assistant
<script:show-panel-source-assistant>`__, goto-definition, and other tools. `Details
<ref:debug/debug-console>`__

**Conditional Breakpoints** can be used in Wing Pro to isolate and understand complex bugs
by stopping before they occur. Using a conditional breakpoint to isolate a broken case and
the `Debug Console <script:show-panel-debug-console>`__ to design a fix is far more productive
than relaunching code repeatedly. `Details <ref:debug/setting-breakpoints>`__
  
**Move Program Counter** is supported by Wing Pro, by right-clicking in the editor and
selecting ``Move Program Counter Here``. Because of how Python is implemented, this
feature works only in the innermost stack frame and it does not work when the debugger is
stopped on an exception.

**Watching Values** in Wing Pro by right-clicking on the editor or any of the data views
tracks values over time by symbolic name or object reference in the `Watch
<script:show-panel-debug-watch>`__ tool.  Expressions can be also be watched.  
`Details <ref:debug/tracking-values>`__
~~~

~~~if not WING101:
**Launch Configurations** in the ``Project`` menu in Wing Pro and Wing Personal 
define different runtime environments for debugging, executing, and unit testing your
code. `Details <ref:proj/launch-configs>`__.

**Named Entry Points** in the ``Debug`` menu in Wing Pro and Wing Personal provide a way
to launch the same file with different debug environments. `Details
<ref:debug/named-entry-points>`__ 
~~~

Other Features
--------------

~~~if WING101:
Several other features are available to assist in your Python coding:
~~~
~~~if not WING101:
~~PRODUCT_NAME~~ includes a number of other features designed to make Python coding
easier and more productive:
~~~

**Python Shell** -- Wing's `Python Shell <script:show-panel-python-shell>`__ lets you try
out code in an independent sandbox process. To enable debugging, click the bug icon in the
top right of the ``Python Shell``.
~~~if not WING101:
In Wing Pro and Wing Personal, the shell provides auto-completion, goto-definition, and is 
integrated with the `Source Assistant <script:show-panel-source-assistant>`__.
~~~
~~~if WING101:
The shell provides auto-completion if it has been enabled in preferences.
~~~
`Details <ref:debug/python-shell>`__

~~~if WINGPRO:
**Unit Testing** in Wing Pro's `Testing <script:show-panel-testing>`__ tool works with
unittest, doctest, pytest, nose, and Django unit tests. You can run tests suites, view the
results, and debug tests. `Details <ref:testing/index>`__
  
**Version Control** in Wing Pro supports revision control with Mercurial, Git, Subversion,
Perforce, Bazaar, and CVS. Wing auto-detects which systems are used in your project and
shows the appropriate additional menus and tools in the ``Tools`` menu. `Details
<ref:versioncontrol/index>`__.

**Difference and Merge** in the ``Source`` menu can be used to compare and merge files and
directories on disk, files open in the IDE, an unsaved buffer with disk, and a working
copy with its revision control repository. `Details <ref:diff/index>`__

**Remote Development** is easy in Wing Pro, to remote hosts, containers, or virtual
machines. Use the ``Remote Hosts`` item in the ``Project`` menu to configure a remote
host, then set the ``Python Executable`` in ``Project Properties`` to that remote host,
and use ``Add Existing Directory`` in the ``Project`` menu to add your remote directories
to the project. Wing can edit, debug, test, search, inspect, and manage files, run the
`Python Shell <script:show-panel-python-shell>`__, and execute `OS Commands
<script:show-panel-oscommands>`__ on the remote host in the same way as it does when
working locally. `Details <ref:proj/remote-hosts>`__ 
~~~

~~~if not WING101:
**OS Commands** in the ``Tools`` menu in Wing Pro and Wing Personal's displays the `OS
Commands <script:show-panel-os-command>`__ tool, which execute external tools for build,
code generation, and other purposes. `Details <ref:oscommands/index>`__.
~~~

**Preferences** in the ``Edit`` menu (or ``~~OSX_BUNDLE~~`` menu on OS X) gives you
control of the overall layout and color of the IDE, among many other options. Right click
on tool and editor tabs for layout options, or drag tabs to move them or create new
splits. Right-click on the toolbar to configure which tools are visible or to add your
own. See `Customization <ref:custom/index>`__ for details.

~~~if not WING101:
**Perspectives** in Wing Pro and Wing Personal let you save named tool panel layouts.
`Details <ref:custom/perspectives>`__.

**Other Features** like `bookmarks <ref:edit/bookmarks>`__, `code folding
<ref:edit/folding>`__, `keyboard macros <ref:edit/keyboard-macros>`__ are also available,
and you can `extend Wing by writing Python scripts <ref:scripting/index>`__.
~~~

Further Reading
---------------

As you work with ~~PRODUCT_NAME~~ on your own software development projects, the following
resources may be useful:

* `Wing Support Website <https://wingware.com/support>`__ which includes a Q&A support
  forum, mailing lists, documentation, links to social media, and other information 
  for Wing users.

* `Wing Reference Manual <ref:manual>`__ which documents all the features in detail.

~~~if not WING101:
* `How-Tos <ref:howtos/index>`__ with instructions for using Wing with third party
  frameworks, applications, and tool, like Django, Jupyter, matplotlib, Autodesk Maya, 
  Raspberry Pi, pygame, and many others.
~~~

* Wing displays a useful tip at startup, to help you continue learning about the feature
  set over time. These are also accessible from `Wing Tips <script:show-wingtip>`__ in 
  the ``Help`` menu.

**Thanks for using ~~PRODUCT_NAME~~!**
