Substrate

Substrate is a base application and set of libraries for making
Google App Engine python development easier. It includes a base app with management
script, testing already set up, a set of common helper functions
(agar), and a serialization library (restler). It also comes with
common libraries like webapp2 and pytz ready to go.

Substrate is based on best practices for Google App Engine python learned in
developing several real-world applications with many users.

We are tired of seeing App Engine frameworks languish unsupported. For
that reason, Substrate is NOT a framework. It is a base
application with a set of libraries and helpers. No more, no less.

Creating a new application

This will create a new directory your-app-id and unpack the substrate
application libraries in it. The application name in app.yaml will be
set to your-app-id.

Or, if you find installing a script to do this for you tedious, you
can clone the substrate repository and copy the app directory to
create your application.

Upgrading an existing application

If you have an existing application, you can upgrade it to the latest
substrate code by updating the substrate package (see Installation) and then running:

$ substrate update ~/development/your-app-id

where ~/development/your-app-id is the application directory
(the one containing your app.yaml file) to upgrade.
(For example, you could run this in the current directory with .)

This command will NOT touch any of your application's files. Only
"substrate files" in the local/substrate and lib/substrate directories plus
manage.py and env_setup.py in the application directory will be
overwritten. You can add new files to local/usr and lib/usr, but do not
edit existing "substrate files" or your changes will be lost when upgrading.

Management Console

manage.py is a management console for your app. It can invoke several commands.

$ ./manage.py shell

Runs a shell against your local application (uses iPython if available).

$ ./manage.py rshell

Runs a remote shell against your application on Google App
Engine. To specify a different application ID than what is in your
app.yaml, use -A. If your remote API endpoint is not at
the default location, you can pass the path as an argument.

Adding Your Own Commands

manage.py will add .py files in the
local/usr/manage/substrate_manage_usr/commands directory as
commands.

Adding New Libraries to Your App

Substrate stores its libraries in lib/substrate and
local/substrate/lib (for libraries that should not be deployed to
Google App Engine). Do not add new libraries to these directories as
they are removed and re-copied on upgrade.

User libraries can be placed in lib/usr and
local/usr/lib. These paths are added to sys.path by
env_setup.setup

Testing

As noted above, manage.py has a test command. This runs all
the tests in the tests directory of your application using
unittest2. Included with the Substrate base app is a simple "hello
world" test that you can run to verify your installation. It is
located in tests/handlers/test_main.py.

Substrate includes test helpers located in the agar.test
package. agar.test uses google.appengine.ext.testbed to set up your
Google App Engine environment fresh before each test run. It is mostly
API compatable with the old gaetestbed project, plus new additions.

License

Substrate is mostly a packaging of other libraries, which have their
own licenses. Original code in Substrate is under the MIT license.