The Queue class may be used to prepare Tasks for offline execution by App Engine.

Queue is provided by the google.appengine.api.taskqueue module.

1. Introduction
2. Queue()
3. Properties
   • name
4. Instance methods:
   • add()
   • add_async()
   • delete_tasks()
   • delete_tasks_async()
   • delete_tasks_by_name()
   • delete_tasks_by_name_async()
   • fetch_statistics()
   • fetch_statistics_async()
   • lease_tasks()
   • lease_tasks_async()
   • lease_tasks_by_tag()
   • lease_tasks_by_tag_async()
   • modify_task_lease()
   • purge()

Introduction

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 . The Queue object may then be used to insert new Task instances for offline execution by App Engine.

Multiple Queue objects may correspond to the same underlying system queue. However, a single Task object may only be added to one Queue.

Constructor

class Queue ( name ='default')

Instantiates a Queue object which corresponds to either the default queue (automatically available to all applications) or a user-created queue defined in queue.yaml . Once instantiated, a Queue object may be used to insert new Tasks into the system for offline execution.

Arguments

name:

Optional. The name of this Queue. Must correspond to a user-defined queue name from queue.yaml. Alternatively, if not specified, the Queue instance will correspond to the automatic default queue.

Properties

A Queue instance has the following properties:

name

The name of this Queue, either default (if the default queue ) or a user-defined value corresponding to an active queue in queue.yaml .

Instance Methods

A Queue instance has the following methods:

add ( task , transactional = False )

Add a Task or a list of Tasks to this Queue.

Arguments

task

The Task to add, or a list of Task objects to add.

If task is a list of Task objects, all tasks are added to the queue. If transactional = True , then all of the tasks are added in the same active Datastore transaction, and if any of the tasks cannot be enqueued, none of the tasks are enqueued and the Datastore transaction fails. If transactional = False , a failure to enqueue any task will raise an exception, but other tasks may be enqueued successfully.

transactional = False

Relevant when this method is called inside db.run_in_transaction() . Indicates that this transactional task should be added only if an enclosing Datastore transaction is applied successfully. Note that this task must not have a user-specified name in this case. Also, you need to call get_result on the RPC object before committing the transaction: this ensures that the add request has finished.

The return value is the Task or list of tasks that was supplied to this method.

If any Task has already been added to a queue, this method raises a BadTaskStateError .

If transactional = True , but this method is not called during a Datastore transaction, is raises a BadTransactionStateError .

If the list of Task objects exceeds the limit for tasks added in a bulk call (see Quotas and Limits ), this method raises a TooManyTasksError .

If the list of Task objects contains two tasks with the same name, this method raises a DuplicateTaskNameError .

add_async ( task , transactional = False , rpc = None )

Asynchronously add a Task or a list of Tasks to this Queue.

Arguments

task

The Task to add, or a list of Task objects to add.

If task is a list of Task objects, all tasks are added to the queue. If transactional = True , then all of the tasks are added in the same active Datastore transaction, and if any of the tasks cannot be enqueued, none of the tasks are enqueued and the Datastore transaction fails. If transactional = False , a failure to enqueue any task will raise an exception, but other tasks may be enqueued successfully.

transactional = False

Relevant when this method is called inside db.run_in_transaction() . Indicates that this transactional task should be added only if an enclosing Datastore transaction is applied successfully. Note that this task must not have a user-specified name in this case.

rpc

The RPC object used for asynchronous operation.

The return value is an RPC object on which you can call get_result() to obtain the task or list of tasks.

If any Task has already been added to a queue, this method raises a BadTaskStateError .

If transactional = True , and this method is not called during a Datastore transaction, it raises a BadTransactionStateError .

If the list of Task objects exceeds the limit for tasks added in a bulk call (see Quotas and Limits ), this method raises a TooManyTasksError .

If the list of Task objects contains two tasks with the same name, this method raises a DuplicateTaskNameError .

delete_tasks ( task )

Deletes a Task or list of Tasks in this Queue. Task name is the only task attribute used to select tasks for deletion. If there is any task with was_deleted property set to True, or without a task name, a BadTaskStateError is raised immediately.

Arguments

task

A Task or a list of Tasks to delete from the Queue.

delete_tasks_async ( task , rpc = None )

Asynchronously deletes a Task or list of Tasks in this Queue. Task name is the only task attribute used to select tasks for deletion. If there is any task with was_deleted property set to True, or without a task name, a BadTaskStateError is raised immediately.

Arguments

task

