Using the webapp2 Framework

The CGI standard is simple, but it would be cumbersome to write all of the code that uses it by hand. Web application frameworks handle these details for you, so you can focus your development efforts on your application’s features. Google App Engine supports any framework written in pure Python that speaks CGI (and any WSGI-compliant framework using a CGI adaptor).

Hello, webapp2!

A webapp2 application has three parts:

  • One or more RequestHandler classes that process requests and build responses.
  • A WSGIApplication instance that routes incoming requests to handlers based on the URL.
  • A main routine that runs the WSGIApplication using a CGI adaptor.

Let’s rewrite our friendly greeting as a webapp2 application. Edit helloworld/helloworld.py and replace its contents with the following:

import webapp2

class MainPage(webapp2.RequestHandler):
    def get(self):
        self.response.headers['Content-Type'] = 'text/plain'
        self.response.out.write('Hello, webapp2 World!')

application = webapp2.WSGIApplication([
    ('/', MainPage)
], debug=True)

Also edit app.yaml and replace its contents with the following:

application: helloworld
version: 1
runtime: python27
api_version: 1
threadsafe: true

handlers:
- url: /.*
  script: helloworld.app

Reload http://localhost:8080/ in your browser to see the new version in action (if you stopped your web server, restart it by running the command described in “Hello, World!”).

What webapp2 Does

This code defines one request handler, MainPage, mapped to the root URL (/). When webapp2 receives an HTTP GET request to the URL /, it instantiates the MainPage class and calls the instance’s get method. Inside the method, information about the request is available using self.request. Typically, the method sets properties on self.response to prepare the response, then exits. webapp2 sends a response based on the final state of the MainPage instance.

The application itself is represented by a webapp2.WSGIApplication instance. The parameter debug=true passed to its constructor tells webapp2 to print stack traces to the browser output if a handler encounters an error or raises an uncaught exception. You may wish to remove this option from the final version of your application.

The code application.run() runs the application in App Engine’s CGI environment. It uses a function provided by App Engine that is similar to the WSGI-to-CGI adaptor provided by the wsgiref module in the Python standard library, but includes a few additional features. For example, it can automatically detect whether the application is running in the development server or on App Engine, and display errors in the browser if it is running on the development server.

We’ll use a few more features of webapp2 later in this tutorial. For more information about webapp2, see the webapp2 reference.