Tasks

New in Django 6.0.

The Task framework provides the contract and plumbing for background work, not the engine that runs it. The Tasks API defines how work is described, queued, and tracked, but leaves actual execution to external infrastructure.

Task definition

The task decorator

task(*, priority=0, queue_name='default', backend='default', takes_context=False, **kwargs)[source]

The @task decorator defines a Task instance. All keyword arguments are passed directly to the backend’s task_class (which defaults to Task).

The following standard arguments are supported:

  • priority: Sets the priority of the Task. Defaults to 0.

  • queue_name: Sets the queue_name of the Task. Defaults to "default".

  • backend: Sets the backend of the Task. Defaults to "default".

  • takes_context: contrôle si la fonction Task accepte un objet TaskContext. Vaut False par défaut. Voir Contexte des tâches pour plus de détails.

Custom Task backends may define a custom task_class that accepts additional arguments. These can be passed through the @task decorator:

@task(foo=5, bar=600)
def my_task():
    pass
Changed in Django 6.1:

Support for passing arbitrary **kwargs to the @task decorator is added.

Si la tâche définie n’est pas valable selon le moteur, une exception InvalidTask est générée.

Voir définition des tâches pour des exemples d’utilisation.

Task

class Task[source]

Représente une tâche à exécuter en arrière-plan. Les tâches doivent être définies par le décorateur func:task.

