Home » Support » 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 IDE is an integrated development environment that can be used to write, test, and debug Python code that is written for Django, a powerful web development framework. Wing provides auto-completion, call tips, goto-definition, find uses, refactoring, a powerful debugger, unit testing, and many other features that help you write, navigate, and understand Python code.

Wing IDE can also be used to step through and debug Django templates, and it includes Django-specific plugin functionality to make it easier to create Django projects and apps, set up Wing projects for use with Django, and manage routine tasks. The debugger can be configured to launch Django from the IDE and to reinitiate automatically when Django reload occurs.

For more information on Wing IDE see the product overview. If you do not already have Wing IDE installed, download a free trial now. To get started using Wing, refer to the tutorial in the Help menu in Wing and/or the Wing IDE Quickstart Guide.

Installing Django

The Django website provides complete instructions for installing Django.

Quick Start with Wing IDE Professional

If you have Wing IDE Professional and Django 1.4 or later, the fastest way to get started using Wing IDE with Django is to use the provided Django extensions. If you have Wing IDE Personal, skip ahead to the Manual Configuration section below.

Existing Django Project

To set up a Wing IDE Professional project for an existing Django project:

  • Create a new project from the Project menu,
  • Add the Django site directory to the Wing project (so that manage.py and settings.py (or settings package) are both in the project),
  • Wait until the Django menu appears in the menu bar, and
  • Select the Configure Project for Django item from that menu.

This sets the Python Executable in Project Properties (if it can be located), sets up manage.py runserver --noreload 8080 as the main debug file, adds DJANGO_SITENAME and DJANGO_SETTINGS_MODULE to the environment in Project Properties, adds the site directory to the Python Path in the Wing project, ensures Django Template Debugging in Project Properties is enabled, turns on TEMPLATE_DEBUG in your site's settings.py file (debugging templates will not work without this), and sets the Default Test Framework in the Testing tab of Project Properties so that Wing's Testing tool will invoke manage.py test.

If settings is a package in your project (instead of a settings.py file), you will need to set TEMPLATE_DEBUG=True manually in the appropriate place(s) in your settings.

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

New Django Project

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

  • Select Start Django Project from the Extensions sub-menu of the Project menu.
  • You will be prompted for the location of django_admin.py, location to place the new project, and the site name in the same entry area. Defaults for these values are based on the current project contents, if a Django project is already open.
  • Press Enter and Wing will set up a new Django project and your Wing IDE project at the same time.

This runs django_admin.py startproject <sitename>, sets up settings.py to use sqlite3 default database engine, adds django.contrib.admin to INSTALLED_APPS, runs syncdb, and copies the default admin template base_site.html from your Django installation into your site's templates/admin directory.

Note that on Windows you will see an error that the superuser account could not be set up. The error includes the command that needs to be run interactively. To complete project creation, copy/paste this into a command console.

When project setup is completed, the command offers to creates a new Wing IDE project, add the files, and configure the project for use with Django as described in the Existing Django Project sub-section above.

Notes on Debugger Configuration

(1) 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 systems):

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 Report Exceptions preference is set to When Printed.

(2) Debugging with Reload Enabled

The default configuration of the debugger launches Django from Wing IDE and disables auto-reload, so the restart button in Wing must be pressed before changes take effect in the debug process. To launch from outside the IDE and to handle auto-reload automatically see the Manual Configuration section below.

Django-specific Actions

