English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# The Queue Class

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.

- Introduction
- Queue()
- Properties
  - name
- Instance methods:
  - add()
  - delete_tasks()
  - lease_tasks()
  - lease_tasks_by_tag()
  - modify_task_lease()
  - purge()

## Introduction

A Queue object is instantiated by nam. 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.

  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.

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.
lease_tasks(lease_seconds, max_tasks)

  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.

lease_tasks_by_tag(lease_seconds, max_tasks, tag=None)

  Leases up to a specified number of tasks from the queue for a specified period of time. If a `tag` is specified, queries for tasks with that tag. 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.

  Raises:

  `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.
modify_task_lease(lease_seconds, max_tasks)

  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.