Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
App Engine executes your Python application code using a pre-loaded Python interpreter in a safe "sandboxed" environment. Your app receives web requests, performs work, and sends responses by interacting with this environment.
App Engine knows to use the Python runtime environment for your application code when you use the tool named appcfg.py
from the Python SDK with a configuration file named app.yaml
.
You specify the runtime
element in app.yaml
. You can choose either Python 2.5 or the new, experimental Python 2.7 runtime. To use Python 2.5, add the following to app.yaml
:
runtime: python api_version: 1 ...
The first element, runtime
, selects the Python runtime environment. App Engine supports four runtime environments:
python
python27
– This runtime is experimental. See the Python 2.7 documentation for more information.java
– See the Java runtime documentation for more information.go
– See the Go runtime documentation for more information.The second element, api_version
, selects which version of the Python runtime environment to use. As of this writing, App Engine only has one version of the Python environment, 1
. If the App Engine team ever needs to release changes to the environment that may not be compatible with existing code, they will do so with a new version identifier. Your app will continue to use the selected version until you change the api_version
setting and upload your app.
For more information about app.yaml
and appcfg.py
, see Python Application Configuration, Using Python 2.7, and Uploading an App.
App Engine determines that an incoming request is intended for your application using the domain name of the request. A request whose domain name is http://your_app_id.appspot.com
is routed to the application whose ID is your_app_id
. Every application gets an appspot.com
domain name for free.
appspot.com
domains also support subdomains of the form subdomain.your_app_id.appspot.com
, where subdomain
can be any string allowed in one part of a domain name (not .
). Requests sent to any subdomain in this way are routed to your application.
You can set up a custom top-level domain using Google Apps. With Google Apps, you assign subdomains of your business's domain to various applications, such as Google Mail or Sites. You can also associate an App Engine application with a subdomain. For convenience, you can set up a Google Apps domain when you register your application ID, or later from the Administrator Console. See Deploying your Application on your Google Apps URL for more information.
Requests for these URLs all go to the version of your application that you have selected as the default version in the Administration Console. Each version of your application also has its own URL, so you can deploy and test a new version before making it the default version. The version-specific URL uses the version identifier from your app's configuration file in addition to the appspot.com
domain name, in this pattern: http://version_id.latest.your_app_id.appspot.com
You can also use subdomains with the version-specific URL: http://subdomain.version_id.latest.your_app_id.appspot.com
Warning! When writing Python code to get the application ID, you must use the get_application_id() API instead of the environment variable. App Engine may prepend a string to the application ID in the environment variable (such as dev~
in the development web server and s~
in production). Functions that rely on the application ID set in app.yaml
will fail if called with the application ID from the environment variable.
The domain name used for the request is included in the request data passed to the application. If you want your app to respond differently depending on the domain name used to access it (such as to restrict access to certain domains, or redirect to an official domain), you can check the request data (such as the Host
request header) for the domain from within the application code and respond accordingly.
If your app uses backends, you can address requests to a specific backend and a specific instance with that backend. For more information about backend addressability, please see Properties of Backends.
When App Engine receives a web request for your application, it calls the handler script that corresponds to the URL, as described in the application's app.yaml configuration file. If your application uses backends, it may also call the handler script defined in backends.yaml
. See Backend Configuration for more information.
App Engine uses multiple web servers to run your application, and automatically adjusts the number of servers it is using to handle requests reliably. A given request may be routed to any server, and it may not be the same server that handled a previous request from the same user.
The Python 2.5 runtime always uses the CGI standard. The Python 2.7 runtime supports the WSGI standard and CGI for backwards compatibility. WSGI is preferred, and some features of Python 2.7 do not work without it. The configuration of your application's script handlers determines whether a request is handled using WSGI or CGI.
The server determines which Python handler script to run by comparing the URL of the request to the URL patterns in the app's configuration file. It then runs the script in a CGI environment populated with the request data. As described in the CGI standard, the server puts the request data in environment variables and the standard input stream. The script performs actions appropriate to the request, then prepares a response and puts it on the standard output stream.
Most applications use a library to parse CGI requests and return CGI responses, such as the cgi module from the Python standard library, or a web framework that knows the CGI protocol (such as webapp). You can refer to the CGI documentation for details about the environment variables and the format of the input stream data.
The following example handler script displays a message on the user's browser. It prints an HTTP header that identifies the type of the message and the content of message to the standard output stream.
print "Content-Type: text/plain" print "" print "Hello, world!"
The server determines which Python application object to call by comparing the URL of the request to the URL patterns in the app's configuration file. It then calls the application object using the arguments as defined in the WSGI standard. The application object performs actions appropriate to the request, then prepares a response and returns it as a list of strings.
Most applications use a framework, such as webapp2, to handle WSGI requests. webapp2
is included as part of the Python 2.7 runtime.
An incoming HTTP request includes the HTTP headers sent by the client. For security purposes, some headers are sanitized or amended by intermediate proxies before they reach the application.
As a service to the app, App Engine adds an additional header: X-AppEngine-Country
This header's value represents the country from which the request originated, as an ISO 3166-1 alpha-2 country code. App Engine determines this code from the client's IP address.
App Engine collects all of the data the request handler script writes to the standard output stream, then waits for the script to return. When the handler completes, all of the output data is sent to the user.
App Engine does not support sending data to the user's browser before the handler returns. Some web servers use this technique to "stream" data to the user's browser over a period of time in response to a single request. App Engine does not support this streaming technique.
If the client sends HTTP headers with the request indicating that the client can accept compressed (gzipped) content, App Engine compresses the response data automatically and attaches the appropriate response headers. It uses both the Accept-Encoding
and User-Agent
request headers to determine if the client can reliably receive compressed responses. Custom clients can force content to be compressed by specifying both Accept-Encoding
and User-Agent
headers with a value of "gzip".
If you access your site while signed in using an administrator account, App Engine includes per-request statistics in the response headers. The header X-AppEngine-Estimated-CPM-US-Dollars
represents an estimate of what 1,000 requests similar to this request would cost in US dollars. The header X-AppEngine-Resource-Usage
represents the resources used by the request, including server-side time as a number of milliseconds.
A request handler has a limited amount of time to generate and return a response to a request, typically around 60 seconds. Once the deadline has been reached, the request handler is interrupted.
The Python runtime environment interrupts the request handler by raising a DeadlineExceededError
, from the package google.appengine.runtime
. If the request handler does not catch this exception, as with all uncaught exceptions, the runtime environment will return an HTTP 500 server error to the client.
The request handler can catch this error to customize the response. The runtime environment gives the request handler a little bit more time (less than a second) after raising the exception to prepare a custom response.
from google.appengine.runtime import DeadlineExceededError class MainPage(webapp.RequestHandler): def get(self): try: # Do stuff... except DeadlineExceededError: self.response.clear() self.response.set_status(500) self.response.out.write("This operation could not be completed in time...")
If the handler hasn't returned a response or raised an exception by the second deadline, the handler is terminated and a default error response is returned.
While a request can take as long as 60 seconds to respond, App Engine is optimized for applications with short-lived requests, typically those that take a few hundred milliseconds. An efficient app responds quickly for the majority of requests. An app that doesn't will not scale well with App Engine's infrastructure.
Backends allow you to avoid this request timer; with backends, there is no time limit for generating and returning a request.
To allow App Engine to distribute requests for applications across multiple web servers, and to prevent one application from interfering with another, the application runs in a restricted "sandbox" environment. In this environment, the application can execute code, store and query data in the App Engine datastore, use the App Engine mail, URL fetch and users services, and examine the user's web request and prepare the response.
An App Engine application cannot:
The Python 2.7 runtime no longer restricts access to Python bytecode. Libraries that generate or manipulate bytecode (e.g. the jinja2 templating library) can do so in this runtime.
You can upload and use .pyc
, but not in combination with .py
files. You can upload zip files containing .py
or .pyc
files (or a combination).
Threads can be created using the thread or threading modules. Note that threads will be joined by the runtime when the request ends so the threads cannot run past the end of the request.
The Python runtime environment uses Python 2.5.2 or Python 2.7.
All code for the Python runtime environment must be pure Python, and not include any C extensions or other code that must be compiled.
The environment includes the Python standard library. Some modules have been disabled because their core functions are not supported by App Engine, such as networking or writing to the filesystem. In addition, the os
module is available, but with unsupported features disabled. An attempt to import an unsupported module or use an unsupported feature will raise an exception.
You can include other pure Python libraries with your application by putting the code in your application directory. If you make a symbolic link to a module's directory in your application directory, appcfg.py will follow the link and include the module in your app.
The Python module include path includes your application's root directory (the directory containing the app.yaml
file). Modules you create in your application's root directory are available using a path from the root. Don't forget to create __init__.py
files in sub-directories, so Python will recognize the sub-directories as packages.
A few modules from the standard library have been replaced or customized to work with App Engine. These modules vary between the two Python runtimes, as described below.
In the Python 2.5 runtime, the following modules have been replaced or customized:
TemporaryFile
which is aliased to StringIO.In addition to the Python standard library and the App Engine libraries, the runtime environment includes the following third-party libraries:
In the Python 2.7 runtime, the following modules have been replaced or customized:
TemporaryFile
which is aliased to StringIO.In addition to the Python standard library and the App Engine libraries, the Python 2.7 runtime includes the following third-party libraries:
The Python runtime environment caches imported modules between requests on a single web server, similar to how a standalone Python application loads a module only once even if the module is imported by multiple files. The runtime also caches WSGI handlers while CGI handler scripts are only cached if they provide a main()
routine. Otherwise, the CGI handler script is loaded for every request. See Requests for more information about the differences between CGI and WSGI.
App caching provides a significant benefit in response time. We recommend that all CGI handler scripts use a main() routine, as described below.
For efficiency, the web server keeps imported modules in memory and does not re-load or re-evaluate them on subsequent requests to the same application on the same server. Most modules do not initialize any global data or have other side effects when they are imported, so caching them does not change the behavior of the application.
If your application imports a module that depends on the module being evaluated for every request, the application must accommodate this caching behavior.
The following example demonstrates how an imported module is cached. Because mymodule
is only imported once for a single web server, the global mymodule.counter
is only initialized to 0
on the first request served by the server. Subsequent requests use the value from the previous request.
### mymodule.py counter = 0 def increment(): global counter counter += 1 return counter ### myhandler.py import mymodule print "Content-Type: text/plain" print "" print "My number: " + str(mymodule.increment())
This outputs My number: #
where #
is the number of times this handler has been called by the web server that handled the request.
You can tell App Engine to cache the CGI handler script itself, in addition to imported modules. If the handler script defines a function named main()
, then the script and its global environment will be cached like an imported module. The first request for the script on a given web server evaluates the script normally. For subsequent requests, App Engine calls the main()
function in the cached environment.
To cache a handler script, App Engine must be able to call main()
with no arguments. If the handler script does not define a main()
function, or the main()
function requires arguments (that don't have defaults), then App Engine loads and evaluates the entire script for every request.
Keeping the parsed Python code in memory saves time and allows for faster responses. Caching the global environment has other potential uses as well:
The handler script should call main()
when imported. App Engine expects that importing the script calls main()
, so App Engine does not call it when loading the request handler for the first time on a server.
The following example does the same thing as the previous example, using caching of the handler script's global environment:
### myhandler.py # A global variable, cached between requests on this web server. counter = 0 def main(): global counter counter += 1 print "Content-Type: text/plain" print "" print "My number: " + str(counter) if __name__ == "__main__": main()
Note: Be careful to not "leak" user-specific information between requests. Avoid global variables unless caching is desired, and always initialize request-specific data inside the main()
routine.
App caching with main()
provides a significant improvement in your CGI handler's response time. We recommend it for all applications that use CGI.
The App Engine web server captures everything the handler script writes to the standard output stream for the response to the web request. It also captures everything the handler script writes to the standard error stream, and stores it as log data. Log data for your application can be viewed and analyzed using the Administration Console, or downloaded using appcfg.py request_logs.
The App Engine Python runtime environment includes special support for the logging module from the Python standard library to understand logging concepts such as log levels ("debug", "info", "warning", "error", "critical").
import logging from google.appengine.api import users from google.appengine.ext import db user = users.get_current_user() if user: q = db.GqlQuery("SELECT * FROM UserPrefs WHERE user = :1", user) results = q.fetch(2) if len(results) > 1: logging.error("more than one UserPrefs object for user %s", str(user)) if len(results) == 0: logging.debug("creating UserPrefs object for user %s", str(user)) userprefs = UserPrefs(user=user) userprefs.put() else: userprefs = results[0] else: logging.debug("creating dummy UserPrefs for anonymous user")
The execution environment includes several environment variables useful to the application. Some of these are special to App Engine, while others are part of the CGI standard. Python code can access these variables using the os.environ
dictionary.
The following environment variables are specific to App Engine:
CURRENT_VERSION_ID
: The major and minor version of the currently running application, as "X.Y". The major version number ("X") is specified in the app's app.yaml
file. The minor version number ("Y") is set automatically when each version of the app is uploaded to App Engine. On the development web server, the minor version is always "1". AUTH_DOMAIN
: The domain used for authenticating users with the Users API. Apps hosted on appspot.com have an AUTH_DOMAIN
of gmail.com
, and accept any Google account. Apps hosted on a custom domain using Google Apps have an AUTH_DOMAIN
equal to the custom domain.The following environment variables are part of the CGI standard, with special behavior in App Engine:
SERVER_SOFTWARE
: In the development web server, this value is "Development/X.Y" where "X.Y" is the version of the runtime. When running on App Engine, this value is "Google App Engine/X.Y.Z".Additional environment variables are set according to the CGI standard. For more information on these variables, see the CGI standard.
Tip: The following webapp request handler displays every environment variable visible to the application in the browser:
from google.appengine.ext import webapp import os class PrintEnvironmentHandler(webapp.RequestHandler): def get(self): for name in os.environ.keys(): self.response.out.write("%s = %s<br />\n" % (name, os.environ[name]))
Google App Engine allocates resources to your application automatically as traffic increases to support many simultaneous requests. However, App Engine reserves automatic scaling capacity for applications with low latency, where the application responds to requests in less than one second. Applications with very high latency (over one second per request for many requests) are limited by the system, and require a special exemption in order to have a large number of simultaneous dynamic requests. If your application has a strong need for a high throughput of long-running requests, you can request an exemption from the simultaneous dynamic request limit. The vast majority of applications do not require any exemption.
Applications that are heavily CPU-bound may also incur some additional latency in order to efficiently share resources with other applications on the same servers. Requests for static files are exempt from these latency limits.
Each incoming request to the application counts toward the Requests limit.
Data sent in response to a request counts toward the Outgoing Bandwidth (billable) limit.
Both HTTP and HTTPS (secure) requests count toward the Requests, Incoming Bandwidth (billable), and Outgoing Bandwidth (billable) limits. The Quota Details page of the Admin Console also reports Secure Requests, Secure Incoming Bandwidth, and Secure Outgoing Bandwidth as separate values for informational purposes. Only HTTPS requests count toward these values.
For more information on system-wide safety limits, see Limits, and the "Quota Details" section of the Admin Console.
In addition to system-wide safety limits, the following limits apply specifically to the use of request handlers:
Limit | Amount |
---|---|
request size | 32 megabytes |
response size | 32 megabytes |
request duration | 60 seconds |
maximum total number of files (app files and static files) | 10,000 total 1,000 per directory |
maximum size of an application file | 32 megabytes |
maximum size of a static file | 32 megabytes |
maximum total size of all application and static files | 150 megabytes |