Les attributs de Task ne peuvent pas être modifiés. Voir :ref:modification des tâches <modifying-tasks>` pour plus de détails.

priority

La priorité de Task. Les priorités doivent se situer entre -100 et 100, où un plus grand nombre signifie une priorité plus haute et va donc s’exécuter plus rapidement.

Le moteur doit avoir l’attribut supports_priority à True pour pouvoir utiliser cette fonctionnalité.

backend

L’alias du moteur pour lequel la tâche Task doit être placée en file d’attente. Cela doit correspondre à un moteur défini dans BACKEND.

queue_name

Le nom de la file d’attente à laquelle la tâche sera attribuée. Par défaut, c’est "default". Cela doit correspondre à une file d’attente définie dans QUEUES, sauf si QUEUES est défini à [].

run_after

The earliest time the Task will be executed. This can be a timedelta, which is used relative to the current time, a timezone-aware datetime, or None if not constrained. Defaults to None.

This attribute can be set using using().

The backend must have supports_defer set to True to use this feature. Otherwise, InvalidTask is raised.

name[source]

Le nom de la fonction décorée par task(). Ce nom n’est pas forcément unique.

using(*, priority=None, backend=None, queue_name=None, run_after=None)[source]

Crée une nouvelle Task avec des valeurs par défaut modifiées. La tâche existante n’est pas touchée.

using permet de modifier les attributs suivants :

Voir modification des tâches pour des exemples d’utilisation.

enqueue(*args, **kwargs)[source]

Enqueues the Task to the Task backend for later execution.

Arguments are passed to the Task’s function after a round-trip through a json.dumps()/json.loads() cycle. Hence, all arguments must be JSON-serializable and preserve their type after the round-trip.

If the Task is not valid according to the backend, InvalidTask is raised.

See enqueueing Tasks for usage examples.

aenqueue(*args, **kwargs)

La variante async de enqueue.

get_result(result_id)[source]

Récupère un résultat à partir de son id.

If the result does not exist, TaskResultDoesNotExist is raised. If the result is not the same type as the current Task, TaskResultMismatch is raised. If the backend does not support get_result(), NotImplementedError is raised.

aget_result(*args, **kwargs)

La variante async de get_result.

Contexte des tâches

class TaskContext[source]

Contains context for the running Task. Context only passed to a Task if it was defined with takes_context=True.

Attributes of TaskContext cannot be modified.

task_result

The TaskResult currently being run.

attempt[source]

The number of the current execution attempts for this Task, starting at 1.

Résultats des tâches

class TaskResultStatus[source]

An Enum representing the status of a TaskResult.

READY

The Task has just been enqueued, or is ready to be executed again.

RUNNING

The Task is currently being executed.

FAILED

The Task raised an exception during execution, or was unable to start.

SUCCESSFUL

The Task has finished executing successfully.

class TaskResult[source]

The TaskResult stores the information about a specific execution of a Task.

Attributes of TaskResult cannot be modified.

task

The Task the result was enqueued for.

id

A unique identifier for the result, which can be passed to Task.get_result().

The format of the id will depend on the backend being used. Task result ids are always strings less than 64 characters.

See Task results for more details.

status

The status of the result.

enqueued_at

The time when the Task was enqueued.

started_at

The time when the Task began execution, on its first attempt.

last_attempted_at

The time when the most recent Task run began execution.

finished_at

The time when the Task finished execution, whether it failed or succeeded.

backend

The backend the result is from.

errors

A list of TaskError instances for the errors raised as part of each execution of the Task.

return_value[source]

The return value from the Task function.

If the Task did not finish successfully, ValueError is raised.

See return values for usage examples.

refresh()[source]

Refresh the result’s attributes from the queue store.

arefresh()

The async variant of TaskResult.refresh().

is_finished[source]

Whether the Task has finished (successfully or not).

attempts[source]

The number of times the Task has been run.

If the task is currently running, it does not count as an attempt.

worker_ids

The ids of the workers which have executed the Task.

Erreurs des tâches

class TaskError

Contient des informations au sujet de l’erreur générée durant l’exécution de la tâche.

traceback

La trace d’erreur (sous forme de chaîne) de l’exception générée lorsque la tâche a échoué.

exception_class

La classe d’exception générée lors de l’exécution de la tâche.

Backends

Backends handle how Tasks are stored and executed. All backends share a common interface defined by BaseTaskBackend, which specifies the core methods for enqueueing Tasks and retrieving results.

Base backend

class BaseTaskBackend[source]

BaseTaskBackend is the parent class for all Task backends.

task_class

The Task subclass to use when creating tasks with the task() decorator. Defaults to Task. Custom backends can override this to use a custom Task subclass with additional attributes.

options

A dictionary of extra parameters for the Task backend. These are provided using the OPTIONS setting.

enqueue(task, args, kwargs)[source]

Task backends which subclass BaseTaskBackend should implement this method as a minimum.

When implemented, enqueue() enqueues the task, a Task instance, for later execution. args are the positional arguments and kwargs are the keyword arguments to be passed to the task. Returns a TaskResult.

aenqueue(task, args, kwargs)

The async variant of BaseTaskBackend.enqueue().

get_result(result_id)[source]

Retrieve a result by its id. If the result does not exist, TaskResultDoesNotExist is raised.

If the backend does not support get_result(), NotImplementedError is raised.

aget_result(result_id)

The async variant of BaseTaskBackend.get_result().

validate_task(task)[source]

Validates whether the provided Task is able to be enqueued using the backend. If the Task is not valid, InvalidTask is raised.

Feature flags

Some backends may not support all features Django provides. It’s possible to identify the supported functionality of a backend, and potentially change behavior accordingly.

BaseTaskBackend.supports_defer

Whether the backend supports enqueueing Tasks to be executed after a specific time using the run_after attribute.

BaseTaskBackend.supports_async_task

Whether the backend supports enqueueing async functions (coroutines).

BaseTaskBackend.supports_get_result

Whether the backend supports retrieving Task results from another thread after they have been enqueued.

BaseTaskBackend.supports_priority

Whether the backend supports executing Tasks as ordered by their priority.

The below table notes which of the built-in backends support which features:

Feature

DummyBackend

ImmediateBackend

supports_defer

Oui

Non

supports_async_task

Oui

Oui

supports_get_result

Non

No [1]

supports_priority

Yes [2]

Yes [3]

Available backends

Django includes only development and testing backends. These support local execution and inspection, for production ready backends refer to Configuration d’un moteur de tâches.

Immediate backend

class ImmediateBackend[source]

The immediate backend executes Tasks immediately, rather than in the background.

Le moteur bidon

class DummyBackend[source]

The dummy backend does not execute enqueued Tasks. Instead, it stores task results for later inspection.

results

A list of results for the enqueued Tasks, in the order they were enqueued.

clear()[source]

Clears the list of stored results.

Exceptions

exception InvalidTask[source]

Raised when the Task attempting to be enqueued is invalid.

exception InvalidTaskBackend[source]

Raised when the requested BaseTaskBackend is invalid.

exception TaskResultDoesNotExist[source]

Raised by get_result() when the provided result_id does not exist.

exception TaskResultMismatch[source]

Raised by get_result() when the provided result_id is for a different Task than the current Task.

Notes de bas de page

« previous | up | next »