google.appengine.api.taskqueue package

A queue object is instantiated by name. The name must correspond either to the default queue (provided by the system) or a user-defined queue as specified in the application’s queue.yaml configuration file. The queue object can then be used to insert new task instances for offline execution by App Engine.

Multiple queue objects can correspond to the same underlying system queue. However, a single task object can only be added to one queue.

delete_tasks(task)source

Deletes a task or list of tasks in this queue.

When multiple tasks are specified, an exception will be raised if any individual task fails to be deleted. Check the task.was_deleted property.

The task name is the only task attribute that is used to select tasks for deletion. If any task exists that is unnamed or with the was_deleted property set to True, a BadTaskStateError will be raised immediately.

Parameters

task – A task instance or a list of task instances that will be deleted from the queue.

Returns

The task or list of tasks passed into this call.

Raises

BadTaskStateError – If the tasks to be deleted do not have task names or have already been deleted.
DuplicateTaskNameError – If a task is repeated in the request.
Error-subclass on application errors.

delete_tasks_async(task, rpc=None)source

Asynchronously deletes a task or list of tasks in this queue.

The task name is the only task attribute that is used to select tasks for deletion.

This function is identical to delete_tasks() except that it returns an asynchronous object. You can call get_result() on the return value to block on the call.

Parameters

task – A task instance or a list of task instances that will be deleted from the queue.
rpc – An optional UserRPC object.

Returns

A UserRPC object. Call get_result() to complete the RPC and obtain the task or list of tasks passed into this call.

Raises

BadTaskStateError – If the tasks to be deleted do not have task names or have already been deleted.
DuplicateTaskNameError – If a task is repeated in the request.

delete_tasks_by_name(task_name)source

Deletes a task or list of tasks in this queue, by name.

When multiple tasks are specified, an exception will be raised if any individual task fails to be deleted.

Parameters

task_name – A string corresponding to a task name, or an iterable of strings corresponding to task names.

Returns

If an iterable, other than string, is provided as input, a list of task objects is returned, one for each task name in the order requested. The Task.was_deleted property will be True for each task deleted by this call, and will be False for unknown and tombstoned tasks.

Otherwise, if a single string was provided as input, a single task object is returned.

Raises

DuplicateTaskNameError – If a task name is repeated in the request.
Error-subclass on application errors.

delete_tasks_by_name_async(task_name, rpc=None)source

Asynchronously deletes a task or list of tasks in this queue, by name.

This function is identical to delete_tasks_by_name() except that it returns an asynchronous object. You can call get_result() on the return value to block on the call.

Parameters

task_name – A string corresponding to a task name, or an iterable of strings corresponding to task names.
rpc – An optional UserRPC object.

Returns

A UserRPC object. Call get_result() to complete the RPC and obtain the result.

If an iterable, other than string, is provided as input, the result will be a list of of task objects, one for each task name in the order requested. The Task.was_deleted property will be True for each task deleted by this call, and will be False for unknown and tombstoned tasks.

Otherwise, if a single string was provided as input, then the result will be a single task object.

Raises

DuplicateTaskNameError – If a task name is repeated in the request.

fetch_statistics(deadline=10)source

Gets the current details about this queue.

Parameters

deadline – The maximum number of seconds to wait before aborting the method call.

Returns

A QueueStatistics instance that contains information about this queue. Error-subclass on application errors.

fetch_statistics_async(rpc=None)source

Asynchronously gets the current details about this queue.

Parameters

rpc – An optional UserRPC object.

Returns

A UserRPC object. Call get_result() to complete the RPC and obtain a QueueStatistics instance that contains information about this queue.

lease_tasks(lease_seconds, max_tasks, deadline=10)source

Leases a number of tasks from the queue for a period of time.

This method can only be performed on a pull queue. Any non-pull tasks in the pull queue will be converted into pull tasks when being leased. If fewer than the specified number of max_tasks are available, all available tasks will be returned. The lease_tasks method supports leasing at most 1000 tasks for no longer than a week in a single call.

Parameters

lease_seconds – Number of seconds to lease the tasks, up to one week (604,800 seconds). Must be a positive integer.
max_tasks – The maximum number of tasks to lease from the pull queue, up to 1000 tasks.
deadline – The maximum number of seconds to wait before aborting the method call.

Returns

A list of tasks leased from the queue.

Raises

InvalidLeaseTimeError – If lease_seconds is not a valid float or integer number or is outside the valid range.
InvalidMaxTasksError – If max_tasks is not a valid integer or is outside the valid range.
InvalidQueueModeError – If invoked on a queue that is not in pull mode.
Error-subclass on application errors.

lease_tasks_async(lease_seconds, max_tasks, rpc=None)source

Asynchronously leases a number of tasks from the queue.

This method can only be performed on a pull queue. Attempts to lease tasks from a push queue results in an InvalidQueueModeError. All non-pull tasks in the pull queue will be converted into pull tasks when leased. If fewer than the specified value of max_tasks are available, all available tasks on a best-effort basis are returned. The lease_tasks_async method supports leasing at most 1000 tasks for no longer than a week in a single call.

