<type>how-to</type>
<domain>install</domain>
<id>web2py</id>
<title>Using Wing with web2py</title>
<date>$Date: 2006-05-26 17:43:42 -0400 (Fri, 26 May 2006) $</date>
<product>per+</product>
<summary>Tips for using Wing with web2py, an enterprise web framework.</summary>

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

`Wing <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code and templates written for `web2py <http://www.web2py.com/>`__, a
powerful open source web development framework. 

Two versions of Wing are appropriate for use with this document: Wing Pro is the
full-featured Python IDE for professional developers, and Wing Personal is a free
alternative with reduced feature set.

If you do not already have Wing installed, `download it now <https://wingware.com/downloads>`__.

This document describes how to configure Wing for web2py. To get started using Wing as
your Python IDE, please refer to the tutorial in Wing's ``Help`` menu or read the
`Quickstart Guide <ref:howtos/quickstart>`__.

Introduction
------------

Wing allows you to debug Python code and templates running under web2py as you interact
with it from your web browser. Breakpoints set in your code from the IDE will be reached,
allowing inspection of your running code's local and global variables with Wing's various
debugging tools. In addition, in Wing Pro, the `Debug Console
<script:show-panel#panel_type="debug-console">`__ allows you to interactively execute
methods on objects and get values of variables that are available in the context of the
running web app.

There is more than one way to do this, but in this document we focus on an "in process"
method where the web2py server is run from within Wing, as opposed to `attaching to a
remote process <ref:debug/debugging-externally-launched-code>`__.

Setting up a Project
--------------------

The best way to install web2py is to clone the `git repository
<https://github.com/web2py/web2py/>`__. Be sure to follow the instructions in the readme
so you clone all the dependencies recursively.

To create a new project, use ``New Project`` in Wing's ``Project menu. Select the project
type ``web2py`` and under ``Python Executable`` select ``Custom`` and then enter the full
path of the Python you plan to use with web2py. You can determine the correct value
to use by executing the following commands interactively in Python.  If you are using
virtualenv, this will be the virtualenv's Python executable::

  import sys
  sys.executable

Press ``OK`` and then add the directory with your source code to the new project with
``Add Existing Directory`` in the ``Project`` menu.

After the ``Project`` tool populates, find and right click on the file ``web2py.py`` and
select ``Set As Main Entry Point``.

Remote Development
..................

Wing Pro can work with web2py code that is running on a remote host, VM, or container. To
do this, you need to be able to connect to the remote system with SSH. Then you can create
your project in the same way as above, using the ``Connect to Remote Host via SSH``
project type.  See `Remote Hosts <ref:proj/remote-hosts>`__ for more information on
remote development with Wing Pro.

Debugging
---------

You can now debug web2py by clicking on the green ``Debug`` icon in Wing's toolbar and
waiting for the web2py console to appear. Enter a password and start the server as usual.

Once web2py is running, open a file in Wing that you know will be reached when you load a
page of your web2py application in your web browser. Place a breakpoint in the code and
load the page in your web browser. Wing should stop at the breakpoint. Use the ``Stack
Data`` tool or ``Debug Console`` (in Wing Pro) to look around.

An example is to set a breakpoint in ``applications/examples/views/default/index.html``,
which is loaded when you go to the URL ``http://127.0.0.1:8000/examples/default/index``
(assuming local web2py install running on port 8000).

Notice that breakpoints work both in Python code and HTML template files.

Wing's ``Debug Console`` (in the ``Tools`` menu) is similar to running a shell from web2py
(with ``python web2py.py -S myApp -M``) but additionally includes your entire context and
provides auto-completion. You can easily inspect or modify variables, manually make
function calls, and continue debugging from your current context.

Usage Tips
----------

Setting Run Arguments
.....................

When you start debugging, Wing will show the ``File Properties`` for ``web2py.py``. This
includes a ``Run Arguments`` field under the ``Debug`` tab where you can add any web2py
option. For example, adding ``-a '<recycle>'`` will give you somewhat faster web2py
startup since it avoids showing the ``Tk`` dialogs and automatically opening a browser
window. This is handy once you already have a target page in your browser. Run ``python
web2py.py --help`` for a list of all the available options.

To avoid seeing the ``File Properties`` dialog each time you debug, un-check the "Show
this dialog before each run" check box. You can access it subsequently with ``Debug
Environment`` in the ``Debug`` menu.

Hung Cron Processes
...................

Web2py may spawn cron sub-processes that fail to terminate on some OSes when web2py is
debugged from Wing. This can lead to unresponsiveness of the debug process until those
sub-processes are killed. To avoid this, add the parameter ``-N`` to prevent the cron
processes from being spawned.

Better Auto-completion
......................

Because of the way web2py is designed, Wing's static analysis engine can fail to
find the types of commonly used values like ``db``.  To work around this, run
to a breakpoint in your code before editing it.  This causes Wing to use runtime
analysis as well as static analysis to drive auto-completion and other IDE features.

Related Documents
-----------------

Wing provides many other options and tools.  For more information:

* `web2py website <http://web2py.com/>`__ provides documentation and downloads.

* `Remote Web Development <ref:howtos/debugging-web-remote>`__ describes how to set up
  development on a remote host, VM, or container.
  
* `Quickstart Guide <ref:howtos/quickstart>`__ which contains additional basic information
   about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to
  Wing's features.

* `Wing Reference Manual <ref:manual>`__, which describes Wing in detail.