A Task or a list of Tasks to delete from the Queue.

rpc

The RPC object used for asynchronous operation.

delete_tasks_by_name ( task_name )

Deletes a Task or list of Tasks in this Queue by name. If a Task name is repeated in the request, a DuplicateTaskNameError is raised.

Arguments

task_name

The name of the Task or a list of task names to delete from the Queue.

Result value

If a list of task names is provided as input, this call returns a list 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. If a single task name was provided as input, a single Task object.

delete_tasks_by_name_async ( task_name , rpc = None )

Asynchronously deletes a Task or list of Tasks in this Queue by name. If a Task name is repeated in the request, a DuplicateTaskNameError is raised. If the tasks to be deleted do not have task names or have already been deleted, a BadTaskStateError is raised.

Arguments

task_name

The name of the Task or a list of task names to delete from the Queue.

rpc

The RPC object used for asynchronous operation.

Result value

The return value is an RPC object on which you can call get_result() to obtain the deleted task or list of tasks (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.

fetch_statistics ( deadline = 10 )

Returns a QueueStatistics instance containing information about this queue.

Arguments

deadline

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

Result value

A QueueStatistics instance containing information about this queue

fetch_statistics_async ( rpc = None )

Asynchronously gets the current details about this queue.

Arguments

rpc

The RPC object used for asynchronous operation.

Result value

An RPC object on which you can call get_result() to obtain information about this queue.

lease_tasks ( lease_seconds , max_tasks , deadline = 10 )

Leases a number of tasks from the Queue for a period of time. This method can only be performed on a pull Queue. Attempts to lease tasks from a push Queue result in a InvalidQueueModeError . All non-pull tasks in the pull Queue will be converted into pull tasks when leased. If fewer than max_tasks are available, all available tasks are returned. The lease_tasks method supports leasing at most 1000 tasks for no longer than a week in a single call.

Arguments

lease_seconds

Number of seconds to lease this task, 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 1,000 tasks.

deadline

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

Result value

A list of tasks leased from the Queue.

lease_tasks_async ( lease_seconds , max_tasks , rpc = None )

Asynchronously leases a number of tasks from the Queue for a period of time. This method can only be performed on a pull Queue. Attempts to lease tasks from a push Queue result in a InvalidQueueModeError . All non-pull tasks in the pull Queue will be converted into pull tasks when leased. If fewer than max_tasks are available, all available tasks are returned. The lease_tasks_async method supports leasing at most 1000 tasks for no longer than a week in a single call.

Arguments

lease_seconds

Number of seconds to lease this task, 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 1,000 tasks.

rpc

The RPC object used for asynchronous operation.

Result value

An RPC object on which you can call get_result() to obtain the list of tasks leased from the Queue.

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

Leases up to a specified number of tasks with the same tag from the queue for a specified period of time. If a tag is specified, leases tasks with that tag. If a tag is not specified, uses the tag of the queue's "oldest" task (by eta ). Returns a list of leased tasks.

Note: Applies only to pull queues. Any non-pull tasks will be converted into pull tasks when being leased by tag.

Exceptions

InvalidLeaseTimeError

if lease_seconds is not a valid float or integer number, or is outside the value 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 a pull queue.

Result value

A list of tasks leased from the Queue.

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

Leases up to a specified number of tasks with the same tag from the queue for a specified period of time. If a tag is specified, leases tasks with that tag. If a tag is not specified, uses the tag of the queue's "oldest" task (by eta ). Returns a list of leased tasks.

Note: Applies only to pull queues. Any non-pull tasks will be converted into pull tasks when being leased by tag.

Exceptions

InvalidLeaseTimeError

if lease_seconds is not a valid float or integer number, or is outside the value 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 a pull queue.

Result value

An RPC object on which you can call get_result() to obtain the list of tasks leased from the Queue.

modify_task_lease ( task , lease_seconds )

Modifies the lease of a task in this queue.

Arguments

task

The task instance whose lease you wish to modify.

lease_seconds

Number of seconds to lease this task, up to one week (604,800 seconds). Must not be negative. Setting lease_seconds to 0 removes the task lease, making the task available for leasing again using lease_tasks() .

Raises a TypeError if lease_seconds is not a valid float or integer. Raises an InvalidLeaseTimeError if lease_seconds is outside of the valid range.

purge ()

Removes all tasks from this queue. Purging the queue takes about 20 seconds, regardless of the queue size. Tasks continue executing during this time, until the backends recognize that the queue has been purged.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .