Using Wing with Pyramid

Wing is a Python IDE that can be used to develop, test, and
debug Python code written for the Pyramid,
web development framework. Two versions of Wing are appropriate for use with this document:
Wing Pro is the full-featured Python IDE for professional programmers, and Wing Personal
is a free alternative with reduced feature set.

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.

Installing Pyramid

Please see the Pyramid website
(part of the Pylons project), which provides complete instructions for
installing the Pyramid framework. The procedure varies slightly by OS.

Like any Python package, Pyramid will install itself using whichever instance
of Python runs the installer script. You should be using a Python version at
least 2.6.

Pyramid projects are typically installed inside of a virtualenv, to maintain a
"sandboxed" installation separate from your main Python installation. This
allows Python packages that you install as part of your Pyramid project to be
kept entirely separate from your system's main Python environment, and from any
other virtualenvs that you may have. Creating or removing a virtualenv is just
a couple of file system commands, so it's easy and quick to start a new one
just to test an alternative configuration of your project. This makes it very
easy to test "what-if" scenarios based on installing different versions of the
packages relied upon by your project. For example, you could use a new
virtualenv if you wanted to try serving your app using a newly released version
of your ORM layer or your templating engine, or a newly released or beta
version of Pyramid itself.

This How-To was developed with Pyramid version 1.3.

Configuring your Wing Project

This section assumes your Pyramid project is called 'project' and is installed
in a virtualenv at .../project where ... is the full path to the
location of your project. We also assume that you are running Wing, that
you have your current Wing Project open and saved as
.../project/project.wpr (or whatever you chose to name your project).

Make sure that your Pyramid project directory (which should be the same as your
virtualenv) is added to your Wing project with AddDirectory in the
Project menu, and that you have saved the project. There is no need to add
the entire .../project directory to the Wing project, as that would include the
entire project/bin area. Typical Pyramid project structure looks like
project/Project/project. The Project (upper case) directory holds setup and
README information for your project and the configuration files, ending in
.ini, which allow you to start your project's server with different settings.

Ordinarily you'll have project/Project/development.ini which contains the
settings (including enabling lots of logging, etc) that you run during
development activities, and project/Project/production.ini which contains
different settings (turning off most logging and any development-related
security vulnerabilities such as open administrative access) that you'll use in
production. But you can also create additional .ini files for any purpose, such
as when you want to simulate serving your project under different conditions,
e.g. connecting to a different database server.

The one file you'll need to add to your Wing project from the .../project
level of your directory structure is .../project/bin/pserve. Then open it in
Wing and set it as Main Debug File from the Debug menu.

Next open up the PythonShell tool and type importsys followed by
sys.executable to check whether Wing is using the Python that will be
running the Pyramid server. If not, verify that the shell's status message does
not indicate that it needs to be restarted to load configuration changes. If
this message is present, restart the shell from its Options menu and try
again. If the message is not present, open ProjectProperties and set the
PythonExecutable, then restart the shell again and verify that
sys.executable is correct. The interpreter used in this step will vary
depending on whether your .../project directory is enabled as a virtualenv
or not.

Once this is done, Wing's source analysis engine should be able to find and
analyze your code and Pyramid. Analysis status messages may show up in the
lower left of Wing's main window while analysis is in progress.

Debugging

