Google App Engine (using buildout) and Pyramid

This is but one way to develop applications to run on Google's App Engine. This one uses buildout . For a different approach, you may want to look at Google App Engine Standard and Pyramid.

Install the pyramid_appengine scaffold

Let's take it step by step.

You can get pyramid_appengine from pypi via pip just as you typically would any other python package, however to reduce the chances of the system installed python packages intefering with tools you use for your own development you should install it in a local virtual environment

Creating a virtual environment

Update distribute

$ sudo pip install --upgrade distribute

Install virtualenv

$ sudo pip install virtualenv

create a virtual environment

$ virtualenv -p /usr/bin/python2.7 --no-site-packages --distribute myenv

install pyramid_appengine into your virtual environment

$ myenv/bin/pip install pyramid_appengine

Once successfully installed a new project template is available to use named "appengine_starter".

To get a list of all available templates.

$ myenv/bin/pcreate -l

Create the skeleton for your project

You create your project skeleton using the "appengine_starter" project scaffold just as you would using any other project scaffold.

$ myenv/bin/pcreate -t appengine_starter newproject

Once successfully ran, you will have a new buildout directory for your project. The app engine application source is located at newproject/src/newproject.

This buildout directory can be added to version control if you like, using any of the available version control tools available to you.

Bootstrap the buildout

Before you do anything with a new buildout directory you need to bootstrap it, which installs buildout locally and everything necessary to manage the project dependencies.

As with all buildouts, it can be bootstrapped running the following commands.

~/ $ cd newproject
~/newproject $ ../bin/python2.7 bootstrap.py

You typically only need to do this once to generate your buildout command. See the buildout documentation for more information.

Run buildout

As with all buildouts, after it has been bootstrapped, a "bin" directory is created with a new buildout command. This command is run to install things based on the newproject/buildout.cfg which you can edit to suit your needs.

~/newproject $ ./bin/buildout

In the case of this particular buildout, when run, it will take care of several things that you need to do....

  1. install the app engine SDK in parts/google_appengine more info
  2. Place tools from the appengine SDK in the buildout's "bin" directory.
  3. Download/install the dependencies for your project including pyramid and all it's dependencies not already provided by the app engine SDK. more info
  4. A directory structure appropriate for deploying to app engine at newproject/parts/newproject. more info
  5. Download/Install tools to support unit testing including pytest, and coverage.

Run your tests

Your project is configured to run all tests found in files that begin with "test_"(example: newproject/src/newproject/newproject/test_views.py).

~/newproject/ $ cd src/newproject
~/newproject/src/newproject/ $ ../../bin/python setup.py test

Your project incorporates the unit testing tools provided by the app engine SDK to setUp and tearDown the app engine environment for each of your tests. In addition to that, running the unit tests will keep your projects index.yaml up to date. As a result, maintaining a thorough test suite will be your best chance at insuring that your application is ready for deployment.

You can adjust how the app engine api's are initialized for your tests by editing newproject/src/newproject/newproject/conftest.py.

Run your application locally

You can run your application using the app engine SDK's Development Server

~/newproject/ $ ./bin/devappserver parts/newproject

Point your browser at http://localhost:8080 to see it working.

Deploy to App Engine

Note: Before you can upload any appengine application you must create an application ID for it.

To upload your application to app engine, run the following command. For more information see App Engine Documentation for appcfg

~/newproject/ $ ./bin/appcfg update parts/newproject -A newproject -V dev

Point your browser at http://dev.newproject.appspot.com to see it working.

The above command will most likely not work for you, it is just an example. the "-A" switch indicates an Application ID to deploy to and overrides the setting in the app.yaml, use the Application ID you created when you registered the application instead. The "-V" switch specifies the version and overrides the setting in your app.yaml.

You can set which version of your application handles requests by default in the admin console. However you can also specify a version of your application to hit in the URL like so...

http://<app-version>.<application-id>.appspot.com

This can come in pretty handy in a variety of scenarios that become obvious once you start managing the development of your application while supporting a current release.