The Django menu that auto-activates for Django projects also contains special actions for starting a new Django app (this creates the app and adds it to INSTALLED_APPS in settings.py, running sync db, generating SQL for a selected app, and running validation checks. This menu also provides convenient access to this How-To. If settings is a package in your project (instead of a settings.py file), you will need to manually add the new Django app to INSTALLED_APPS in the appropriate place(s) in your settings.

This functionality is implemented as an open source plugin that can be found in scripts/django.py in the install directory listed in Wing's About box. This code can be user-modified by working from the existing functionality as examples. For detailed information on writing extensions for Wing IDE, see the Scripting and Extending Wing IDE chapter.

Debugging Django Templates

The above-described project setup scripts enable template debugging automatically. If you configured your project manually, you will need to take the following two steps to enable template debugging:

  • Set TEMPLATE_DEBUG to True in your Django application's settings.py file or settings package,
  • Be sure that Wing IDE's Enable Django Template Debugging setting in your project's properties is enabled. When you change this property, you will need to restart your Django debug process if one is already running.

Once this is done, you should be able to set breakpoints in any file that contains {%%} or {{}} tags, and the debugger will stop at them.

When debugging Django templates is enabled, Wing will replace the Python stack frames within the template invocation with frames for the template files, and the locals shown in the Stack Data tool will be extracted from the template's runtime context. When working in a template stack frame, the Debug Probe, Watch, and other tools will operate in the environment that is displayed in the Stack Data tool.

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.

Stepping in the debugger while a template invocation is active will be limited to templates and any user code or code within the contrib area of your Django installation. If you need to step into Django internals during a template invocation, you will need to disable Django template debugging in your project properties, set a breakpoint at the relevant place in Django, and restart your debug process.

Notes on Auto-Completion

Wing provides auto-completion on Python code and Django templates. The completion information is based on static analysis of the files unless the debugger is active and paused and the template or Python code being edited are on the stack. In that case, Wing sources the information shown in the auto-completer and Source Assistant from live runtime state. As a result, it is often more informative to work with the debugger a breakpoint, particularly in Django templates where static analysis is not as effective as it is in Python code.

Running Unit Tests

In Wing IDE Professional, the Default Testing Framework under the Testing tab of Project Properties can be set to Django Tests to cause the Testing tool in Wing to run manage.py test and display the results. Particular tests can be debugged by selecting them and using Debug in the Testing menu (or right-clicking on them).

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.

Manual Configuration

This section describes manual configuration of Wing IDE projects for use with Django. If you are using Wing IDE Professional, see the above Quick Start for Wing IDE Professional.

Configuring the Project

To get started, create a new project from the Project menu, add your files, and determine if the correct Python is being found by displaying the Python Shell tool in Wing. If the wrong Python is being used, alter the Python Executable in Project Properties (in the Project menu) and restart the shell from its Options menu.

You may also want to set the DJANGO_SITENAME and DJANGO_SETTINGS_MODULE environment variables in Project Properties.

Configuring the Debugger

By default, Django runs in an environment that spawns and automatically re-launches a sub-process for servicing web requests. This is used to automatically restart the server if for some reason it crashes. However, this does not work with Wing's debugger if you launch Django from Wing, since the debugger has no way to cause the sub-process to be debugged when it is started by the main process.

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

Launching from Wing

When Django is launched from Wing, it must be configured to avoid auto-reload and other options that break the debugger.

Newer versions of Django include a --noreload option that you can pass to the manage.py or django-admin.py scripts to turn off the auto restart feature of Django.

The typical way to do all this is to set the manage.py file as the primary debug file in Wing and give it the following Run Arguments via the Debug properties tab in the File Properties dialog:

runserver --noreload

Other options can be added here as necessary for your application.

Some older versions of Django may also require adding --settings=devsettings to the arguments for runserver, in order for debugging to work. If Wing is not be able to stop on any breakpoints, try adding this.

In much older versions of Django, the --noreload option does not exist. The only way to solve the problem there is to make a modification to the code to prevent launching of a sub-process, or to use the alternative method described below.

Debugging with Auto-reload

Another method of debugging Django is to use wingdbstub.py to initiate debugging when Django is started from outside of Wing IDE. This will allow Django to restart automatically after code changes and to automatically reconnect the debugger to Wing IDE as needed.

This is done by placing a copy of wingdbstub.py, which is located in the install directory listed in Wing's About box, into the top of the Django directory, where manage.py is located. Make sure that WINGHOME is set inside wingdbstub.py; if not, set it to the location of your Wing IDE installation (on OS X, to the name of Wing's .app folder). This allows the debug process to find the debugger implementation.

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

import wingdbstub

Then make sure that the Accept Debug Connections preference is enabled in Wing and start Django. The Django process should connect to Wing IDE and stop at any breakpoints set after the import wingdbstub.

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

Related Documents

Wing IDE provides many other options and tools. For more information:

« 2. How-Tos for Web DevelopmentTable of Contents2.1. Using Wing IDE with web2py »

Using Wing IDE with Django