.. _app_engine: App Engine Support =================== Pecan runs smoothly in Google's App Engine. There is **no** hacking/patching or weird changes that you need to make to work with Pecan. However, since App Engine has certain restrictions you may want to be aware on how to set it up correctly. .. note:: We do not discuss here how to get an App Engine environment here, nor App Engine specifics that are not related to Pecan. For more info on App Engine go to `their docs `_ Dependencies --------------- Pecan has a few dependencies and one of them is already supported by App Engine (WebOb) so no need to grab that. Just so you are aware, this is the list of things that you absolutely need to grab: * WebCore >= 1.0.0 * simplegeneric >= 0.7 * Paste >= 1.7.5.1 * PasteScript >= 1.7.3 * formencode >= 1.2.2 * WebTest >= 1.2.2 * WebError >= 0.10.3 These are optional, depending on the templating engine you want to use. However, depending on your choice, you might want to check that engine's dependencies as well. * Genshi >= 0.6 * Kajiki >= 0.3.1 * Mako >= 0.3 From this point forward, we will assume you are going to be using Mako (it is the recommended Pecan template engine), to avoid describing third party dependencies. Creating the project --------------------- Create a directory called ``pecan_gae`` and ``cd`` into it so we can start adding files. We go step by step into what needs to go there to get everything running properly. app.yaml ------------ To start off, you will need your ``app.yaml`` file set properly to map to Pecan. This is how that file should look like:: application: foo-bar version: 1 runtime: python api_version: 1 handlers: - url: /.* script: main.py Remember the application name will have to match your registered app name in App Engine. The file above maps everything to a ``main.py`` file that we will create next. This file will be the *root* of our project and will handle everything. main.py ------------ You can name this anything you want, but for consistency we are going with `main.py`. This file will handle all the incoming requests including static files for our Pecan application. This is how it should look:: from google.appengine.ext.webapp import util import sys if './lib' not in sys.path: sys.path.append('./lib') from pecan import Pecan, expose class RootController(object): @expose('kajiki:index.html') def index(self): return dict(name="Joe Wu Zap") def main(): application = Pecan(RootController(), template_path='templates') util.run_wsgi_app(application) if __name__ == '__main__': main() We are doing a few things here... first we are importing the ``util`` module from App Engine that will run our Pecan app, then we are importing ``sys`` because we need to add ``lib`` to our path. The ``lib`` directory is where all our dependencies (including Pecan) will live, so we need to make sure App Engine will see that as well as all our libraries within ``lib`` (it would not be enough to add a ``__init__.py`` file there). lib ----- Go ahead and create a ``lib`` directory inside of your ``pecan_gae`` directory application and add the requirements for Pecan there. Make sure you have a ``__init__.py`` file too. .. warning:: You should **not** run ``setup.py`` on any of the libraries. This prevents activating C extensions which are forbidden in App Engine. Copy the *actual* source for the libraries only. The ``lib`` directory should contain the source for all the dependencies we need. For our example, it should contain these libraries: * alacarte * formencode * mako * markupsafe * Paste * pecan * pygments * simplegeneric.py * simplejson * tempita * WebCore * WebTest * WebError Unfortunately, `weberror` needs `pkg_resources` which it can't find. The easy fix for this problem is to find `pkg_resources` in your own `site-packages` directory and copy it inside `weberror`. That is all you need to get this project started! .. note:: When grabing the source of the dependencies we mention, make sure you are actually grabing the module itself and not adding the top directory source (where setup.py lives). Also make sure you are **not** using egg files (App Engine doesn't work with them). templates ----------- The `templates` directory is where we will have all of our html templates for Pecan. If you don't have it already, go ahead and create it and add this html file to it and name it index.html:: Hello, ${name}!

Hello, ${name}!

Layout --------- This is how your layout (only showing directories) should look like:: pecan_gae ├── lib │   ├── alacarte │   │   ├── serialize │   │   └── template │   ├── formencode │   │   ├── javascript │   │   └── util │   ├── mako │   │   └── ext │   ├── markupSafe │   ├── paste │   │   ├── auth │   │   ├── cowbell │   │   ├── debug │   │   ├── evalexception │   │   │   └── media │   │   ├── exceptions │   │   └── util │   ├── pecan │   │   ├── commands │   │   └── templates │   │   └── project │   │   ├── +package+ │   │   │   ├── controllers │   │   │   ├── model │   │   │   └── templates │   │   └── public │   │   ├── css │   │   └── javascript │   ├── pygments │   │   ├── filters │   │   ├── formatters │   │   ├── lexers │   │   └── styles │   ├── simplejson │   │   └── tests │   ├── tempita │   ├── web │   │   ├── app │   │   ├── auth │   │   ├── commands │   │   ├── core │   │   │   └── dialects │   │   ├── db │   │   ├── extras │   │   └── utils │   ├── webTest │   └── weberror │   ├── eval-media │   ├── exceptions │   └── util └── templates Trying it out ------------------------- Now everything should be ready to start serving, so go ahead and run the development server:: $ ./dev_appserver.py pecan_gae INFO 2010-10-10 12:44:29,476 dev_appserver_main.py:431] Running application pecan-gae on port 8080: http://localhost:8080 If you go to your browser and hit ``localhost:8080`` you should see something like this:: Hello, Joe Wu Zap! This is the most basic example for App Engine, you can start adding more controllers to handle a bigger application and connect everything together.