---
title: "Tasks"
version: 6.0
locale: fr
source: https://docs.djangoproject.com/fr/6.0/ref/tasks/
canonical: https://djangodocs.dev/fr/6.0/ref/tasks/
---
# 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(* (Keyword-only parameters separator (PEP 3102)), priority=0, queue_name='default', backend='default', takes_context=False)`

The `@task` decorator defines a [`Task`](#django.tasks.Task) instance. This has the
following optional arguments:

- `priority`: Sets the [`priority`](#django.tasks.Task.priority) of the `Task`. Defaults
  to 0.
- `queue_name`: Sets the [`queue_name`](#django.tasks.Task.queue_name) of the `Task`.
  Defaults to `"default"`.
- `backend`: Sets the [`backend`](#django.tasks.Task.backend) of the `Task`. Defaults to
  `"default"`.
- `takes_context`: contrôle si la fonction `Task` accepte un objet [`TaskContext`](#django.tasks.TaskContext). Vaut `False` par défaut. Voir [Contexte des tâches](/fr/6.0/topics/tasks/#task-context) pour plus de détails.

Si la tâche définie n’est pas valable selon le moteur, une exception [`InvalidTask`](#django.tasks.exceptions.InvalidTask) est générée.

Voir [définition des tâches](/fr/6.0/topics/tasks/#defining-tasks) pour des exemples d’utilisation.

### `Task`

#### `class Task`

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`](#django.tasks.backends.base.BaseTaskBackend.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`](/fr/6.0/ref/settings/#std-setting-TASKS-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`](/fr/6.0/ref/settings/#std-setting-TASKS-QUEUES), sauf si [`QUEUES`](/fr/6.0/ref/settings/#std-setting-TASKS-QUEUES) est défini à `[]`.

#### `run_after`

The earliest time the `Task` will be executed. This can be a
[`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta), which is used relative to the
current time, a timezone-aware [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime),
or `None` if not constrained. Defaults to `None`.

The backend must have [`supports_defer`](#django.tasks.backends.base.BaseTaskBackend.supports_defer) set to `True` to use
this feature. Otherwise,
[`InvalidTask`](#django.tasks.exceptions.InvalidTask) is raised.

#### `name`

Le nom de la fonction décorée par [`task()`](#django.tasks.task). Ce nom n’est pas forcément unique.

#### `using(* (Keyword-only parameters separator (PEP 3102)), priority=None, backend=None, queue_name=None, run_after=None)`

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 :

- [`priority`](#django.tasks.Task.priority)
- [`backend`](#django.tasks.Task.backend)
- [`queue_name`](#django.tasks.Task.queue_name)
- [`run_after`](#django.tasks.Task.run_after)

Voir [modification des tâches](/fr/6.0/topics/tasks/#modifying-tasks) pour des exemples d’utilisation.

#### `enqueue(*args, **kwargs)`

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()`](https://docs.python.org/3/library/json.html#json.dumps)/[`json.loads()`](https://docs.python.org/3/library/json.html#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`](#django.tasks.exceptions.InvalidTask) is raised.

See [enqueueing Tasks](/fr/6.0/topics/tasks/#enqueueing-tasks) for usage examples.

#### `aenqueue(*args, **kwargs)`

La variante `async` de [`enqueue`](#django.tasks.Task.enqueue).

#### `get_result(result_id)`

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

If the result does not exist, [`TaskResultDoesNotExist`](#django.tasks.exceptions.TaskResultDoesNotExist) is raised. If the
result is not the same type as the current Task,
[`TaskResultMismatch`](#django.tasks.exceptions.TaskResultMismatch)
is raised. If the backend does not support `get_result()`,
[`NotImplementedError`](https://docs.python.org/3/library/exceptions.html#NotImplementedError) is raised.

#### `aget_result(*args, **kwargs)`

La variante `async` de [`get_result`](#django.tasks.Task.get_result).

## Contexte des tâches

#### `class TaskContext`

Contains context for the running [`Task`](#django.tasks.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`](#django.tasks.TaskResult) currently being run.

#### `attempt`

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

## Résultats des tâches

#### `class TaskResultStatus`

An Enum representing the status of a [`TaskResult`](#django.tasks.TaskResult).

#### `READY`

The [`Task`](#django.tasks.Task) has just been enqueued, or is ready to be executed
again.

#### `RUNNING`

The [`Task`](#django.tasks.Task) is currently being executed.

#### `FAILED`

The [`Task`](#django.tasks.Task) raised an exception during execution, or was unable
to start.

#### `SUCCESSFUL`

The [`Task`](#django.tasks.Task) has finished executing successfully.

#### `class TaskResult`

The `TaskResult` stores the information about a specific execution of a
[`Task`](#django.tasks.Task).

Attributes of `TaskResult` cannot be modified.

#### `task`

The [`Task`](#django.tasks.Task) the result was enqueued for.

#### `id`

A unique identifier for the result, which can be passed to
[`Task.get_result()`](#django.tasks.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](/fr/6.0/topics/tasks/#task-results) for more details.

#### `status`

The [`status`](#django.tasks.TaskResultStatus) 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`](#django.tasks.TaskError) instances for the errors raised as part of
each execution of the Task.

#### `return_value`

The return value from the `Task` function.

If the `Task` did not finish successfully, [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) is
raised.

See [return values](/fr/6.0/topics/tasks/#task-return-values) for usage examples.

#### `refresh()`

Refresh the result’s attributes from the queue store.

#### `arefresh()`

The `async` variant of [`TaskResult.refresh()`](#django.tasks.TaskResult.refresh).

#### `is_finished`

Whether the `Task` has finished (successfully or not).

#### `attempts`

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`

`BaseTaskBackend` is the parent class for all Task backends.

#### `options`

A dictionary of extra parameters for the Task backend. These are
provided using the [`OPTIONS`](/fr/6.0/ref/settings/#std-setting-TASKS-OPTIONS) setting.

#### `enqueue(task, args, kwargs)`

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

When implemented, `enqueue()` enqueues the `task`, a [`Task`](#django.tasks.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`](#django.tasks.TaskResult).

#### `aenqueue(task, args, kwargs)`

The `async` variant of [`BaseTaskBackend.enqueue()`](#django.tasks.backends.base.BaseTaskBackend.enqueue).

#### `get_result(result_id)`

Retrieve a result by its id. If the result does not exist,
[`TaskResultDoesNotExist`](#django.tasks.exceptions.TaskResultDoesNotExist) is raised.

If the backend does not support `get_result()`,
[`NotImplementedError`](https://docs.python.org/3/library/exceptions.html#NotImplementedError) is raised.

#### `aget_result(result_id)`

The `async` variant of [`BaseTaskBackend.get_result()`](#django.tasks.backends.base.BaseTaskBackend.get_result).

#### `validate_task(task)`

Validates whether the provided `Task` is able to be enqueued using
the backend. If the Task is not valid,
[`InvalidTask`](#django.tasks.exceptions.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`](#django.tasks.Task.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`](#django.tasks.Task.priority).

The below table notes which of the [built-in backends](#task-available-backends) support which features:

| Feature | [`DummyBackend`](#django.tasks.backends.dummy.DummyBackend) | [`ImmediateBackend`](#django.tasks.backends.immediate.ImmediateBackend) |
| --- | --- | --- |
| [`supports_defer`](#django.tasks.backends.base.BaseTaskBackend.supports_defer) | Oui | Non |
| [`supports_async_task`](#django.tasks.backends.base.BaseTaskBackend.supports_async_task) | Oui | Oui |
| [`supports_get_result`](#django.tasks.backends.base.BaseTaskBackend.supports_get_result) | Non | No [^1] |
| [`supports_priority`](#django.tasks.backends.base.BaseTaskBackend.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](/fr/6.0/topics/tasks/#configuring-a-task-backend).

#### Immediate backend

#### `class ImmediateBackend`

The [immediate backend](/fr/6.0/topics/tasks/#immediate-task-backend) executes Tasks
immediately, rather than in the background.

#### Le moteur bidon

#### `class DummyBackend`

The [dummy backend](/fr/6.0/topics/tasks/#dummy-task-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()`

Clears the list of stored results.

## Exceptions

#### `exception InvalidTask`

Raised when the [`Task`](#django.tasks.Task) attempting to be enqueued
is invalid.

#### `exception InvalidTaskBackend`

Raised when the requested [`BaseTaskBackend`](#django.tasks.backends.base.BaseTaskBackend) is invalid.

#### `exception TaskResultDoesNotExist`

Raised by [`get_result()`](#django.tasks.backends.base.BaseTaskBackend.get_result)
when the provided `result_id` does not exist.

#### `exception TaskResultMismatch`

Raised by [`get_result()`](#django.tasks.Task.get_result) when the provided
`result_id` is for a different Task than the current Task.

**Notes de bas de page**

[^1]: The [`ImmediateBackend`](#django.tasks.backends.immediate.ImmediateBackend) doesn’t officially
support `get_result()`, despite implementing the API, since the result
cannot be retrieved from a different thread.

[^2]: The [`DummyBackend`](#django.tasks.backends.dummy.DummyBackend) has `supports_priority=True`
so that it can be used as a drop-in replacement in tests. Since this
backend never executes Tasks, the `priority` value has no effect.

[^3]: The [`ImmediateBackend`](#django.tasks.backends.immediate.ImmediateBackend) has
`supports_priority=True` so that it can be used as a drop-in replacement
in tests. Because Tasks run as soon as they are scheduled, the `priority`
value has no effect.