To debug code running under Pyramid, place a copy wingdbstub.py (from
the install directory listed in Wing's About box) into your project/Project
directory, the same directory that holds your .ini files and which is set as
the InitialDirectory for your Wing project. Near the top of any Python file
you wish to debug, place the following line:

import wingdbstub

Also click on the bug icon in the lower left of the main window and make sure
that AcceptDebugConnections is checked.

Then set a breakpoint on any location in your project's code that you know will
be reached when an HTTP or AJAX request is made to your server, depending on
what user actions in the browser you intend to follow with debugging. A common
breakpoint location would be in one of what Pyramid calls your View Callables,
which are the Python classes and/or methods called by the webserver depending
on the URL and other parameters of the request. Or, if you need to debug lower
levels of the stack, you can set breakpoints in the Pyramid source files
themselves, or in the source of any other package (such as your ORM or template
rendering system) that supports the handling of your web requests.

With a terminal window open, start your Pyramid server as you usually would, by
issuing the command:

pserve --reload development.ini

from within your project/Project directory. --reload is a convenient
option that restarts the server whenever you've saved any changes to your
Pyramid project's source files. You don't have to use it, but Wing's debugger
is still able to attach and operate correctly if you do. If you are using a
different .ini file such as a production.ini or testing.ini, supply
its name to pserve instead.

Load http://localhost:5000/ or the page you want to debug in a browser. The
port that your server uses (5000 in this example) is set in your .ini file, in
a section that looks like the following:

[server:main]
use = egg:waitress#main
host = 0.0.0.0
port = 5000

Wing should stop on your breakpoint. Be sure to look aroung a bit with the
StackData tool, and in Wing Pro the DebugProbe (a command line that
works in the runtime state of your current debug stack frame). All the
debugging tools are available from the Tools menu, if not already shown.

Notes on Auto-Completion

Wing provides auto-completion on Python code and within basic HTML elements,
and can help a lot within the various templating languages that can be used in
a Pyramid project.

The autocomplete information available to Wing is based on static analysis of
your project files and any files Wing can find on your Python Path or via
imports in other Python files.

Additionally, when the debugger is active and paused, Wing usess introspection
of the live runtime state 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 Mako Templates

A good choice of templating engine for the Pyramid projects of a Wing user
is Mako, because it allows the full syntax
of Python in expression substitutions and control structures and this maximizes
Wing's ability to help out. Mako templates are simply marked-up HTML files, and
as such they cannot be directly stepped through using the debugger. However,
they are compiled to .py files whenever the source file is altered, and you can
set Wing debug breakpoints in the .py files corresponding to your templates.

Debugging Mako templates with Wing requires one optional setting that can
be made in your .ini file, usually development.ini. Under the [app:main]
section, add the following line:

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

This location will exist in most typical Pyramid projects. If yours does
not have it you can create it, or point the setting to an existing location of
choice. Without this setting (by default), mako templates are compiled in
memory and not cached to disk. With this setting in place, your mako templates
will be compiled to actual .py files in the desired location, with the same
filename as the original template plus the .py extension appended to the end.

You should be able to set breakpoints within these .mako.py files just like
anywhere else in your project. If necessary, add the following at the top of
the template file:

<%! import wingdbstub %>

This uses mako's module-level import facility to drop the import directly into
the compiled .mako.py file, and will prevent the import from disappearing
when a template is automatically recompiled after its source file is changed.

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.

Debugging without wingdbstub.py (experimental)

In some cases it may be more convenient to debug your Pyramid project files by
launching your Pyramid server directly from Wing, rather than using
wingdbstub.py as described above. In this approach, you use the DebugStart or Restart commands to start and restart your server, instead of
launching it on the command line outside of Wing.

To try this, verify that you have set the MainDebugFile to
.../project/bin/pserve by opening the file, and selecting SetCurrentasMainDebugFile from the Debug menu.

Then right click on the pserve file in the editor or Project tool and use
Properties... to set its RunArguments to development.ini or
whatever .ini file you want to use with debugging, and then set the
InitialDirectory property to .../project/Project or wherever your
.ini files are located.

Make sure that the --reload option is not supplied in the RunArguments
that you configure, as this will interfere with the debugger. You will need
to press the restart debugging icon in the toolbar or select RestartDebugging
from the Debug menu to restart the Pyramid server after making changes to
Python files or templates.

Once this is done, press the green Debug icon in the toolbar or use
Start/Continue in the Debug menu to start debugging. The
DebugI/O tool in Wing, available in the Tools menu, will display any
output from the server.