<type>how-to</type>
<domain>install</domain>
<id>pyramid</id>
<title>Using Wing with Pyramid</title>
<date>$Date: 2006-12-28 17:21:05 -0500 (Thu, 28 Dec 2006) $</date>
<product>per+</product>
<summary>Learn how Wing can be used to speed up development and debugging of Python code written for the Pyramid web development system.</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 written for the `Pyramid <https://trypyramid.com/>`__
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 Pyramid. 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>`__.

Creating a Wing Project
-----------------------

To create a new project, use ``New Project`` in Wing's ``Project menu. Select the project
type ``Pyramid`` and under ``Python Executable`` select ``Custom`` and then enter the full
path of the Python you plan to use with Pyramid. 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.

Debugging
---------

Launching from Wing
...................

The easiest way to debug Pyramid is just to launch it from Wing. To do this, find and open
``pserve`` from Pyramid and select ``Set Current as Main Entry Point`` from the ``Debug``
menu.

Then right-click on ``pserve`` and under ``Environment`` enter your run arguments,
for example::

  development.ini
  
Then go into ``Project Properties`` in the ``Project`` menu and set ``Initial Directory``
under the ``Debug/Execute`` tab to the full path of the directory that contains your
``.ini`` files.

Now you can start debugging with ``Start/Continue`` in the ``Debug`` menu or from the
toolbar. You can load `http://localhost:6543/ <http://localhost:6543/>`__ or other page,
or initiate an AJAX request, and Wing will stop on any breakpoints or exceptions. This
works with any Python code, including any View Callable, Pyramid internals, or any other
library or package used by your code.

From here, you can step through code or inspect the program state with ``Stack Data`` and
other tools. In Wing Pro, the ``Debug Console`` provides a command line that allows you to
interact with the current stack frame in your debug process. All the debugging tools are
available from the ``Tools`` menu.

Auto-reloading Changes
......................

With the above configuration, you'll need to restart Pyramid every time you make a change.
If you have Wing Pro you can cause Pyramid to auto-reload changes. To do this, add the
``--reload`` option to the run arguments you set for ``pserve``, for example::

  --reload development.ini
  
Then enable ``Debug Child Processes`` in ``Project Properties``, from the ``Project``
menu, so that Pyramid's reloaded processes will also be debugged.

This option is only available in Wing Pro. In Wing Personal you'll need to use
``wingdbstub`` for reloading, as described above.

Launching Outside of Wing
.........................

Wing can also debug code that is launched from outside of the IDE, for example from the
command line. To do this with Pyramid, copy ``wingdbstub.py`` from the ``Install
Directory`` listed in Wing's `About <script:about-application>`__ box into the directory
that contains your Pyramid ``.ini`` files. You may need to set the value of ``WINGHOME``
inside your copy of this file to the full path of the install directory you copied it
from, or On OS X to the full path of the ``.app``.

Next place the following line into your source, on a line before the code you wish to 
debug::

  import wingdbstub

Then click on the bug icon in the lower left of Wing's window and make sure that ``Accept
Debug Connections`` is checked.

Now you can start your Pyramid server as you usually would, for example::

  pserve --reload development.ini

Using ``--reload`` is not necessary but it is supported by Wing's debugger and makes
testing of changes much easier.

Notes on Auto-Completion
------------------------

Wing provides auto-completion on Python code and in other files, including the various
templating languages that can be used with Pyramid.

The autocomplete information available to Wing is based on static analysis of your project
files and any files Wing can find through imports, by searching on your Python Path.

When the debugger is active and paused, Wing also uses introspection of the live runtime
for any template or Python code that is active on the stack. As a result, it is often more
informative to work on your source files while Wing's debugger is active and paused at a
breakpoint, exception, or anywhere in the source code reached by stepping.

Debugging Jinga2 Templates
--------------------------

The Jinga2 template engine sets up stack frames in a way that makes it possible to set
breakpoints directly in ``.jinga2`` template files and step through them, viewing data in
``Stack Data`` and other tools in the same way as for Python code.

Debugging support in the Jinga engine is imperfect in that that not all tags are reached
and some tags cause lines to be visited multiple times. However, this capability can still
be useful to stop Wing's debugger when a particular template is being invoked.

Debugging Mako Templates
------------------------

Another good choice of templating engine for Pyramid is `Mako
<http://www.makotemplates.org>`__, because it allows the full syntax of Python in
expression substitutions and control structures. However, Mako templates cannot be
directly stepped through using the debugger. Instead, you can set breakpoints in the
``.py`` files produced by Mako for templates.

To debug Mako templates with Wing you will need to modify your ``.ini`` file to add the
following line in the ``[app:main]`` section::

  mako.module_directory=%(here)s/data/templates

You may need to change the path to match your project. Without this setting, mako
templates are compiled in memory and not cached to disk, so you won't be able to debug
them. With this setting, Mako will write ``.mako.py`` files for each template to the
specified directory, whenever the template changes. You can set breakpoints within these
generated files.

Your ``.mako.py`` files will not be in one-to-one line correspondence with their ``.mako``
source files, but mako inserts tracking comments indicating original source line
numbering.

If you are starting Pyramid outside of Wing and need to use ``wingdbstub`` to initiate
debugging, as described earlier, and want to do this from a Mako template, then you can
add the following to the template::

  <%! import wingdbstub %>

Remote Development
------------------

Wing Pro can work with Pyramid 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.

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

For more information see:

* `Pyramid documentation <https://trypyramid.com/>`__

* `Quickstart Guide <ref:howtos/quickstart>`__ 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>`__ documents Wing in detail.
