diff options
| author | Jacob Walls <jacobtylerwalls@gmail.com> | 2025-12-02 10:25:26 -0500 |
|---|---|---|
| committer | Natalia <124304+nessita@users.noreply.github.com> | 2025-12-03 13:09:57 -0300 |
| commit | a9f5ca5c58df7b662ad23ba9a39619c41a7e39ff (patch) | |
| tree | 6f14313b8272de1862e82b714cfa2fba013886d2 /docs | |
| parent | 45f9e0e969257c0938fec4b51b9b0264aa49bd25 (diff) | |
[6.0.x] Refs #35859 -- Clarified Tasks ref and topics docs regarding available backends.
Backport of d3f142f2cd36ba0458cc679397555bd5ee7db744 from main.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ref/tasks.txt | 12 | ||||
| -rw-r--r-- | docs/releases/6.0.txt | 5 | ||||
| -rw-r--r-- | docs/topics/tasks.txt | 28 |
3 files changed, 34 insertions, 11 deletions
diff --git a/docs/ref/tasks.txt b/docs/ref/tasks.txt index c427c4c4d3..99d8eb6a0a 100644 --- a/docs/ref/tasks.txt +++ b/docs/ref/tasks.txt @@ -7,6 +7,10 @@ Tasks .. module:: django.tasks :synopsis: Django's built-in background Task system. +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 =============== @@ -274,6 +278,10 @@ Task errors 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 ------------ @@ -365,6 +373,10 @@ Feature :class:`.DummyBackend` :class:`.ImmediateBackend` Available backends ------------------ +Django includes only development and testing backends. These support local +execution and inspection, for production ready backends refer to +:ref:`configuring-a-task-backend`. + Immediate backend ~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/6.0.txt b/docs/releases/6.0.txt index 46fdb25864..89786c7ccb 100644 --- a/docs/releases/6.0.txt +++ b/docs/releases/6.0.txt @@ -102,6 +102,11 @@ Django now includes a built-in Tasks framework for running code outside the HTTP request–response cycle. This enables offloading work, such as sending emails or processing data, to background workers. +The framework provides task definition, validation, queuing, and result +handling. Django guarantees consistent behavior for creating and managing +tasks, while the responsibility for running them continues to belong to +external worker processes. + Tasks are defined using the :func:`~django.tasks.task` decorator:: from django.core.mail import send_mail diff --git a/docs/topics/tasks.txt b/docs/topics/tasks.txt index 13afd8b09f..96deac6dc3 100644 --- a/docs/topics/tasks.txt +++ b/docs/topics/tasks.txt @@ -15,10 +15,11 @@ to be run elsewhere, potentially at a later date. This keeps requests fast, reduces latency, and improves the user experience. For example, a user shouldn't have to wait for an email to send before their page finishes loading. -Django's new Tasks framework makes it easy to define and enqueue such work. It +Django's Tasks framework makes it easy to define and enqueue such work. It does not provide a worker mechanism to run Tasks. The actual execution must be handled by infrastructure outside Django, such as a separate process or -service. +service. Given that, a :ref:`task backend <configuring-a-task-backend>` capable +of executing tasks on that service should be evaluated and configured. Background Task fundamentals ============================ @@ -41,9 +42,13 @@ Configuring a Task backend The Task backend determines how and where Tasks are stored for execution and how they are executed. Different Task backends have different characteristics and configuration options, which may impact the performance and reliability of -your application. Django comes with a number of :ref:`built-in backends -<task-available-backends>`. Django does not provide a generic way to execute -Tasks, only enqueue them. +your application. Django comes with :ref:`built-in backends +<task-available-backends>`, but these are for development and testing only. + +Django handles task definition, validation, queuing, and result handling, not +execution, so production setups need a backend or worker process that actually +runs queued work. Relevant options are listed in the `Community Ecosystem +<https://www.djangoproject.com/community/ecosystem/>`__ page. Task backends are configured using the :setting:`TASKS` setting in your settings file. Whilst most applications will only need a single backend, @@ -103,13 +108,14 @@ Stored results can be cleared using the >>> len(default_task_backend.results) 0 -Using a custom backend ----------------------- +Third-party backends +-------------------- -While Django includes support for a number of Task backends out-of-the-box, -sometimes you might want to customize the Task backend. To use an external Task -backend with Django, use the Python import path as the :setting:`BACKEND -<TASKS-BACKEND>` of the :setting:`TASKS` setting, like so:: +As mentioned at the beginning of this section, Django includes backends +suitable for development and testing only. Production systems should rely on +backends that supply a worker process and durable queue implementation. To use +an external Task backend with Django, use the Python import path as the +:setting:`BACKEND <TASKS-BACKEND>` of the :setting:`TASKS` setting, like so:: TASKS = { "default": { |