This function is identical to lease_tasks() except that it returns an asynchronous object. You can call get_result() on the return value to block on the call.

Parameters

lease_seconds – Number of seconds to lease the tasks, up to one week (604,800 seconds). Must be a positive integer.
max_tasks – Maximum number of tasks to lease from the pull queue, up to 1000 tasks.
rpc – An optional UserRPC object.

Returns

A UserRPC object. Call get_result() to complete the RPC and obtain the list of tasks leased from the queue.

Raises

InvalidLeaseTimeError – If lease_seconds is not a valid float or integer number or is outside the valid range.
InvalidMaxTasksError – If max_tasks is not a valid integer or is outside the valid range.

lease_tasks_by_tag(lease_seconds, max_tasks, tag=None, deadline=10)source

Leases tasks with the same tag from the queue.

If a tag is specified, tasks with that tag are leased for a specified period of time. If a tag is not specified, the tag of the queue’s oldest task (specified by the eta) will be used.

This method can only be performed on a pull queue. Any non-pull tasks in the pull queue will be converted into pull tasks when being leased. If fewer than the specified value of max_tasks are available, all available tasks will be returned. The lease_tasks method supports leasing at most 1000 tasks for no longer than a week in a single call.

Parameters

lease_seconds – Number of seconds to lease the tasks.
max_tasks – The maximum number of tasks to lease from the pull queue.
tag – The tag to query for, or None to group by the first available tag.
deadline – The maximum number of seconds to wait before aborting the method call.

Returns

A list of tasks leased from the queue.

Raises

InvalidLeaseTimeError – If lease_seconds is not a valid float or integer number or is outside the valid range.
InvalidMaxTasksError – If max_tasks is not a valid integer or is outside the valid range.
InvalidQueueModeError – If invoked on a queue that is not in pull mode.
Error-subclass on application errors.

lease_tasks_by_tag_async(lease_seconds, max_tasks, tag=None, rpc=None)source

Asynchronously leases tasks with the same tag from the queue.

If a tag is specified, tasks with that tag are leased for a specified period of time. If a tag is not specified, the best-effort oldest tag of the queue’s oldest task (specified by the eta) will be used.

This function is identical to lease_tasks_by_tag() except that it returns an asynchronous object. You can call get_result() on the return value to block on the call.

Parameters

lease_seconds – Number of seconds to lease the tasks.
max_tasks – The maximum number of tasks to lease from the pull queue.
tag – The tag to query for, or None to group by the first available tag.
rpc – An optional UserRPC object.

Returns

A UserRPC object. Call get_result() to complete the RPC and obtain the list of tasks leased from the queue.

Raises

InvalidLeaseTimeError – If lease_seconds is not a valid float or integer number or is outside the valid range.
InvalidMaxTasksError – If max_tasks is not a valid integer or is outside the valid range.

modify_task_lease(task, lease_seconds)source

Modifies the lease of a task in this queue.

Parameters

task – A task instance that will have its lease modified.
lease_seconds – Number of seconds, from the current time, that the task lease will be modified to. If lease_seconds is 0, the task lease is removed and the task will be available for leasing again using the lease_tasks method.

Raises

TypeError – If lease_seconds is not a valid float or integer.
InvalidLeaseTimeError – If lease_seconds is outside of the valid range.
Error-subclass on application errors.

name: Returns the name of this queue.

purge()source

Removes all of the tasks in this queue.

Purging the queue takes time, regardless of the queue size. Tasks continue to run until the backends recognize that the queue has been purged. This operation is permanent; purged tasks cannot be recovered.

Raises

Error-subclass on application errors.

class google.appengine.api.taskqueue.QueueStatistics(queue, tasks, oldest_eta_usec=None, executed_last_minute=None, in_flight=None, enforced_rate=None)source

Bases: object

Represents the current state of a queue.

classmethod fetch(queue_or_queues, deadline=10)source

Get the queue details for multiple queues.

Use QueueStatistics.fetch() to get QueueStatistics objects for the queues you are interested in. You can specify one or more queues.

Example:

statsList = taskqueue.QueueStatistics.fetch([taskqueue.Queue("foo"),
                                             taskqueue.Queue("bar")])

Parameters

queue_or_queues – The queue or list of queues for which you are obtaining statistics. If you are retrieving statistics for a single queue, you can supply either a queue instance or the name of the queue. If you are retrieving statistics for a list of queues, you can supply an iterable list of queue instances or an iterable list of queue names.
deadline – The maximum number of seconds to wait before aborting the method call.

Returns

If an iterable (other than string) is provided as input, a list of of QueueStatistics objects will be returned, one for each queue in the order requested.

Otherwise, if a single item was provided as input, then a single QueueStatistics object will be returned.

Raises

TypeError – If queue_or_queues is not a queue instance, string, an iterable containing only queue instances, or an iterable containing only strings.
Error-subclass on application errors.

classmethod fetch_async(queue_or_queues, rpc=None)source

Asynchronously get the queue details for multiple queues.

