WebStack supports Django in the sense that WebStack applications can be
deployed within Django instances according to the guidelines described in the
Django documentation plus a few caveats. Here is the basic process:

 1. Create a Django instance or find an existing instance to use.
 2. Create or find an application where WebStack resources and applications
    shall be deployed.
 3. Add URL mappings to the instance's urls.py file - see below for a
    description of how this should be done.
 4. Add WebStack handlers to the application directory.
 5. Add the application to the INSTALLED_APPS definition in the settings.py
    file.
 6. Add the APPEND_SLASH setting to the settings.py file.
 7. Configure Django in mod_python.

Create a Django instance
------------------------

For example:

django-admin.py startproject djangoinstance

Create an application
---------------------

For example:

cd djangoinstance
mkdir webstack

Add URL mappings
----------------

The docs/Django/urls.py file contains definitions for the example applications
based on a Django instance called "djangoinstance" (in a directory of that
name) and the "webstack" application (in a directory of that name within the
instance). The urls.py file employs URL patterns to direct requests to each of
the examples.

Consider the auth example - the following pattern is employed to detect
requests intended for it:

^django/webstack/auth(?P<vp>/.*)?

Here, the example will be accessible via a URL like this:

http://localhost/django/webstack/auth

Additional path information is captured by a special named regular expression
group which is used within the WebStack adapter.

WebStack handlers and adapters
------------------------------

The handlers from examples/Django should be copied into or otherwise linked to
from the "webstack" application directory within the Django instance. Each
handler should contain a function, produced by calling the special deploy
function from the Django adapter, with a name as stated in the urls.py file.

Consider the auth example - the following path to the resource is stated:

djangoinstance.webstack.authapp.auth

Here, within the instance and application, the "authapp" handler (provided by
the authapp.py from examples/Django) must contain a function called "auth".

Add the application to the settings
-----------------------------------

For example:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'djangoinstance.webstack', # Application added here!
)

Prevent Django from adding slash characters:

APPEND_SLASH = 0

Django and mod_python
---------------------

For example:

<Location "/django/">
    SetHandler python-program
    PythonHandler django.core.handlers.modpython
    SetEnv DJANGO_SETTINGS_MODULE djangoinstance.settings
    PythonDebug On
    PythonPath "['/home/paulb/Software/Python', '/home/paulb/Software/Python/WebStack', '/home/paulb/Software/Python/WebStack/examples/Common'] + sys.path"
</Location>

Django and authentication
-------------------------

Whilst Django has its own authentication scheme, WebStack preserves the
standard HTTP notion of a user as provided via the HTTP authentication
mechanisms. Thus, the get_user method on the Transaction object does not
currently access Django's underlying authentication machinery.
