Python 3.9 is now generally available.


Maps from URLs to handlers.

Inherits From: HandlerBase, Validated, ValidatedBase, expected_type

This class acts similar to a union type. Its purpose is to describe a mapping between a set of URLs and their handlers. The handler type of a given instance is determined by which handler-id attribute is used.

Every mapping can have one and only one handler type. Attempting to use more than one handler-id attribute will cause an UnknownHandlerType to be raised during validation. Failure to provide any handler-id attributes will cause MissingHandlerType to be raised during validation.

The regular expression used by the url field will be used to match against the entire URL path and query string of the request; therefore, partial maps will not be matched. Specifying a url, such as /admin, is the same as matching against the regular expression ^/admin$. Don't start your matching url with ^ or end them with $. These regular expressions won't be accepted and will raise ValueError.

Special cases:

When defining a static_dir handler, do not use a regular expression in the url attribute. Both the url and static_dir attributes are automatically mapped to these equivalents::


For example, this declaration...::

url: /images
static_dir: images_folder equivalent to this static_files declaration::

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

AttributeDefinitionError When class instance is missing ATTRIBUTE definition or when ATTRIBUTE is of the wrong type.

login Specifies whether a user should be logged in to access a URL. The default value of this argument is optional.
secure Sets the restriction on the protocol that can be used to serve this URL or handler. This value can be set to HTTP, HTTPS or either.
url Specifies a regular expression that is used to fully match against the request URLs path. See the "Special cases" section of this document to learn more.
static_files Specifies the handler ID attribute that maps url to the appropriate file. You can specify regular expression backreferences to the string matched to url.
upload Specifies the regular expression that is used by the application configuration program to determine which files are uploaded as blobs. Because it is difficult to determine this information using just the url and static_files arguments, this attribute must be included. This attribute is required when you define a static_files mapping. A matching file name must fully match against the upload regular expression, similar to how url is matched against the request path. Do not begin the upload argument with the ^ character or end it with the $ character.
static_dir Specifies the handler ID that maps the provided url to a sub-directory within the application directory. See "Special cases."
mime_type When used with static_files and static_dir, this argument specifies that the MIME type of the files that are served from those directories must be overridden with this value.
script Specifies the handler ID that maps URLs to a script handler within the application directory that will run using CGI.
position Used in AppInclude objects to specify whether a handler should be inserted at the beginning of the primary handler list or at the end. If tail is specified, the handler is inserted at the end; otherwise, the handler is inserted at the beginning. This behavior implies that head is the effective default.
expiration When used with static files and directories, this argument specifies the time delta to use for cache expiration. This argument should use the following format: 4d 5h 30m 15s, where each letter signifies days, hours, minutes, and seconds, respectively. The s for "seconds" can be omitted. Only one amount must be specified, though combining multiple amounts is optional. The following list contains examples of values that are acceptable: 10, 1d 6h, 1h 30m, 7d 7d 7d, 5m 30.
api_endpoint Specifies the handler ID that identifies an endpoint as an API endpoint. Calls that terminate here will be handled by the API serving framework.



View source

Makes sure that self.http_headers is consistent with self.mime_type.

This method assumes that self is a static handler, either self.static_dir or self.static_files. You cannot specify None.

appinfo_errors.ContentTypeSpecifiedMultipleTimes If self.http_headers contains a Content-Type header, and self.mime_type is set. For example, the following configuration would be rejected::


  - url: /static
    static_dir: static
    mime_type: text/html
      content-type: text/html

As this example shows, a configuration will be rejected when http_headers and mime_type specify a content type, even when they specify the same content type.


View source

Adds additional checking to make sure a handler has correct fields.

In addition to normal ValidatedCheck, this method calls GetHandlerType, which validates whether all of the handler fields are configured properly.

UnknownHandlerType If none of the handler ID attributes are set.
UnexpectedHandlerAttribute If an unexpected attribute is set for the discovered handler type.
HandlerTypeMissingAttribute If the handler is missing a required attribute for its handler type.
ContentTypeSpecifiedMultipleTimes If mime_type is inconsistent with http_headers.


View source

