.. _tutorials.gettingstarted.usingwebapp2:

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 <http://www.python.org/dev/peps/pep-0333/>`_-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:

.. code-block:: yaml

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

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

Reload `http://localhost:8080/ <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 ":ref:`tutorials.gettingstarted.helloworld`").


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.


Next...
-------
Frameworks make web application development easier, faster and less error
prone. webapp2 is just one of many such frameworks available for Python.
Now that we're using a framework, let's add some features.

Continue to :ref:`tutorials.gettingstarted.usingusers`.