Example:

rpc = taskqueue.create_rpc(deadline=1.0)
taskqueue.QueueStatistics.fetch_async([taskqueue.Queue("foo"),
                                        taskqueue.Queue("bar")], rpc)
statsList = rpc.get_result()

Parameters

queue_or_queues – The queue or list of queues for which you are obtaining statistics. If you are retrieving statistics for a single queue, you can supply either a queue instance or the name of the queue. If you are retrieving a list of queues, you can supply an iterable list of queue instances or an iterable list of queue names.
rpc – An optional UserRPC object.

Returns

A UserRPC object. Call get_result() to complete the RPC and obtain the result.

If an iterable (other than string) is provided as input, the result will be a list of of QueueStatistics objects, one for each queue in the order requested.

Otherwise, if a single item was provided as input, then the result will be a single QueueStatistics object.

Raises

TypeError – If queue_or_queues is not a queue instance, string, an iterable containing only queue instances, or an iterable containing only strings.

class google.appengine.api.taskqueue.Task(payload=None, **kwargs)source

Bases: object

Represents a single task on a queue.

The Task class enables an application to queue background work. Work is done through webhooks that process tasks pushed from a push queue, or workers that manually pull tasks from a pull queue.

In push queues, most tasks are delivered in best-effort order of ETA.

Webhooks that fail cause tasks to be retried at a later time. You can configure the rate and number of retries for failed tasks. You can specify webhook URLs directly for push tasks. You can also use the default URL scheme, which translates task names into URLs that are relative to a queue’s base path. A default queue is also provided for simple usage.

In pull queues, workers are responsible for leasing tasks, processing them, and deleting them after processing. You can configure the number of task retries, which is based on how many times the task has been leased. You can define multiple queues with independent throttling controls.

You set the various properties for a task in the constructor. Once the Task object is instantiated, you insert that task into a queue. A task instance can be inserted into one queue only.

eta: Returns a datetime.datatime when this task will run or be leased.

eta_posix: Returns a POSIX timestamp of when this task will run or be leased.

extract_params()source

Returns the parameters for this task.

If the same name parameter has several values, then the value is a list of strings. For POST requests and pull tasks, the parameters are extracted from the task payload; for all other methods, the parameters are extracted from the URL query string.

Returns

A dictionary of strings that map parameter names to their values as strings. If the same name parameter has several values, the value will be a list of strings. For POST requests and pull tasks, the parameters are extracted from the task payload. For all other methods, the parameters are extracted from the URL query string. An empty dictionary is returned if the task contains an empty payload or query string.

Raises

ValueError – If the payload does not contain valid application/x-www-form-urlencoded data (for POST requests and pull tasks) or the URL does not contain a valid query (all other requests).

method: Returns the method to use for this task.

name: Returns the name of this task.

on_queue_url: Returns True if task runs on queue’s default URL (push tasks only).

queue_name: Returns the name of the queue with which this task is associated.

retry_count: Returns the number of retries or leases attempted on the task.

retry_options: Returns any or all the TaskRetryOptions tasks.

size: Returns the size of this task in bytes.

tag: Returns the tag for this task.

target: Returns the target for this task.

url: Returns the relative URL for this task (push tasks only).

was_deleted: Returns True if this task was successfully deleted.

was_enqueued: Returns True if this task has been inserted into a queue.

class google.appengine.api.taskqueue.TaskRetryOptions(**kwargs)source

Bases: object

The options used to decide when a failed task will be retried.

Tasks executing in the task queue can fail for many reasons. If a task fails to execute, which is indicated by returning any HTTP status code outside of the range 200-299, App Engine retries the task until it succeeds. By default, the system gradually reduces the retry rate to avoid flooding your application with too many requests, but schedules retry attempts to recur at a maximum of once per hour until the task succeeds. 503 errors, however, are treated as special cases and should not be returned by user code.

The TaskRetryOptions class provides the properties that you can use to decide when to retry a failed task at runtime.

max_backoff_seconds: The maximum number of seconds to wait before retrying a task.

max_doublings: The number of times that the retry interval will be doubled.

min_backoff_seconds: The minimum number of seconds to wait before retrying a task.

task_age_limit: The number of seconds after which a failed task will not be retried.

task_retry_limit: The number of times that a failed task will be retried.

google.appengine.api.taskqueue.create_rpc(deadline=None, callback=None)source

Creates an RPC object for use with the Task Queue API.

Parameters

deadline – Optional deadline in seconds for the operation; the default value is a system-specific deadline, which is typically 5 seconds. After the deadline, a DeadlineExceededError error will be returned.
callback – Optional function to be called with the Task Queue service returns results successfully when get_result(), check_success(), or wait() is invoked on the RPC object. The function is called without arguments. The function is not called in a background process or thread; the function is only called when one of the above methods is called by the application. The function is called even if the request fails or the RPC deadline elapses.

Returns

An apiproxy_stub_map.UserRPC object specialized for this service.

google.appengine.api.taskqueue package

Summary

Sub Modules

Contents