GOOGLE APP ENGINE HELPER FOR DJANGO
===================================

This package provides a helper that eases the process of developing a Django
project to run on the Google App Engine. The helper is structured as a Django
application that should be installed inside your project. See below for
detailed usage instructions.

The helper provides the following functionality:

  * The ability to use most manage.py commands
    - Additional manage.py commands (update, rollback, and vacuum_indexes) that
      operate identically to the appcfg.py equivalents.
  * A BaseModel class that appears the same as the standard Django Model class.
  * The ability to serialize and deserialize model instances to JSON, YAML and
    XML.
  * Access to Django's test framework with a test datastore and support for
    fixtures.
  * The ability to send email via the App Engine mail API using the standard
    Django mail functions.
  * An App Engine compatible implementation of the Django authentication
    framework. Only users are supported at this time. Group and Permission
    support is not implemented.
  * Support for the Django memcache cache backend module.
  * Support for the db and cache session backed modules.

The helper is provided in the context of a blank Django project, very
similar to what would be provided by the django-admin.py startproject command.
This project contains minor customisations to manage.py and settings.py that
demonstrate how to integrate the helper with a Django project.

To use the helper you have two choices:

1) Copy the entire project provided with the helper and modify it to bootstrap
   your project.
2) Copy the appengine_django application into your existing project and modify
   the settings appropriately.

Instructions for both cases are provided below.


Obtaining the helper
--------------------

You can download the latest released version of the helper from the Google Code
project at: http://code.google.com/p/google-app-engine-django

The helper will be unzipped into a directory named appengine_helper_for_django.

Alternatively you can check out the latest version of the helper directly from
the SVN repository with the following command:

svn co http://google-app-engine-django.googlecode.com/svn/trunk/ \
  appengine_helper_for_django


Required Software
-----------------

You will need the Google App Engine SDK and its dependencies installed on your
computer. Additionally if you are developing on a Windows machine you will need
to install the Python for Windows extensions from
http://sourceforge.net/projects/pywin32/

This version of the helper requires Django 1.0beta_1 or greater. If you would
prefer to use the stable version of Django (0.96) that is bundled with the App
Engine SDK then you can download revision 53 or earlier of the helper from the
address in the previous section. You must place Django in a directory named
django/ instead your project, or provide a django.zip file containing the
zipped Django source. See below for details.


Using the helper to bootstrap a new project
-------------------------------------------

1) Copy the appengine_helper_for_django directory to a new location named after
   your project

2) Edit the application line in app.yaml to match the name you registered your
   application under in the Admin Console.

3) If you have installed the Google App Engine SDK using the Windows or MacOS
   installers provided by Google you may skip this step.

   Create a symlink from the location of the extracted SDK zipfile to the
   '.google_appengine' directory inside your project. E.g:

   ln -s /home/me/google_appengine /home/me/myproject/.google_appengine

   If you like to stay up to date see the 'SDK via SVN' section below for an
   alternative setup.

4) Download and copy Django into the django/ subdirectory of your project.
   Alternatively you can create a zipfile of the Django code and place it at
   django.zip inside your project. E.g.

   /home/me/myproject/django          (directory method)
   /home/me/myproject/django.zip      (zipfile method)

5) Run manage.py to start a new application for your code:

   python manage.py startapp myapplication

6) Add your code!


Installing the helper into an existing project
----------------------------------------------

1) Copy the appengine_django application from within the helper into your
   project.

2) Copy app.yaml and main.py from within the helper into your project.

3) Edit the application line in app.yaml to match the name you registered your
   application under in the Admin Console.

4) Add the following two lines to the top of manage.py::

       from appengine_django import InstallAppengineHelperForDjango
       InstallAppengineHelperForDjango()

5) If you have installed the Google App Engine SDK using the Windows or MacOS
   installers provided by Google you may skip this step.

   Create a symlink from the location of the extracted SDK zipfile to the
   '.google_appengine' directory inside your project. E.g:

   ln -s /home/me/google_appengine /home/me/myproject/.google_appengine

   If you like to stay up to date see the 'SDK via SVN' section below for an
   alternative setup.

6) Ensure Django is available within your project as described in Step 4 of the
   instructions for bootstrapping new porjects above.

7) Remove incompatible settings from your settings.py file.

   The helper can warn you about some settings that it knows to be
   incompatible, you can see these warnings by running::

       python manage.py diffsettings

   For the rest you'll just have to experiment by trial and error. The main
   problem here is usually loading middleware that attempts to import modules
   that are banned by the appserver.

8) Port your models and code over to the appengine_django.model.BaseModel
   class.


SDK via SVN
-----------

If you are using SVN to manage your project and you would like to keep up to
date with the latest SDK without having to download and install it regularly
you can use an svn:external to include the SDK in our project.

Once you have commited the basic structure of your project to your repository
change to the base directory and add the following line to the svn:externals
property using svn propset or svn propedit.

.google_appengine http://googleappengine.googlecode.com/svn/trunk/python/

Then run svn update and a copy of the SDK will be installed into the
'.google_appengine' subdirectory. This copy of the SDK will be updated with the
latest changes from the Google Code repository every time you run svn update.


Contributing to the helper
--------------------------

We would be happy to consider any additions or bugfixes that you would like to
add to the helper. Please add them as a patch, in unified diff format to the
Issue Tracker at: http://code.google.com/p/google-app-engine-django/issues/list

Before we can accept your code you will need to have signed the Google
Contributer License. You can find this at:

http://code.google.com/legal/individual-cla-v1.0.html
or
http://code.google.com/legal/corporate-cla-v1.0.html

If you are an Individual contributor you will be able to electronically sign
and submit the form at the URL above. Please ensure that you use the same email
address to submit your patch as you used to sign the CLA.


Reporting Bugs and Requesting Features
--------------------------------------

Please see the KNOWN_ISSUES file and the existing list of issues at
http://code.google.com/p/google-app-engine-django/issues to see if your problem
has already been reported.

If you find a bug or would like to request a feature you may do so at the
Google Code issue tracker for this project:

http://code.google.com/p/google-app-engine-django/issues/entry