Note

"The best solution for debugging Zope and Plone" -- Joel Burton, Member, Plone Team

Wing is a Python IDE that can be used to develop, test, and debug Python code written for Zope2 or Zope3. Wing provides auto-completion, call tips, and other features that help you write, navigate, and understand Zope code. Wing's debugger can be used to debug code in the context of the running Zope server, in response to page loads from a browser, and can work with Zope's code reloading features to achieve a very short edit/debug cycle.

Wing's code intelligence and debugging support work with Products, External Methods, file system-based Scripts and Zope itself. Wing is also useful for Zope-based frameworks like Plone (see Plone How-To).

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.

This document describes how to configure Wing for Zope. To get started using Wing as your Python IDE, please refer to the tutorial in Wing's Help menu or read the Quickstart Guide.

Before Getting Started

Note: This guide is for Zope2 users. If you are using Zope3, please try z3wingdbg by Martijn Pieters or refer to Debugging Externally Launched Code in the users manual to set up Zope3 debugging manually.

Limitations: Wing cannot debug DTML, Page Templates, ZCML, or Python code that is not stored on the file system.

Security Warning: We advise against using the WingDBG product on production web servers. Any user connected to the Wing debugger will (unavoidably) have extensive access to files and data on the system.

Upgrading from earlier Wing versions

If you are upgrading from an older version of Wing and have previously used Wing with your Zope installation(s), you need to manually upgrade WingDBG in each Zope instance. Otherwise, debugging may fail.

The easiest way to do this is to go to the Zope Control Panel, click on Wing Debug Service, and then Remove the control panel. Then restart Zope. Next, go into your Wing project's Extension Tab, verify that you've got the Zope Instance Home set correctly, and press Apply. This will offer to re-install WingDBG with the latest version and will configure it to point to the new version of Wing.

Quick Start on a Single Host

To use Wing with Zope running on the same host as the IDE:

Install Zope -- You can obtain Zope from zope.org. Version 2.5.1 or newer will work with Wing.
Install Wing -- You will need Wing 2.1 or later. See Installing for details.
Configure Wing -- Start Wing, create or open the project you wish to use (from the Project menu). Then use the Extensions tab in Project Properties to enable Zope2/Plone support and to specify the Zope2 Instance Home to use with the project. Wing will find your Zope installation by reading the file etc/zope.conf in the provided Zope instance. Once you press Apply or OK in the Project Properties dialog, Wing will ask to install the WingDBG product and will offer to add files from your Zope installation to the project. If your zope instance is generated by buildout, set the main debug file to the bin/instance file (bin\instance-script.py on Windows) in your buildout tree by opening the file in Wing and select Set Current as Main Debug File in the Debug menu. This will set up the effective sys.path for the instance.
Configure the WingDBG Product -- Start or restart Zope and log into http://localhost:8080/manage (assuming default Zope configuration). The Wing Debugging Service will be created automatically on startup; you can find it under the Control Panel of your server. If the Wing Debugging Service does not appear in the Control Panel, you may need to enable product loading in your zope.conf file by changing enable-product-installation off to enable-product-installation on.

Starting the Debugger

Proceed to the Wing Debugger Service by navigating to the Control Panel, then selecting the 'Wing Debugging Service'. Click in the "Start" button. The Wing IDE status area should display "Debugger: Debug process running".

Note that you can configure WingDBG to start and connect to the IDE automatically when Zope is started from the Advanced configuration tab.

Problems? See the Trouble-Shooting Guide below.

Test Drive Wing

Once you've started the debugger successfully, here are some things to try:

Run to a Breakpoint -- Open up your Zope code in Wing and set a breakpoint on a line that will be reached as the result of a browser page load. Then load that page in your web browser using the port number displayed by the Zope Management Interface after you started the debugger. By default, this is 50080, so your URL would look something like this:

http://localhost:50080/Rest/Of/Usual/Url

Explore the Debugger Tools -- Take a look at these tools available from the Tools menu:

Stack Data -- displays the stack, allows selecting current stack frame, and shows the locals and globals for that frame.
Debug Probe (Wing Pro only) -- lets you interact with your paused debug process using a Python shell prompt
Watch (Wing Pro only) -- watches values selected from other value views (by right-clicking and selecting one of the Watch items) and allows entering expressions to evaluate in the current stack frame
Modules (Wing Pro only) -- browses data for all modules in sys.modules
Exceptions -- displays exceptions that occur in the debug process
Debug I/O -- displays debug process output and processes keyboard input to the debug process, if any

Continue the Page Load -- When done, select Start / Continue from the Debug menu or toolbar.

Try Pause -- From Wing, you can pause the Zope process by pressing the pause icon in the toolbar or using Pause from the Debug menu. This is a good way to interrupt a lengthy computation to see what's going on. When done between page loads, it pauses Zope in its network service code.

Other Features -- Notice that Wing's editor contains a source index and presents you with an auto-completer when you're editing source code. Control-click on a source symbol to jump to its point of definition (or use Goto Selected Symbol in the Source menu). Wing Pro also includes a Source Assistant and Source Browser. The Source Assistant will display context appropriate call tips and documentation. Bring up the Source Browser from the Tools menu to look at the module and class structure of your code.