Raises an error if position is specified outside of AppInclude objects.

PositionUsedInAppYamlHandler If the position attribute is specified for an app.yaml file instead of an include.yaml file.


View source

Forces omitted secure handler fields to be set to 'secure: optional'.

The effect is that is never equal to the nominal default.


View source

Get a single value on Validated instance.

This method can only be used to retrieve validated attributes.

key The name of the attributes

ValidationError when no validated attribute exists on class.


View source

Gets the handler for a mapping.

The value of the handler, as determined by the handler ID attribute.


View source

Gets the handler type of a mapping.

The handler type as determined by which handler ID attribute is set.

UnknownHandlerType If none of the handler ID attributes are set.
UnexpectedHandlerAttribute If an unexpected attribute is set for the discovered handler type.
HandlerTypeMissingAttribute If the handler is missing a required attribute for its handler type.
MissingHandlerAttribute If a URL handler is missing an attribute.


View source

Get a single value on the Validated instance, without normalizing.


View source

Safely get the underlying attribute definition as a Validator.

key Name of attribute to get.

Validator associated with key or attribute value wrapped in a validator.

ValidationError if no such attribute exists.


View source

Return all the warnings we've got, along with their associated fields.

A list of tuples of (dotted_field, warning), both strings.


View source

Short human-readable representation.


View source

Set a single value on Validated instance.

This method can only be used to assign validated attributes.

key The name of the attributes
value The value to set

ValidationError when no validated attribute exists on class.


View source

Set multiple values on Validated instance.

All attributes will be validated before being set.

attributes A dict of attributes/items to set.

ValidationError When no validated attribute exists on class.


View source

Convert Validated object to a dictionary.

Recursively traverses all of its elements and converts everything to simplified collections.

A dict of all attributes defined in this classes ATTRIBUTES mapped to its value. This structure is recursive in that Validated objects that are referenced by this object and in lists are also converted to dicts.


View source

Print validated object as simplified YAML.

Object as a simplified YAML string compatible with parsing using the SafeLoader.


View source

Generates a warning for reserved URLs.

See the version element documentation_ to learn which URLs are reserved.

.. _version element documentation:


View source

Equality operator.

Comparison is done by comparing all attribute values to those in the other instance. Objects which are not of the same type are not equal.

other Other object to compare against.

True if validated objects are equal, else False.


View source

Inequality operator.


 'api_endpoint': ('position', 'script'),
 'script': 'position',
 'static_dir': ('mime_type', 'expiration', 'require_matching_file', 'http_headers', 'application_readable'),
 'static_files': ('mime_type', 'upload', 'expiration', 'require_matching_file', 'http_headers', 'application_readable')


 'api_endpoint': <google.appengine.api.validation.Optional object at 0x7ff881260910>,
 'application_readable': <google.appengine.api.validation.Optional object at 0x7ff881260190>,
 'auth_fail_action': <google.appengine.api.validation.Options object at 0x7ff881254bb0>,
 'expiration': <google.appengine.api.validation.Optional object at 0x7ff8812603d0>,
 'http_headers': <google.appengine.api.validation.Optional object at 0x7ff8812607c0>,
 'login': <google.appengine.api.validation.Options object at 0x7ff881254b80>,
 'mime_type': <google.appengine.api.validation.Optional object at 0x7ff881260310>,
 'position': <google.appengine.api.validation.Optional object at 0x7ff8812606d0>,
 'redirect_http_response_code': <google.appengine.api.validation.Optional object at 0x7ff881260820>,
 'require_matching_file': <google.appengine.api.validation.Optional object at 0x7ff8812605e0>,
 'script': <google.appengine.api.validation.Optional object at 0x7ff881254d30>,
 'secure': <google.appengine.api.validation.Options object at 0x7ff881254d90>,
 'static_dir': <google.appengine.api.validation.Optional object at 0x7ff881260250>,
 'static_files': <google.appengine.api.validation.Optional object at 0x7ff881254f70>,
 'upload': <google.appengine.api.validation.Optional object at 0x7ff8812600d0>,
 'url': <google.appengine.api.validation.Optional object at 0x7ff881254d00>