English | Site Directory

Configuring a Python App

An App Engine application written in Python uses configuration files that are uploaded with the app's code. These files specify the version number of the app code, the runtime environment App Engine should use with the app, how URLs correspond with handler scripts, and which datastore indexes the app needs for its queries.

Runtimes and URLs: app.yaml

A Python app specifies runtime configuration, including versions and URLs, in a file named app.yaml. The following is an example of an app.yaml file:

application: myapp
version: 1
runtime: python
api_version: 1

handlers:
- url: /
  script: home.py

- url: /index\.html
  script: home.py

- url: /stylesheets
  static_dir: stylesheets

- url: /(.*\.(gif|png|jpg))
  static_files: static/\1
  upload: static/(.*\.(gif|png|jpg))

- url: /admin/.*
  script: admin.py
  login: admin

- url: /.*
  script: not_found.py

The syntax of app.yaml is the YAML format. For more information about this syntax, see the YAML website for more information.

Tip: The YAML format supports comments. A line that begins with a pound (#) character is ignored:
# This is a comment.

URL and file path patterns use POSIX extended regular expression syntax, excluding collating elements and collation classes. Back-references to grouped matches (e.g. \1) are supported, as are these Perl extensions: \w \W \s \S \d \D (This is similar to Codesite search, plus back-reference support.)

Required Elements

An app.yaml file must include one of each of the following elements:

application

The application identifier. This is the identifier you selected when you created the application in the Administration Console.

application: myapp
version

A version specifier for the application code. App Engine retains a copy of your application for each version used. An administrator can change which major version of the application is public using the Administration Console, and can test non-public versions before making them public.

Each version of an application retains its own copy of app.yaml. When an application is uploaded, the version mentioned in the app.yaml file being uploaded is the version that gets created or replaced by the upload.

On the Administration Console, the version number appears as a major version (version), and a minor version that corresponds to the number of times this major version has been uploaded. Only the latest major version is retained.

version: 1
runtime

The name of the App Engine runtime environment used by this application. At this time, App Engine has one runtime environment: python

runtime: python
api_version

The version of the API in the given runtime environment used by this application. When Google releases a new version of a runtime environment's API, your application will continue to use the one for which it was written. To upgrade your application to the new API, you change this value and upload the upgraded code.

At this time, App Engine has one version of the python runtime environment: 1

api_version: 1
handlers

A list of URL patterns and descriptions of how they should be handled. App Engine can handle URLs by executing application code, or by serving static files uploaded with the code, such as images, CSS or JavaScript.

Patterns are evaluated in the order they appear in the app.yaml, from top to bottom. The first mapping whose pattern matches the URL is the one used to handle the request.

There are two kinds of handlers: script handlers, and static file handlers. A script handler runs a Python script in your application to determine the response for the given URL. A static file handler returns the contents of a file, such as an image, as the response.

See Script Handlers and Handlers for Static Files below for more information on this value.

handlers:
- url: /images
  static_dir: static/images

- url: /.*
  script: myapp.py

Script Handlers

A script handler executes a Python script to handle the request that matches the URL pattern. The mapping defines a URL pattern to match, and the script to be executed.

url

The URL pattern, as a regular expression. The expression can contain groupings that can be referred to in the file path to the script with regular expression back-references.

For example, /profile/(.*?)/(.*) would match the URL /profile/edit/manager and use edit and manager as the first and second groupings.

handlers:
- url: /profile/(.*?)/(.*)
  script: /employee/\2/\1.py
script

The path to the script, from the application root directory.

As in the previous example, with the groupings edit and manager, the script path /employee/\2/\1.py uses the full path /employee/manager/edit.py.

The following examples map URLs to scripts:

handlers:

# The root URL (/) is handled by the index.py script.  No other URLs match this pattern.
- url: /
  script: index.py

# The URL /index.html is also handled by the index.py script.
- url: /index\.html
  script: index.py

# A regular expression can map parts of the URL to the file path of the script.
- url: /browse/(books|videos|tools)
  script: \1/catalog.py

# All other URLs use the not_found.py script.
- url: /.*
  script: not_found.py

Handlers for Static Files

Static files are files to be served directly to the user for a given URL, such as images, CSS stylesheets, or JavaScript source files. Static file handlers describe which files in the application directory are static files, and which URLs serve them.

For efficiency, App Engine stores and serves static files separately from application files. Static files are not available in the application's file system. If you have data files that need to be read by the application code, the data files must be application files, and must not be matched by a static file pattern.

Unless told otherwise, web browsers retain files they load from a website for a limited period of time. You can define a global default cache period for all static file handlers for an application by including the default_expiration element, a top-level element. You can also configure a cache duration for specific static file handler. (Script handlers can set cache durations by returning the appropriate HTTP headers to the browser.)

default_expiration

The length of time a static file served by a static file handler ought to be cached in the user's browser, if the handler does not specify its own expiration. The value is a string of numbers and units, separated by spaces, where units can be d for days, h for hours, m for minutes, and s for seconds. For example, "4d 5h" sets cache expiration to 4 days and 5 hours after the file is first loaded by the browser.

default_expiration is optional. If omitted, the default behavior is to allow the browser to determine its own cache duration.

For example:

application: myapp
version: 1
runtime: python
api_version: 1

default_expiration: "4d 5h"

handlers:
  # ...

Static file handlers can be defined in two ways: as a directory structure of static files that maps to a URL path, or as a pattern that maps URLs to specific files.

Static Directory Handlers

A static directory handler makes it easy to serve the entire contents of a directory as static files. Each file is served using the MIME type that corresponds with its filename extension unless overridden by the directory's mime_type setting. All of the files in the given directory are uploaded as static files, and none of them can be run as scripts.

url

A URL prefix. This value uses regular expression syntax (and so regexp special characters must be escaped), but it should not contain groupings. All URLs that begin with this prefix are handled by this handler, using the portion of the URL after the prefix as part of the file path.

static_dir

The path to the directory containing the static files, from the application root directory. Everything after the end of the matched url pattern is appended to static_dir to form the full path to the requested file.

All files in this directory are uploaded with the application as static files.

mime_type

Optional. If specified, all files served by this handler will be served using the specified MIME type. If not specified, the MIME type for a file will be derived from the file's filename extension.

For more information about the possible MIME media types, see the IANA MIME Media Types website.

expiration

The length of time a static file served by this handler ought to be cached in the user's browser. The value is a string of numbers and units, separated by spaces, where units can be d for days, h for hours, m for minutes, and s for seconds. For example, "4d 5h" sets cache expiration to 4 days and 5 hours after the file is first loaded by the browser.

expiration is optional. If omitted, the application's default_expiration is used.

For example:

handlers:

# All URLs beginning with /stylesheets are treated as paths to static files in
# the stylesheets/ directory.  Note that static_dir handlers do not use a
# regular expression for the URL pattern, only a prefix.
- url: /stylesheets
  static_dir: stylesheets

Static File Pattern Handlers

A static file handler associates a URL pattern with paths to static files uploaded with the application. The URL pattern regular expression can define regular expression groupings to be used in the construction of the file path. You can use this instead of static_dir to map to specific files in a directory structure without mapping the entire directory.

Static files cannot be the same as application code files. If a static file path matches a path to a script used in a dynamic handler, the script will not be available to the dynamic handler.

The following static_dir and static_files handlers are equivalent:

- url: /images
  static_dir: static/images

- url: /images/(.*)
  static_files: static/images/\1
  upload: static/images/(.*)
url

The URL pattern, as a regular expression. The expression can contain groupings that can be referred to in the file path to the script with regular expression back-references.

For example, /item-(.*?)/category-(.*) would match the URL /item-127/category-fruit, and use 127 and fruit as the first and second groupings.

handlers:
- url: /item-(.*?)/category-(.*)
  static_files: archives/\2/items/\1
static_files

The path to the static files matched by the URL pattern, from the application root directory. The path can refer to text matched in groupings in the URL pattern.

As in the previous example, archives/\2/items/\1 inserts the second and first groupings matched in place of \2 and \1, respectively. With the pattern in the example above, the file path would be archives/fruit/items/127.

upload

A regular expression that matches the file paths for all files that will be referenced by this handler. This is necessary because the handler cannot determine which files in your application directory correspond with the given url and static_files patterns. Static files are uploaded and handled separately from application files.

The example above might use the following upload pattern: archives/(.*?)/items/(.*)

mime_type

Optional. If specified, all files served by this handler will be served using the specified MIME type. If not specified, the MIME type for a file will be derived from the file's filename extension.

For more information about the possible MIME media types, see the IANA MIME Media Types website.

expiration

The length of time a static file served by this handler ought to be cached in the user's browser. The value is a string of numbers and units, separated by spaces, where units can be d for days, h for hours, m for minutes, and s for seconds. For example, "4d 5h" sets cache expiration to 4 days and 5 hours after the file is first loaded by the browser.

expiration is optional. If omitted, the application's default_expiration is used.

For example:

handlers:

# All URLs ending in .gif .png or .jpg are treated as paths to static files in
# the static/ directory.  The URL pattern is a regexp, with a grouping that is
# inserted into the path to the file.
- url: /(.*\.(gif|png|jpg))
  static_files: static/\1
  upload: static/(.*\.(gif|png|jpg))

Secure URLs

Google App Engine supports secure connections via HTTPS for URLs using the *.appspot.com domain. When a request accesses a URL using HTTPS, and that URL is configured to use HTTPS in the app.yaml file, both the request data and the response data are encrypted by the sender before they are transmitted, and decrypted by the recipient after they are received. Secure connections are useful for protecting customer data, such as contact information, passwords, and private messages.

Note: Google Apps domains do not currently support HTTPS. HTTPS support is limited to apps accessed via *.appspot.com domains. Accessing an HTTPS URL on a Google Apps domain will return a "host not found" error, and accessing a URL whose handler only accepts HTTPS (see below) using HTTP will return an HTTP 403 "Forbidden" error. You can link to an HTTPS URL with the *.appspot.com domain for secure features, and use the Apps domain and HTTP for the rest of the site. (Redirecting to the other domain may require that Google Accounts users sign in a second time.)

To configure a URL to accept secure connections, provide a secure parameter for the handler:

handlers:

- url: /youraccount/.*
  script: accounts.py
  login: required
  secure: always

secure has 3 possible values:

  • never. Requests for a URL that match this handler that use HTTPS are automatically redirected to the HTTP equivalent URL. This is the default when secure is not provided for a handler.
  • always. Requests for a URL that match this handler that do not use HTTPS are automatically redirected to the HTTPS URL with the same path. Query parameters are preserved for the redirect.
  • optional. Both HTTP and HTTPS requests with URLs that match the handler succeed without redirects. The application can examine the request to determine which protocol was used, and respond accordingly.

When a user's HTTPS query is redirected to be an HTTP query, the query parameters are removed from the request. This prevents a user from accidentally submitting query data over a non-secure connection that was intended for a secure connection.

Secure connections use more CPU and bandwidth than non-secure connections, and are therefore more expensive. Secure connections are also slower than non-secure connections.

Any URL handler can use the secure setting, including script handlers and static file handlers.

The development web server does not support HTTPS connections. It ignores the secure parameter, so paths intended for use with HTTPS can be tested using regular HTTP connections to the development web server.

When you test your app's HTTPS handlers using the versioned appspot.com URL, such as https://1.latest.app-id.appspot.com/, your browser will warn that the HTTPS certificate was not signed for that specific domain path. If you accept the certificate for that domain, pages will load successfully. Users will not see the certificate warning when accessing https://app-id.appspot.com/.

Google Accounts sign-in and sign-out are always performed using a secure connection, unrelated to how the application's URLs are configured.

Requiring Login or Administrator Status

Any URL handler can have a login setting to restrict visitors to only those users who have signed in, or just those users who are administrators for the application. When a URL handler with a login setting matches a URL, the handler first checks whether the user has signed in to the application with a Google account. If not, the user is redirected to the Google sign-in page, and is redirected back to the application URL after signing in or creating an account.

If the setting is login: required, once the user has signed in, the handler proceeds normally.

If the setting is login: admin, once the user has signed in, the handler checks whether the user is an administrator for the application. If not, the user is given an error message. If the user is an administrator, the handler proceeds.

If an application needs different behavior, the application can implement the user handling itself. See the Users API for more information.

An example:

handlers:

- url: /profile/.*
  script: user_profile.py
  login: required

- url: /admin/.*
  script: admin.py
  login: admin

- url: /.*
  script: welcome.py

Skipping Files

Files in your application directory whose paths match a static_dir path or a static_files upload path are considered to be static files. All other files in the application directory are considered to be application program and data files.

The skip_files element specifies which files in the application directory are not to be uploaded to App Engine. The value is a regular expression. Any filename that matches the regular expression is omitted from the list of files to upload when the application is uploaded.

skip_files has the following default value:

skip_files: |
 ^(.*/)?(
 (app\.yaml)|
 (app\.yml)|
 (index\.yaml)|
 (index\.yml)|
 (#.*#)|
 (.*~)|
 (.*\.py[co])|
 (.*/RCS/.*)|
 (\..*)|
 )$

The default pattern excludes the configuration files app.yaml, app.yml, index.yaml, index.yml (configuration is sent to the server separately), Emacs backup files with names of the form #...# and ...~, .pyc and .pyo files, files in an RCS revision control directory, and Unix hidden files with names beginning with a dot (.).

If a new value is specified in app.yaml, it overrides this value. To extend this pattern, copy and paste it into your configuration with your extensions.

Referring to the Python Library Directory

You can refer to the Python library directory in an app.yaml script path using $PYTHON_LIB. This is only useful for setting up handlers whose scripts are included in the App Engine libraries.

For example, $PYTHON_LIB/google/appengine/ext/admin is an administrative application similar to the developer console feature of the development web server that can run as part of your application on App Engine itself. To set it up, include configuration for a script handler using its path:

handlers:

- url: /admin/.*
  script: $PYTHON_LIB/google/appengine/ext/admin
  login: admin

Reserved URLs

Several URL paths are reserved by App Engine for features or administrative purposes. Script handler and static file handler paths will never match these paths.

The following URL paths are reserved:

  • /_ah/
  • /form

Datastore Indexes: index.yaml

Every datastore query made by an application needs a corresponding index. Indexes for simple queries, such as queries over a single property, are created automatically. Indexes for complex queries must be defined in a configuration file named index.yaml. This file is uploaded with the application to create indexes in the datastore.

The development web server (dev_appserver.py) automatically adds items to this file when the application tries to execute a query that needs an index that does not have an appropriate entry in the configuration file. You can adjust indexes or create new ones manually by editing the file.

Tip: If during testing the app exercises every query it will make using the development web server, then the generated entries in index.yaml will be complete. You only need to edit the file manually to delete indexes that are no longer used, or to define indexes not created by the development web server.

For more information about indexes, see Queries and Indexes.

The following is an example of an index.yaml file:

indexes:

- kind: Cat
  ancestor: no
  properties:
  - name: name
  - name: age
    direction: desc

- kind: Cat
  properties:
  - name: name
    direction: asc
  - name: whiskers
    direction: desc

- kind: Store
  ancestor: yes
  properties:
  - name: business
    direction: asc
  - name: owner
    direction: asc

The syntax of index.yaml is the YAML format. For more information about this syntax, see the YAML website for more information.

Tip: The YAML format supports comments. A line that begins with a pound (#) character is ignored:
# This is a comment.

Index Definitions

index.yaml has a single list element called indexes. Each element in the list represents an index for the application.

An index element can have the following elements:

kind

The kind of the entity for the query. Typically, this is the name of the Model class that defines the model for the entities. This element is required.

properties

A list of properties to include as columns of the index, in the order to be sorted: properties used in equality filters first, followed by the property used in inequality filters, then the sort orders and their directions.

Each element in this list has the following elements:

name

The datastore name of the property.

direction

The direction to sort, either asc for ascending or desc for descending. This is only required for properties used in sort orders of the query, and must match the direction used by the query. The default is asc.

ancestor

yes if the query has an ancestor clause (either Query.ancestor() or a GQL ANCESTOR IS clause). The default is no.

Automatic and Manual Indexes

When the development web server adds a generated index definition to index.yaml, it does so below the following line, inserting it if necessary:

# AUTOGENERATED

The development web server considers all index definitions below this line to be automatic, and it may update existing definitions below this line as the application makes queries.

All index definitions above this line are considered to be under manual control, and are not updated by the development web server. The web server will only make changes below the line, and will only do so if the complete index.yaml file does not describe an index that accounts for a query executed by the application. To take control of an automatic index definition, move it above this line.