1 .. _tutorials.gettingstarted.usingwebapp2: 2 3 Using the webapp2 Framework 4 =========================== 5 The CGI standard is simple, but it would be cumbersome to write all of the 6 code that uses it by hand. Web application frameworks handle these details 7 for you, so you can focus your development efforts on your application's 8 features. Google App Engine supports any framework written in pure Python 9 that speaks CGI (and any 10 `WSGI <http://www.python.org/dev/peps/pep-0333/>`_-compliant framework using a 11 CGI adaptor). You can bundle a framework of your choosing with your application 12 code by copying its code into your application directory. 13 14 App Engine includes a simple web application framework of its own, called 15 ``webapp``. The ``webapp`` framework is already installed in the App Engine 16 environment and in the SDK, and as ``webapp2`` is based on it, you only need 17 to bundle a single file with your application code to use it. We will use 18 ``webapp2`` for the rest of this tutorial. 19 20 Follow 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 28 Hello, webapp2! 29 --------------- 30 A ``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 38 Let'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 52 Also 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 66 Reload `http://localhost:8080/ <http://localhost:8080/>`_ in your browser to 67 see the new version in action (if you stopped your web server, restart it by 68 running the command described in ":ref:`tutorials.gettingstarted.helloworld`"). 69 70 71 What webapp2 Does 72 ----------------- 73 This code defines one request handler, ``MainPage``, mapped to the root URL 74 (``/``). When ``webapp2`` receives an HTTP GET request to the URL ``/``, it 75 instantiates the ``MainPage`` class and calls the instance's ``get`` method. 76 Inside the method, information about the request is available using 77 ``self.request``. Typically, the method sets properties on ``self.response`` 78 to prepare the response, then exits. ``webapp2`` sends a response based on 79 the final state of the ``MainPage`` instance. 80 81 The application itself is represented by a ``webapp2.WSGIApplication`` 82 instance. The parameter ``debug=true`` passed to its constructor tells 83 ``webapp2`` to print stack traces to the browser output if a handler 84 encounters an error or raises an uncaught exception. You may wish to remove 85 this option from the final version of your application. 86 87 The code ``application.run()`` runs the application in App Engine's CGI 88 environment. It uses a function provided by App Engine that is similar to the 89 WSGI-to-CGI adaptor provided by the ``wsgiref`` module in the Python standard 90 library, but includes a few additional features. For example, it can 91 automatically detect whether the application is running in the development 92 server or on App Engine, and display errors in the browser if it is running 93 on the development server. 94 95 We'll use a few more features of ``webapp2`` later in this tutorial. For more 96 information about ``webapp2``, see the webapp2 reference. 97 98 99 Next... 100 ------- 101 Frameworks make web application development easier, faster and less error 102 prone. webapp2 is just one of many such frameworks available for Python. 103 Now that we're using a framework, let's add some features. 104 105 Continue to :ref:`tutorials.gettingstarted.usingusers`. 106
