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

# 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, Tasks execute 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 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.

`Task` is provided by the `google.appengine.api.taskqueue` module.

- Introduction
- Task()
- Properties
  - eta
  - eta_posix
  - headers
  - method
  - name
  - on_queue_url
  - payload
  - size
  - retry_count
  - retry_options
  - tag
  - target
  - url
  - was_enqueued
  - was_deleted
- Instance methods:
  - add
  - extract_params
  - lease_tasks_by_tag()

## Introduction

The Task class encapsulates a description of offline work in a push queue or a pull queue. In push queues, this work is modeled as a web hook and includes a URL endpoint in your application, and an optional task payload.

In pull queues, the task's payload is fetched from the queue by the task consumer when the task is leased.

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.

## Constructor

class Task (payload=None, **kw)

  Instantiates a Task object which describes a unit of offline work. The instance may be inserted into a push or pull queue for processing based on the requirements of the application.

  All arguments are optional. Some arguments have different meanings in push queues and pull queues. The following table summarizes the meaning of each argument in each type of queue.

  Task class argument | Description | Functionality in Push Queues | Functionality in Pull Queues
  --- | --- | --- | ---
  `payload` | The data payload providing the parameters for this task's work. Allowed only for `POST`, `PUT`, and `PULL` methods. | Payload is delivered to the webhook or backend in the body of an HTTP request. | Payload is fetched by workers as part of the response from lease_tasks().
  `name` | The task's name. | If you don't specify a task name, App Engine auto-generates the name when your application adds the task to a queue. | If you don't specify a task name, App Engine auto-generates the name when your application adds the task to a queue.
  `method` | The method of task execution. May be `POST` (default), `GET`, `PUT`, `DELETE`, `HEAD`, or `PULL`. | Do not specify a `method` for push tasks. This argument defaults to `POST`, which posts assigned tasks to the web hook at the specified `url`. | Set the `method` to `PULL`. This setting prevents the task from being delivered to the web hook so a worker can be lease it from the pull queue.
  `url` | URL for the webhook that should handle this task. | The `url` is usually a path relative to your application's root directory. May have a query string unless the `method` is `POST`. If you are using backends, you can specify the URL of the instance and backend that you want to perform the work. | Do not specify a `url` for pull queue tasks.
  `headers` | Dictionary of headers to pass to the webhook. | Values in the dictionary may be iterable to indicate repeated header fields. If a `Content-Type` header is not specified, a default of `text/plain` is used. | Do not specify `headers` for pull queue tasks.

  `params`

  Dictionary of parameters to use for this task.

  Values in the dictionary may be iterable to indicate repeated parameters. In `POST` requests,
  - Do not specify params if you already specified a `payload`.
  - Params are encoded as `application/x-www-form-urlencoded` and set to the `payload`.

  In `PUT` requests,

  - Params are converted to a query string if the URL contains a query string, or the task already has a `payload`.
  - Do not specify params if the URL already contains a query string and the `method` is `GET`.

  Values in the dictionary may be iterable to indicate repeated parameters. In `PULL` requests,

  - Do not specify params if you already specified a `payload`.
  - Params are encoded as `application/x-www-form-urlencoded` and set to the `payload`.

  `countdown` | Minimum time to wait before executing this task, in seconds. Defaults to zero. Do not specify a countdown if you specified an `eta`. | Minimum time to wait before executing this task, in seconds. | Designates how long to wait, in seconds, before allowing the task to be leased.
  `eta` | Earliest time of task execution. If None, defaults to now. | Earliest time to execute the task. May be timezone-aware or timezone-naive. | Designates the earliest time that a worker can lease a task. No worker can lease a task before the `eta`.
  `retry_options` | TaskRetryOptions used to retry failed tasks. | Includes `min_backoff_seconds`, `max_backoff_seconds`, `task_age_limit`, `max_doublings`, and `task_retry_limit`. | Only the `task_retry_limit` option is allowed. It indicates the number of times a task may be leased before it is automatically deleted from the queue.
  `target` | The alternate application version, or backend, on which to execute this task. | No push-specific details. | No pull-specific details.

## Properties

The following table describes properties of a Task instance. These properties differ slightly in push and pull queues, as described in the following table:

Task instance property | Meaning for Push Tasks | Meaning for Pull Tasks
--- | --- | ---
`eta` | A datetime.datetime object which provides the earliest time when this task will execute. | A datetime.datetime object representing the earliest time this task can be leased.
`eta_posix` | A POSIX timestamp giving an estimate of when this task will execute. | A POSIX timestamp representing the earliest time this task can be leased.
`headers` | The HTTP headers which will be used when invoking this task. | Not applicable
`method` | The HTTP method used to invoke this task, one of `GET`, `POST`, `HEAD`, `PUT`, or `DELETE`. | `PULL` only. All other methods are illegal for pull tasks.
`name` | The name of this task. Will be `None` if using auto-assigned task names and this task has not yet been added to a queue. | The name of this task. Will be `None` if using auto-assigned task names and this task has not yet been added to a queue.
`on_queue_url` | True if this task will run on the queue's default URL; false if not. | Not applicable
`payload` | The payload which will be used when invoking this task; may be None. | The payload which will be used when invoking this task; may be None.
`size` | Size of this task in bytes. | Size of this task in bytes.
`retry_count` | The number of times this task has been retried. | The number of times this task has been leased.
`retry_options` | Any or all of the TaskRetryOptions for this task, which may be None. | May be only the `task_retry_limit` parameter of the TaskRetryOptions class, or None.
`tag` | None. | The tag for this task. You can enqueue tasks by tag in pull queues using `Queue.lease_tasks_by_tag()`.
`target` | Returns the version of the application to which this task was targeted. | No push-specific details. | No pull-specific details.

`url`

The URL handler for this task relative to your application's root directory.

Pull queues have no url.

`was_deleted`

True if this task has been successfully deleted.

True if this task has been successfully deleted.

`was_enqueued`

Not queue specific. True if this task has been inserted into a queue. Does not check if this task already exists in the queue.

Not queue specific. True if this task has been inserted into a queue. Does not check if this task already exists in the queue.

## Instance Methods

A Task instance has the following methods:

add(queue_name='default', transactional=False)

  Adds this task to a queue. The queue is specified by name. A single Task instance may only be added to one queue.

  Arguments:

  queue_name
    Name of the queue to which this task will be added. The name should correspond to a user-created entry in the queue.yaml configuration file. If not supplied, the task will be added to the default queue.
  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 committed successfully. Note that this task must not have a user-specified name in this case.

  The return value is the task itself.

extract_params()

  Returns a dictionary of strings mapping parameter names to their values as strings. If the same name parameter has several values, then the value is a list of strings. For `POST` and `PULL` requests,, the parameters are extracted from the task payload; for all other methods, the parameters are extracted from the URL query string.

  Raises a ValueError if:

  - The payload for `PULL` or `POST` does not contain `application/x-www-form-urlencoded` data.
  - The payload for all other methods does not contain a query.