Using Wing with Django

Index of All Documentation » How-Tos » How-Tos for Web Development »


"Wing is really the standard by which I judge other IDEs. It opens, it works, and does everything it can do to stay out of my way so I can be productive. And its remote debugging, which I use when I'm debugging Django uWSGI processes, makes it a rock star!" -- Andrew M
Wing Pro Screenshot

Wing is a Python IDE that can be used to develop, test, and debug Python code written for the Django web development framework. The debugger works with Django's auto-reload feature and can step through and debug Python code and Django templates. Wing Pro also automates some aspects of the creation and management of Django projects and applications.

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 Django. To get started using Wing as your Python IDE, please refer to the tutorial in Wing's Help menu or read the Quickstart Guide.

Automated Configuration

The fastest way to get started working with a local installion of Django is to use Wing Pro's Django extensions. Skip ahead to the Manual Configuration section below if you have Wing Personal or if you need to work with Django running on a remote host.

Existing Django Project

To set up a Wing Pro project for an existing Django project, create a new project from the Project menu using project type Django. You will be prompted to enter the full path to the Python executable used for Django and the directory for your existing Django project, where your manage.py is located.

Once the project is created, this will display a dialog that confirms the configuration, with a detailed list of the settings that were made.

Now you should be able to start Django in Wing's debugger, set breakpoints in Python code and Django templates, and reach those breakpoints in response to a browser page load.

In some cases, the project creation process may prompt you to take additional steps manually:

  • If django-admin.py could not be found from the specified Python Executable then you will be prompted to change this value in Project Properties, from the Project menu. Wing looks for django-admin.py in the same directory as the Python executable.
  • If settings is a package in your project (instead of a settings.py file), you will need to manually enable template debugging in Django. This is done by setting debug to True under OPTIONS in the TEMPLATES section of your settings.py or settings package. If you are using Django 1.8 or earlier, instead set TEMPLATE_DEBUG to True.

New Django Project

If you are starting a new Django project at the same time as you are setting up your Wing project:

  • Select Start Django Project from the Extensions sub-menu of the Project menu, fill in the requested values, and press OK.
  • Wing will display a confirmation dialog, with a detailed list of actions taken. This may include a command that needs to be run manually to set up the superuser account for your new Django project. If so, copy and paste to run it in a command shell.
  • Finally, press Create Wing Project to create and configure a new Wing project for the new Django project. This confirms the project configuration, as described above for existing Django projects.

Automated Django Tasks

The Django menu, shown in Wing when the current project is configured for Django, contains items for common tasks such as creating a new app, generating SQL for a selected app, migrating an app or database, running validation checks or unit tests, and restarting the integrated Python Shell with the Django environment.

Wing's Django extensions are open source and can be found in scripts/django.py in the install directory listed in Wing's About box. For detailed information on writing extensions for Wing, see Scripting and Extending Wing.

Remote Development

Wing Pro can work with Django running on a remote host. See Remote Python Development for instructions on setting up remote access. Then use the following manual configuration instructions. You'll be able to use either of the described methods for debugging.

Manual Configuration

This section describes manual configuration of Wing projects for use with Django. Manual configuration is necessary when Django is running on a remote host or when using Wing Personal. If you are using Wing Pro with a local installation of Django, see Automated Configuration above instead.

Configuring the Project

To get started, create a new project from the Project menu using the Generic Python project type for a local installation and Connect to Remote Host via SSH for a remote installation of Django. Set the Python Executable to the full path of the Python used for Django. This path can be found by running Python outside of Wing and typing the following interactively:

import sys
sys.executable

Then add your project files with Add Existing Directory in the Project menu.

You may also need to set the DJANGO_SITENAME and DJANGO_SETTINGS_MODULE environment variables and add the project directory and its parent directory to the Python Path under Environment tab in Project Properties, from the Project menu.

In Django 1.7 and later, set PYTHONSTARTUP_CODE in the Environment in Project Properties to import django; django.setup() so Django will be initialized in Wing's integrated Python Shell.

For unit testing in Wing Pro, set the Default Test Framework under the Testing tab of Project Properties to Django Tests and then add manage.py as a test file with Add Single File in the Testing menu.

Configuring the Debugger

There are two ways to debug Django code: Either (1) configure Django so it can be launched by Wing's debugger, or (2) cause Django to attach to Wing from the outside as code that you wish to debug is executed.

Launching from Wing

To start Django from Wing, right-click on manage.py in the Project tool and select Set as Main Entry Point. This causes execution and debugging to start here.

