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 decorator¶The @task decorator defines a Task instance. This has the
following optional arguments:
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: Controls whether the Task function accepts a
TaskContext. Defaults to False. See Task context for details.
If the defined Task is not valid according to the backend,
InvalidTask is raised.
See defining tasks for usage examples.
Task¶Represents a Task to be run in the background. Tasks should be defined
using the task() decorator.
Attributes of Task cannot be modified. See modifying Tasks for details.
The priority of the Task. Priorities must be between -100 and 100,
where larger numbers are higher priority, and will be run sooner.
The backend must have supports_priority set to True to use
this feature.
The alias of the backend the Task should be enqueued to. This must
match a backend defined in BACKEND.
The name of the queue the Task will be enqueued on to. Defaults to
"default". This must match a queue defined in
QUEUES, unless
QUEUES is set to [].
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.
The backend must have supports_defer set to True to use
this feature. Otherwise,
InvalidTask is raised.
Creates a new Task with modified defaults. The existing Task is
left unchanged.
using allows modifying the following attributes:
See modifying Tasks for usage examples.
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.
Retrieves a result by its 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.
The async variant of get_result.
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.
The TaskResult currently being run.
An Enum representing the status of a TaskResult.
The TaskResult stores the information about a specific execution of a
Task.
Attributes of TaskResult cannot be modified.
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.
The time when the Task was enqueued.
The time when the Task began execution, on its first attempt.
The time when the most recent Task run began execution.
The time when the Task finished execution, whether it failed or
succeeded.
The backend the result is from.
The return value from the Task function.
If the Task did not finish successfully, ValueError is
raised.
See return values for usage examples.
The async variant of TaskResult.refresh().
The number of times the Task has been run.
If the task is currently running, it does not count as an attempt.
The ids of the workers which have executed the Task.
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.
BaseTaskBackend is the parent class for all Task backends.
A dictionary of extra parameters for the Task backend. These are
provided using the OPTIONS setting.
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.
The async variant of BaseTaskBackend.enqueue().
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.
The async variant of BaseTaskBackend.get_result().
Validates whether the provided Task is able to be enqueued using
the backend. If the Task is not valid,
InvalidTask
is raised.
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.
Whether the backend supports enqueueing Tasks to be executed after a
specific time using the run_after attribute.
Whether the backend supports enqueueing async functions (coroutines).
Whether the backend supports retrieving Task results from another
thread after they have been enqueued.
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 |
||
|---|---|---|
是 |
否 |
|
是 |
是 |
|
否 |
No [1] |
|
Yes [2] |
Yes [3] |
Django includes only development and testing backends. These support local execution and inspection, for production ready backends refer to Configuring a Task backend.
The immediate backend executes Tasks immediately, rather than in the background.
Raised when the requested BaseTaskBackend is invalid.
Raised by get_result()
when the provided result_id does not exist.
Raised by get_result() when the provided
result_id is for a different Task than the current Task.
脚注
12月 22, 2025