Substrate / Exogorth =========

This is a fork of the original PyPy artifact known as Substrate which appears to be abandoned. This is currently a superset of that codebase. The most interesting additions have been in the management commands around snapdeploy which is a version / delivery pipeline based on common hg and git supported deployment ideas.

Substrate / Exogorth 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 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.

• Documentation
• PyPI Package
• Source Code Repository

If you are making changes or additions to substrate proper, this is right repo to clone and test your changes on. You make changes here locally, install the new version of substrate on your local and test it. Then issue a PR.

If you make changes to anything in the exogorth packages (agar or restler) make those changes in those respective repos first, THEN hoist that work here running the update_agar.py and update_restler.py scripts accordingly. Make sure agar and restler repos are on the same level as this repo is for it to work properly. You will need to issue separate PRs for each repo, obviously.

To install substrate, clone this repo and run

$ sudo python ./setup.py install

Or use git+git and pip;

$ sudo -H pip install --upgrade git+git://github.com/agostodev/substrate.git#egg=substrate

To create a new application, run:

$ substrate new your-app-id

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.

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.

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.

$ ./manage.py test

Runs your application's tests. Any additional parameters are passed to the unitetest2 discover command

$./manage.py pytest

Runs your tests using the py.test runner. Any additional parameters are passed to the underlying runner

$./manage.py snapdeploy

Tries to deploy you app and modules to Google AppEngine. Relies on your local git or hg repo to conduct a deploy. Creates a version with the SHA-1 of the current repo / branch in the cloud and updates a snapdeploy.yaml file to commit. Very useful for deploying to multiple app ids and modules with consistent codebases. Supports most options you can pass to appcfg.py

:

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

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

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/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.

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