1.. _tutorials.gettingstarted.usingwebapp2:
2
3Using the webapp2 Framework
4===========================
5The CGI standard is simple, but it would be cumbersome to write all of the
6code that uses it by hand. Web application frameworks handle these details
7for you, so you can focus your development efforts on your application's
8features. Google App Engine supports any framework written in pure Python
9that speaks CGI (and any
10`WSGI <http://www.python.org/dev/peps/pep-0333/>`_-compliant framework using a
11CGI adaptor). You can bundle a framework of your choosing with your application
12code by copying its code into your application directory.
13
14App Engine includes a simple web application framework of its own, called
15``webapp``. The ``webapp`` framework is already installed in the App Engine
16environment and in the SDK, and as ``webapp2`` is based on it, you only need
17to bundle a single file with your application code to use it. We will use
18``webapp2`` for the rest of this tutorial.
19
20Follow these steps to bundle the ``webapp2`` framework with your application:
21
22- Create a file ``webapp2.py`` inside your application directory. Paste the
23  contents from `webapp2.py <http://code.google.com/p/webapp-improved/source/browse/webapp2.py>`_
24  inside it.
25- There's no second step. You can start using webapp2 right now.
26
27
28Hello, webapp2!
29---------------
30A ``webapp2`` application has three parts:
31
32- One or more ``RequestHandler`` classes that process requests and build
33  responses.
34- A ``WSGIApplication`` instance that routes incoming requests to handlers
35  based on the URL.
36- A main routine that runs the ``WSGIApplication`` using a CGI adaptor.
37
38Let's rewrite our friendly greeting as a ``webapp2`` application. Edit
39``helloworld/helloworld.py`` and replace its contents with the following::
40
41    import webapp2
42
43    class MainPage(webapp2.RequestHandler):
44        def get(self):
45            self.response.headers['Content-Type'] = 'text/plain'
46            self.response.out.write('Hello, webapp2 World!')
47
48    application = webapp2.WSGIApplication([
49        ('/', MainPage)
50    ], debug=True)
51
52Also edit ``app.yaml`` and replace its contents with the following:
53
54.. code-block:: yaml
55
56   application: helloworld
57   version: 1
58   runtime: python27
59   api_version: 1
60   threadsafe: true
61
62   handlers:
63   - url: /.*
64     script: helloworld.app
65
66Reload `http://localhost:8080/ <http://localhost:8080/>`_ in your browser to
67see the new version in action (if you stopped your web server, restart it by
68running the command described in ":ref:`tutorials.gettingstarted.helloworld`").
69
70
71What webapp2 Does
72-----------------
73This code defines one request handler, ``MainPage``, mapped to the root URL
74(``/``). When ``webapp2`` receives an HTTP GET request to the URL ``/``, it
75instantiates the ``MainPage`` class and calls the instance's ``get`` method.
76Inside the method, information about the request is available using
77``self.request``. Typically, the method sets properties on ``self.response``
78to prepare the response, then exits. ``webapp2`` sends a response based on
79the final state of the ``MainPage`` instance.
80
81The application itself is represented by a ``webapp2.WSGIApplication``
82instance. The parameter ``debug=true`` passed to its constructor tells
83``webapp2`` to print stack traces to the browser output if a handler
84encounters an error or raises an uncaught exception. You may wish to remove
85this option from the final version of your application.
86
87The code ``application.run()`` runs the application in App Engine's CGI
88environment. It uses a function provided by App Engine that is similar to the
89WSGI-to-CGI adaptor provided by the ``wsgiref`` module in the Python standard
90library, but includes a few additional features. For example, it can
91automatically detect whether the application is running in the development
92server or on App Engine, and display errors in the browser if it is running
93on the development server.
94
95We'll use a few more features of ``webapp2`` later in this tutorial. For more
96information about ``webapp2``, see the webapp2 reference.
97
98
99Next...
100-------
101Frameworks make web application development easier, faster and less error
102prone. webapp2 is just one of many such frameworks available for Python.
103Now that we're using a framework, let's add some features.
104
105Continue to :ref:`tutorials.gettingstarted.usingusers`.
106