1.. _tutorials.gettingstarted.helloworld:
2
3Hello, World!
4=============
5Python App Engine applications communicate with the web server using the
6`CGI <http://www.w3.org/CGI/>`_ standard. When the server receives a request
7for your application, it runs the application with the request data in
8environment variables and on the standard input stream (for POST data).
9To respond, the application writes the response to the standard output stream,
10including HTTP headers and content.
11
12Let's begin by implementing a tiny application that displays a short message.
13
14
15Creating a Simple Request Handler
16---------------------------------
17Create a directory named ``helloworld``. All files for this application reside
18in this directory.
19
20Inside the ``helloworld`` directory, create a file named ``helloworld.py``,
21and give it the following contents::
22
23    print 'Content-Type: text/plain'
24    print ''
25    print 'Hello, world!'
26
27This Python script responds to a request with an HTTP header that describes
28the content, a blank line, and the message ``Hello, world!``.
29
30
31Creating the Configuration File
32-------------------------------
33An App Engine application has a configuration file called ``app.yaml``. Among
34other things, this file describes which handler scripts should be used for
35which URLs.
36
37Inside the ``helloworld`` directory, create a file named ``app.yaml`` with the
38following contents:
39
40.. code-block:: yaml
41
42   application: helloworld
43   version: 1
44   runtime: python27
45   api_version: 1
46   threadsafe: true
47
48   handlers:
49   - url: /.*
50     script: helloworld.py
51
52From top to bottom, this configuration file says the following about this
53application:
54
55- The application identifier is ``helloworld``. When you register your
56  application with App Engine in the final step, you will select a unique
57  identifier, and update this value. This value can be anything during
58  development. For now, leave it set to helloworld.
59- This is version number ``1`` of this application's code. If you adjust this
60  before uploading new versions of your application software, App Engine will
61  retain previous versions, and let you roll back to a previous version using
62  the administrative console.
63- This code runs in the ``python`` runtime environment, version "1".
64  Additional runtime environments and languages may be supported in the future.
65- Every request to a URL whose path matches the regular expression ``/.*``
66  (all URLs) should be handled by the ``helloworld.py`` script.
67
68The syntax of this file is `YAML <http://www.yaml.org/>`_. For a complete list
69of configuration options, see
70`the app.yaml reference <http://code.google.com/appengine/docs/python/config/appconfig.html>`_.
71
72
73Testing the Application
74-----------------------
75With a handler script and configuration file mapping every URL to the handler,
76the application is complete. You can now test it with the web server included
77with the App Engine SDK.
78
79If you're using the Google App Engine Launcher, you can set up the application
80by selecting the **File** menu, **Add Existing Application...**, then selecting
81the ``helloworld`` directory. Select the application in the app list, click the
82Run button to start the application, then click the Browse button to view it.
83Clicking Browse simply loads (or reloads)
84`http://localhost:8080/ <http://localhost:8080/>`_ in your default web browser.
85
86If you're not using Google App Engine Launcher, start the web server with the
87following command, giving it the path to the ``helloworld`` directory:
88
89.. code-block:: text
90
91   google_appengine/dev_appserver.py helloworld/
92
93The web server is now running, listening for requests on port 8080. You can
94test the application by visiting the following URL in your web browser:
95
96    http://localhost:8080/
97
98For more information about running the development web server, including how
99to change which port it uses, see `the Dev Web Server reference <http://code.google.com/appengine/docs/python/tools/devserver.html>`_,
100or run the command with the option ``--help``.
101
102
103Iterative Development
104---------------------
105You can leave the web server running while you develop your application.
106The web server knows to watch for changes in your source files and reload
107them if necessary.
108
109Try it now: Leave the web server running, then edit ``helloworld.py`` to
110change ``Hello, world!`` to something else. Reload
111`http://localhost:8080/ <http://localhost:8080/>`_ or click Browse in Google
112App Engine Launcher to see the change.
113
114To shut down the web server, make sure the terminal window is active, then
115press Control-C (or the appropriate "break" key for your console), or click
116Stop in Google App Engine Launcher.
117
118You can leave the web server running for the rest of this tutorial. If you
119need to stop it, you can restart it again by running the command above.
120
121
122Next...
123-------
124You now have a complete App Engine application! You could deploy this simple
125greeting right now and share it with users worldwide. But before we deploy it,
126let's consider using a web application framework to make it easier to add
127features.
128
129Continue to :ref:`tutorials.gettingstarted.usingwebapp2`.
130