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.
If you do not already have Wing installed, download it now.
To get started using Wing, refer to the tutorial in the Help menu in Wing or the Quickstart Guide.
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 Add Directory 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 Python Shell tool and type import sys 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 Project Properties and set the Python Executable, 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.
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 Initial Directory for your Wing project. Near the top of any Python file you wish to debug, place the following line:
Also click on the bug icon in the lower left of the main window and make sure that Accept Debug Connections 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 Stack Data tool, and in Wing Pro the Debug Probe (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:
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 Debug Start 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 Main Debug File to .../project/bin/pserve by opening the file, and selecting Set Current as Main Debug File from the Debug menu.
Then right click on the pserve file in the editor or Project tool and use Properties... to set its Run Arguments to development.ini or whatever .ini file you want to use with debugging, and then set the Initial Directory property to .../project/Project or wherever your .ini files are located.
Make sure that the --reload option is not supplied in the Run Arguments that you configure, as this will interfere with the debugger. You will need to press the restart debugging icon in the toolbar or select Restart Debugging 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 Debug I/O tool in Wing, available in the Tools menu, will display any output from the server.
Wing provides many other options and tools. For more information:
Thanks to Eric Ongerth for providing the initial version of this How-To.