Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
The App Engine Python SDK includes a web server application you can run on your computer that simulates your application running in the App Engine Python runtime environment. The simulated environment enforces some sandbox restrictions, such as restricted system functions and Python module imports, but not others, like request time-outs or quotas. The server also simulates the services by performing their tasks locally.
Once you have a directory for your application and an app.yaml configuration file, you can start the development web server with the dev_appserver.py
command:
dev_appserver.py myapp
The web server listens on port 8080 by default. You can visit the application at this URL: http://localhost:8080/
To change which port the web server uses, use the --port
option:
dev_appserver.py --port=9999 myapp
To stop the web server: With Windows, press Control-Break in your command prompt window. With Mac OS X or Unix, press Control-C.
While it is running, the web server watches for changes you make to your files, and reloads them if needed. For most kinds of changes, you can simply edit files, then reload the web page in your browser. Under certain circumstances, such as if the application does dynamic imports, you may need to restart the web server to reset module import caching.
Be sure to run dev_appserver.py
using Python 2.5. It will run under Python 2.4, but there are differences between Python 2.4 and 2.5 that may affect your application, such as handling of Unicode strings.
If you need to access your App ID, for example to spoof an email address, use the get_application_id() function. To get the hostname of the running app, use the get_default_version_hostname() function.
Warning! Do not get the App ID from the environment variable. The development server simulates the production App Engine service. One way in which it does this is to prepend a string (dev~
) to the APPLICATION_ID
environment variable, which is similar to the string prepended in production for applications using the High Replication Datastore. You can modify this behavior with the --default_partition flag, choosing a value of ""
to match the master-slave option in production. Google recommends always getting the application ID using the get_application_id() method, and never using the APPLICATION_ID
environment variable.
The development web server simulates the App Engine datastore using a file on your computer. This file persists between invocations of the web server, so data you store will still be available the next time you run the web server.
To clear the local datastore for an application, use the --clear_datastore
option when you start the web server:
dev_appserver.py --clear_datastore myapp
The web server prints the location of the datastore file it is using to the terminal when it starts up. You can make a copy of the file, then restore them later to reset the datastore to a known state. Be sure to restart the web server after replacing the datastore file.
To change the location used for the datastore file, use the --datastore_path
option:
dev_appserver.py --datastore_path=/tmp/myapp_datastore myapp
When your application performs a query on the datastore, the development web server checks that the query is supported by the application's index.yaml
file. If the query requires that its index be mentioned in the file, the server generates one and adds it to the file. You may want to edit this file if your application may attempt queries that are not exercised by your tests.
index.yaml
is generated from every query made since the datastore file was created or last cleared. The query history is stored in a separate file. To change the location of the history file, use the --history_path
option similarly to the --datastore_path
option.
For more information on indexes and index.yaml
, see Queries and Indexes, and Configuring Indexes.
You can configure the local datastore to simulate the consistency model of the High Replication Datastore. This will give you a good idea how an application configured to use the High Replication Datastore will operate in production.
To enable the High Replication consistency model, use the --high_replication
option.
dev_appserver.py --high_replication
If you store a lot of data in your datastore, you can improve performance and startup times by switching the backend for your local datastore stub to SQLite.
Note: Switching between SQLite and regular datastore backends will erase your local datastore.
To switch to SQLite, use the --use_sqlite
option.
dev_appserver.py --use_sqlite
The development web server simulates Google Accounts with its own sign-in and sign-out pages. While running under the development web server,
the users.create_login_url and users.create_logout_url
functions return URLs for /_ah/login
and /_ah/logout
on the local server.
The development sign-in page includes a form where you can enter an email address. Your session uses whatever email address you enter as the active user.
To have the application believe that the logged-in user is an administrator, check the checkbox on the form.
The development web server can send email for calls to the App Engine mail service. To enable email support, the web server must be given options that specify a mail server to use. The web server can use an SMTP server, or it can use a local installation of Sendmail.
To enable mail support with an SMTP server, use the --smtp_host
, --smtp_port
, --smtp_user
and --smtp_password
options with the appropriate values.
dev_appserver.py --smtp_host=smtp.example.com --smtp_port=25 \ --smtp_user=ajohnson --smtp_password=k1tt3ns myapp
To enable mail support with Sendmail, use the --enable_sendmail
option. The web server will use the sendmail
command to send email messages, with your installation's default configuration.
dev_appserver.py --enable_sendmail myapp
If mail is not enabled with either SMTP or Sendmail, then attempts to send email from the application will do nothing, and appear successful in the application.
When your application uses the URL fetch API to make an HTTP request, the development web server makes the request directly from your computer. The behavior may differ from when your application runs on App Engine if you use a proxy server for accessing websites.
Note: dev_appserver.py
can only serve one request at a time. If your application makes URL fetch requests to itself while processing a request, these requests will fail when using the development web server. (They will not fail when running on App Engine.) To test such requests, you can run a second instance of dev_appserver.py
on a different port, then code your application to use the other server when making requests to itself.
The development web server includes a console web application. With the console, you can browse the local datastore, and interact with the application by submitting Python code to a web form.
To access the console, visit the URL /_ah/admin
on your server: http://localhost:8080/_ah/admin
The dev_appserver.py
command supports the following command-line arguments:
--datastore_path=...
The path to use for the local datastore data file. The server creates this file if it does not exist.
--history_path=...
The path to use for the local datastore history file. The server uses the query history file to generate entries for index.yaml
.
--debug
Prints verbose debugging messages to the console while running.
--help
Prints a helpful message then quits.
--login_url=...
The relative URL to use for the Users sign-in page. Default is /_ah/login
.
--port=...
The port number to use for the server. Default is 8080
.
--address=...
The host address to use for the server. You may need to set this to be able to access the development server from another computer on your network. An address of 0.0.0.0
allows both localhost access and hostname access. Default is localhost
.
--clear_datastore
Clears the datastore data and history files before starting the web server.
--persist_logs
Turns on storage of logs to enable the use of the logservice.fetch() functionality. When this option is used, the logs are stored to the datastore where they persist across dev_appserver restarts. By default, this is turned off.
--require_indexes
Disables automatic generation of entries in the index.yaml
file. Instead, when the application makes a query that requires that its index be defined in the file and the index definition is not found, an exception will be raised, similar to what would happen when running on App Engine.
--smtp_host=...
The hostname of the SMTP server to use for sending email messages.
--smtp_port=...
The port number of the SMTP server to use for sending email messages.
--smtp_user=...
The username to use with the SMTP server for sending email messages.
--smtp_password=...
The password to use with the SMTP server for sending email messages.
--enable_sendmail
Uses the local computer's Sendmail installation for sending email messages.
--debug_imports
Prints debugging messages related to importing modules, including search paths and errors.
--default_partition
Specifies the partition to use. The default partition is dev
, but you can change it to any string, or ""
. The development server adds the name of the prefix followed by a ~
(for example, dev~
) to the the application ID stored in the environment variable.