Next, configure the command line arguments sent to manage.py by opening the file in the editor or finding it in the Project tool and right-clicking to select File Properties. Then set the run arguments under the Debug/Execute tab to your desired launch arguments. For example:

runserver 8000

Other command line arguments can be added here as necessary for your application.

If you are using Wing Pro, enable Debug Child Processes under the Debug/Execute tab of Project Properties. This allows Django to load changes you make to code without restarting.

Child process debugging is not available in Wing Personal, so you instead need to add --noreload to the run arguments for manage.py:

runserver --noreload 8000

In this case, you will need to restart Django each time you make a change, or use the debugging method described below.

Launching Outside of Wing

Another method of debugging Django is to use wingdbstub.py to initiate debugging after Django is started from outside of Wing. This method can be used to debug a Django instance remotely or to enable debugging reloaded Django processes with Wing Personal.

This is done by placing a copy of wingdbstub.py into the top of the Django directory, where manage.py is located. This file can be found in the install directory listed in Wing's About box. Make sure that WINGHOME in your copy of wingdbstub.py is set to the full path of the install directory. On OS X, use the full path of Wing's .app folder (without the Contents/Resources part).

If you are developing on a remote host, instead use the copy of wingdbstub.py that is located in the remote agent's installation directory, on the remote host. This is preconfigured to work correctly with your remote project, as described in Remote Web Development.

Next, place the following code into files you wish to debug:

import wingdbstub

Then make sure that the Debugger > Listening > Accept Debug Connections preference is enabled in Wing and start Django. The Django process should connect to Wing and stop at any breakpoints reached after wingdbstub has been imported.

When code is changed, just save it and Django will restart. The debugger should reconnect to Wing once you request a page load in your browser that executes one of your import wingdbstub statements.

Debugging Django Templates

To enable debugging of Django templates, you need to:

  • Enable template debug in Django. This is done by setting debug to True under OPTIONS in the TEMPLATES section of your settings.py or settings package. If you are using Django 1.8 or earlier, instead set TEMPLATE_DEBUG to True.
  • Turn on Enable Django Template Debugging under the Options tab of Project Properties, from the Project menu. When you change this property, you will need to restart your Django debug process, if one is already running.

Usage Tips

Debugging Exceptions

Django contains a catch-all handler that displays exception information to the browser. When debugging with Wing, it is useful to also propagate these exceptions to the IDE. This can be done with a monkey patch as follows (for example, in local_settings.py on your development system):

import os
import sys

import django.views.debug

def wing_debug_hook(*args, **kwargs):
    if __debug__ and 'WINGDB_ACTIVE' in os.environ:
        exc_type, exc_value, traceback = sys.exc_info()
        sys.excepthook(exc_type, exc_value, traceback)
    return old_technical_500_response(*args, **kwargs)

old_technical_500_response = django.views.debug.technical_500_response
django.views.debug.technical_500_response = wing_debug_hook

The monkey patch only activates if Wing's debugger is active and assumes that the Debugger > Exceptions > Report Exceptions preference is left set to its default value When Printed.

Template Debugging

If you enabled Django template debugging as described above, you should be able to set breakpoints in any file that contains {%%} or {{}} tags, and the debugger will stop at them.

Note that stepping is tag by tag and not line by line, but breakpoints are limited to being set for a particular line and thus match all tags on that line.

When template debugging is enabled, you won't be able to step into Django internals during a template invocaton. To work around that, temporarily uncheck Enable Django Template Debugging under the Extension tab of Project Properties in Wing, and then restart your debug process.

Better Auto-Completion

Wing provides auto-completion on Python code and Django templates. The completion information is based on static analysis of the files and runtime introspection if the debugger is active and paused. It is often more informative to work with the debugger paused or at a breakpoint, particularly in Django templates where static analysis is not as effective as it is in Python code.

Running Unit Tests

Wing Pro includes a unit testing integration capable of running and debugging Django unit tests. For Django projects, the Default Testing Framework under the Testing tab of Project Properties is set to Django Tests so that the Testing tool runs manage.py test and displays the results. Individual tests can be run or debugged by selecting them and pressing Run Tests or Debug Tests in the Testing tool.

If unit tests need to be run with different settings, the environment variable WING_TEST_DJANGO_SETTINGS_MODULE can be set to replace DJANGO_SETTINGS_MODULE when unit tests are run.

Django with Buildout

When using Django with buildout, Wing won't auto-detect your project as a Django project because the manage.py file is instead named bin/django. To get it working, copy bin/django to manage.py in the same directory as settings.py or the settings package.

Related Documents

For more information see: