google.appengine.api.request_info module

Summary

Allows API stubs to access request and system state when handling calls.

Certain API stubs require access to information about the request that triggered the API call (e.g. user_service_stub needs to know the host name of the request to generate continuation URLs) or system state (e.g. modules_stub).

Other stubs (e.g. taskqueue_stub, channel_stub) need to be able to dispatch requests within the system.

An instance of a RequestInfo subclass is passed to stubs that require these capabilities.

Contents

exception google.appengine.api.request_info.BackgroundThreadLimitReachedErrorsource

Bases: google.appengine.api.request_info.Error

The instance is at its background thread capacity.

class google.appengine.api.request_info.Dispatchersource

Bases: object

Provides information about and dispatches requests to modules.

add_async_request(method, relative_url, headers, body, source_ip, module_name=None, version=None, instance_id=None)source

Dispatch an HTTP request asynchronously.

Parameters

• method – A str containing the HTTP method of the request.

• relative_url – A str containing path and query string of the request.

• headers – A list of (key, value) tuples where key and value are both str.

• body – A str containing the request body.

• source_ip – The source ip address for the request.

• module_name – An optional str containing the module name to service this request. If unset, the request will be dispatched to the default module.

• version – An optional str containing the version to service this request. If unset, the request will be dispatched to the default version.

• instance_id – An optional str containing the instance_id of the instance to service this request. If unset, the request will be dispatched to according to the load-balancing for the module and version.

add_event(runnable, eta, service=None, event_id=None)source

Add a callable to be run at the specified time.

Parameters

• runnable – A callable object to call at the specified time.

• eta – An int containing the time to run the event, in seconds since the epoch.

• service – A str containing the name of the service that owns this event. This should be set if event_id is set.

• event_id – A str containing the id of the event. If set, this can be passed to update_event to change the time at which the event should run.

add_request(method, relative_url, headers, body, source_ip, module_name=None, version=None, instance_id=None)source

Process an HTTP request.

Parameters

• method – A str containing the HTTP method of the request.

• relative_url – A str containing path and query string of the request.

• headers – A list of (key, value) tuples where key and value are both str.

• body – A str containing the request body.

• source_ip – The source ip address for the request.

• module_name – An optional str containing the module name to service this request. If unset, the request will be dispatched to the default module.

• version – An optional str containing the version to service this request. If unset, the request will be dispatched to the default version.

• instance_id – An optional str containing the instance_id of the instance to service this request. If unset, the request will be dispatched to according to the load-balancing for the module and version.

Returns

A ResponseTuple containing the response information for the HTTP request.

get_default_version(module)source

Returns the default version for a module.

Parameters

module – A str containing the name of the module.

Returns

A str containing the default version for the specified module.

Raises

ModuleDoesNotExistError – The module does not exist.

get_hostname(module, version, instance=None)source

Returns the hostname for a (module, version, instance) tuple.

If instance is set, this will return a hostname for that particular instances. Otherwise, it will return the hostname for load-balancing.

Parameters

• module – A str containing the name of the module.

• version – A str containing the version.

• instance – An optional str containing the instance ID.

Returns

A str containing the hostname.

Raises

• ModuleDoesNotExistError – The module does not exist.

• VersionDoesNotExistError – The version does not exist.

• InvalidInstanceIdError – The instance ID is not valid for the module/version or the module/version uses automatic scaling.

get_module_names()source

Returns a list of module names.

get_num_instances(module, version)source

Gets the number of instances running for a version of a module.

Parameters

• module – A str containing the name of the module.

• version – A str containing the version.

Raises

• ModuleDoesNotExistError – The module does not exist.

• VersionDoesNotExistError – The version does not exist.

• NotSupportedWithAutoScalingError – The provided module/version uses automatic scaling.

get_versions(module)source

Returns a list of versions for a module.

Parameters

module – A str containing the name of the module.

Returns

A list of str containing the versions for the specified module.

Raises

ModuleDoesNotExistError – The module does not exist.

send_background_request(module_name, version, instance, background_request_id)source

Dispatch a background thread request.

Parameters

• module_name – A str containing the module name to service this request.

• version – A str containing the version to service this request.

• instance – The instance to service this request.

• background_request_id – A str containing the unique background thread request identifier.

Raises

• NotSupportedWithAutoScalingError – The provided module/version uses automatic scaling.

• BackgroundThreadLimitReachedError – The instance is at its background thread capacity.

set_num_instances(module, version, instances)source

Sets the number of instances to run for a version of a module.

Parameters

• module – A str containing the name of the module.

• version – A str containing the version.

• instances – An int containing the number of instances to run.

Raises

• ModuleDoesNotExistError – The module does not exist.

• VersionDoesNotExistError – The version does not exist.

• NotSupportedWithAutoScalingError – The provided module/version uses automatic scaling.

start_version(module, version)source

Starts a version.

Parameters

• module – A str containing the name of the module.

• version – A str containing the version.

Raises

• ModuleDoesNotExistError – The module does not exist.

• VersionDoesNotExistError – The version does not exist.

• NotSupportedWithAutoScalingError – The provided module/version uses automatic scaling.

stop_version(module, version)source

Stops a version.

Parameters

• module – A str containing the name of the module.

• version – A str containing the version.

Raises

• ModuleDoesNotExistError – The module does not exist.

• VersionDoesNotExistError – The version does not exist.

• NotSupportedWithAutoScalingError – The provided module/version uses automatic scaling.

update_event(eta, service, event_id)source

Update the eta of a scheduled event.

Parameters

• eta – An int containing the time to run the event, in seconds since the epoch.

• service – A str containing the name of the service that owns this event.

• event_id – A str containing the id of the event to update.

exception google.appengine.api.request_info.Errorsource

Bases: exceptions.Exception

exception google.appengine.api.request_info.InvalidInstanceIdErrorsource

Bases: google.appengine.api.request_info.Error

The provided instance ID is invalid.

exception google.appengine.api.request_info.ModuleDoesNotExistErrorsource

Bases: google.appengine.api.request_info.Error

The provided module does not exist.

exception google.appengine.api.request_info.NotSupportedWithAutoScalingErrorsource

Bases: google.appengine.api.request_info.Error

The requested operation is not supported for auto-scaling modules.

class google.appengine.api.request_info.RequestInfosource

Bases: object

Allows stubs to lookup state linked to the request making the API call.

get_dispatcher()source

Returns the Dispatcher.

Returns

The Dispatcher instance.

get_instance(request_id)source

Returns the instance serving this request.

Parameters

request_id – The string id of the request making the API call.

Returns

An opaque representation of the instance serving this request. It should only be passed to dispatcher methods expecting an instance.

get_module(request_id)source

Returns the name of the module serving this request.

Parameters

request_id – The string id of the request making the API call.

Returns

A str containing the module name.

get_request_environ(request_id)source

Returns a dict containing the WSGI environ for the request.

get_request_url(request_id)source

Returns the URL the request e.g. ‘http://localhost:8080/foo?bar=baz’.

Parameters

request_id – The string id of the request making the API call.

Returns

The URL of the request as a string.

get_version(request_id)source

Returns the version of the module serving this request.

Parameters

request_id – The string id of the request making the API call.

Returns

A str containing the version.

register_request_id(environ, request_id)source

Registers a simulated HTTP request from the dev_appserver.

Subclasses are not required to provide an implementation.

Parameters

• environ – An environ dict for the request as defined in PEP-333.

• request_id – The string id of the request making the API call.

class google.appengine.api.request_info.ResponseTuple(status, headers, content)source

Bases: tuple

content

Alias for field number 2

headers

Alias for field number 1

status

Alias for field number 0

exception google.appengine.api.request_info.VersionAlreadyStartedErrorsource

Bases: google.appengine.api.request_info.Error

The version is already started.

exception google.appengine.api.request_info.VersionAlreadyStoppedErrorsource

Bases: google.appengine.api.request_info.Error

The version is already stopped.

exception google.appengine.api.request_info.VersionDoesNotExistErrorsource

Bases: google.appengine.api.request_info.Error

The provided version does not exist.