Setting Up Auto-Refresh

When you edit and save Zope External Methods or Scripts, your changes will automatically be loaded into Zope with each new browser page load.

By default, Zope Products are not automatically reloaded, but it is possible to configure them to do so. This can make debugging much faster and easier.

Take the following steps to take advantage of this feature:

Place a file called refresh.txt in your Product's source directory (for example, Products/MyProductName inside your Zope installation). This file tells Zope to allow refresh for this product.
Open the Zope Management Interface.
Expand the Control Panel and Products tabs on the upper left.
Click on your product.
Select the Refresh tab.
Check the "Auto refresh mode" check box and press "Change".
Make an edit to your product source, and you should see the changes you made take effect in the next browser page load.

Limitations: Zope may not refresh code if you use import statements within functions or methods. Also, code that manages to retain references to old code objects after a refresh (for example, by holding the references in a C/C++ extension module) will not perform as expected.

If you do run into a case where auto-reload causes problems, you will need to restart Zope from the Zope Management Interface's Control Panel or from the command line. Note that pressing the Stop button in Wing only disconnects from the debug process and does not terminate Zope.

Alternative Approach to Reloading

The refresh.txt techique for module reloading is discouraged in the Plone community. Another option for reloading both Zope and Plone filesystem-based code is plone.reload available from pypi at http://pypi.python.org/pypi/plone.reload. plone.reload will allow you to reload Python code that has been changed since the last reload, and also give you the option to reload any zcml configuration changes.

If you are using buildout, add plone.reload to the eggs and zcml sections of your buildout.cfg and re-run buildout.

To use plone.reload, assuming Zope is running on your local machine at port 8080, log into the ZMI as a Manager user, then go to http://localhost:8080/@@reload on your Zope instance with a web browser (append @@reload to the Zope instance root, not your Plone site if you are using Plone).

Notes:

If you are using Plone, your Plone product's profile config files (*.xml files) get loaded through the ZMI at /YourPlone/portal_setup in the import tab.
Code that uses a @decorator will still likely require a restart.

Setting up Remote Debugging

Configuring Wing for remote debugging can be complicated, so we recommend using X11 (Linux/Unix) or Remote Desktop (Windows) to run Wing on the same machine as Zope but display it remotely. When this is not possible, you can set up Wing to debug Zope running on another machine, as described below:

Set up File Sharing -- You will need some mechanism for sharing files between the Zope host and the Wing host. Windows file sharing, Samba, NFS, and ftp or rsync mirroring are all options. For secure file sharing via SSH on Linux, try sshfs.
Install Wing on the Server -- You will also need to install Wing on the host where Zope is running, if it is not already there. No license is needed for this installation, unless you plan to also run the IDE there. If there is no binary distribution of Wing available for the operating system where Zope is running, you can instead install only the debugger libraries by building them from source code (contact Wingware for details).
Basic Configuration -- Follow the instructions for Single-Host Debugging above first if you have not already done so. Then return here for additional setup instructions.
Configure Allowed Hosts -- You will need to add the IP address of the Zope host to the Allowed Hosts preference in Wing. Otherwise Wing will not accept your debug connections.
Configure File Mapping -- Next, set up a mapping between the location of the Zope installation on your Zope host and the point where it is accessible on your Wing host. For example, if your Zope host is 192.168.1.1 Zope is installed in /home/myuser/Zope on that machine, and /home/myuser is mounted on your Wing host as e:, you would add a Location Map preference setting that maps 192.168.1.1 to a list containing /home/myuser/Zope and e:/Zope. For more information on this, see Manually Configured File Location Maps and Location Map Examples in the Wing manual.
Set the Zope Host -- Go into Project Properties and set the Zope Host to match the host name used in configuring the File Location Map in the previous step. This is used to identify which host mapping should be applied to file names read from the zope.conf file.
Modify WingDBG Configuration -- When debugging remotely, the value given to WingDBG for the Wing Home Directory must be the location where Wing is installed on the Zope host (the default value will usually need to be changed).
Check Project Configuration -- Similarly, the paths identified in Project Properties should be those on the host where Wing IDE is running, not the paths on the Zope host.

Trouble Shooting Guide

You can obtain additional verbose output from Wing and the debug process as follows:

If Zope or Plone on Windows is yielding a Site Error page with a notFoundError when run under Wing's debugger, you may need to go into the Zope Management Interface and delete the access rule (... accessRule.py ...). Now, Zope/Plone runs on port 8080, does not alter the configuration of port 80, and will work properly with Wing's debug port (50080 by default). If the URL for your front page is http://localhost:8080/default/front-page, the Wing debug url will always be the same but with the different port: http://localhost:50080/default/front-page (Thanks for Joel Burton for this tip!)
Go into the Wing Debugging Service in the Zope Management Interface and set Log file under the Configure tab. Using <stdout> will cause logging information to be printed to the console from which Zope was started. Alternatively, set this to the full path of a log file. This file must already exist for logging to occur.
Restart Zope and Wing and try to initiate debug.
Inspect the contents of the log. If you are running Zope and Wing on two separate hosts, you should also inspect the ide.log file on the Wing host (located in the User Settings Directory). It contains additional logging information from the Wing process.

For additional help, send these errors logs to support at wingware.com.