<type>how-to</type>
<domain>install</domain>
<id>django</id>
<title>Using Wing with Django</title>
<date>$Date: 2006-12-28 17:21:05 -0500 (Thu, 28 Dec 2006) $</date>
<product>per+</product>
<summary>Learn how Wing can speed up developing and debugging Python code written for 
the Django web development framework.</summary>

.. note::
  **"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*

.. image:: /images/screenshots/wing7-screenshot-linen.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing <https://wingware.com/>`__ is a Python IDE that can be used to develop, test, and
debug Python code written for the `Django <https://www.djangoproject.com/>`__ 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 developers, and Wing Personal is a free
alternative with reduced feature set.

If you do not already have Wing installed, `download it now <https://wingware.com/downloads>`__.

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 <ref:howtos/quickstart>`__.

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 <script:about-application>`__ box. For detailed
information on writing extensions for Wing, see `Scripting and Extending Wing
<ref:scripting/index>`__.

Remote Development
------------------

Wing Pro can work with Django running on a remote host. See `Remote Python Development
<ref:howtos/remote-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 <script:about-application>`__ 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 <ref:howtos/debugging-web-remote>`__.

Next, place the following code into files you wish to debug::
  
  import wingdbstub
  
Then make sure that the `Debugger > Listening > Accept Debug Connections
<script:show_preferences_gui#prefname="debug.passive-listen">`__ 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:

(1) 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``.
    
(2) Turn on `Enable Django Template Debugging
    <script:view_project_properties#highlighted_attrib="proj.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
<script:show_preferences_gui(prefname="debug.exception-mode")>`__ 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:
  
* `Django home page <https://www.djangoproject.com/>`__ provides downloads and 
  documentation.

* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing's features.

* `Wing Reference Manual <ref:manual>`__ documents Wing in detail.

* `Remote Web Development <ref:howtos/debugging-web-remote>`__ describes how to set up
  development to a remote host, VM, or container.
