[Django] #37165: Update Async Topic Docs

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton | Owner: Carlton Gibson
Gibson |
Type: | Status: assigned
Cleanup/optimization |
Component: | Version: 6.0
Documentation |
Severity: Normal | Keywords:
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
The [https://docs.djangoproject.com/en/6.0/topics/async/ Asynchronous
support] topic doc was written when we first introduced async support.
It's outdated, and the warnings it gives are misleadingly negative. Time
to refresh it.
--
Ticket URL: <https://code.djangoproject.com/ticket/37165>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------

Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Carlton Gibson):

* has_patch: 0 => 1

Comment:

[https://github.com/django/django/pull/21465 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:1>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Description changed by Carlton Gibson:

Old description:

> The [https://docs.djangoproject.com/en/6.0/topics/async/ Asynchronous
> support] topic doc was written when we first introduced async support.
> It's outdated, and the warnings it gives are misleadingly negative. Time
> to refresh it.

New description:

The [https://docs.djangoproject.com/en/6.0/topics/async/ Asynchronous
support] topic doc was written when we first introduced async support.
It's outdated, and the warnings it gives are misleadingly negative. Time
to refresh it.

The main problems are:

1. It strongly implies that Django's asynchronous story is unfinished.
It's **often** liked to in blog posts. And it's totally misleading. The
user API is essentially finished. From the PR: """Many parts of Django
provide asynchronous APIs, including :ref:`the ORM <async-queries>`, the
cache framework, authentication, sessions, mail, and signals. For other
code, the :func:`sync_to_async` adapter is a low-cost bridge (see
:ref:`async_performance`)."""

2. The performance warnings are severely outdated.
`sync_to_async`/`async_to_sync` usage is in the order or microseconds with
modern versions of Python. This plays directly into implementation
considerations where we're constantly pulled towards duplicating whole
code trees, on the mistaken assumption that `sync_to_async` usage (in
particular) incurs a (relatively) massive performance hit.

3. It makes no mention of the remaining async difficulties — such as
concurrent DB queries — which are **not Django specific**. In particular
connection pooling is the appropriate lever to increase throughput,
regardless of whether you're using Django, any other async orm, or raw
connections by hand. (The current phrasing implies it's the ORM that's at
fault here: it's not!)

The topic doc here is a big source of the negative narrative about
Django's async story. It's time to correct that.

--
--
Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:2>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Description changed by Carlton Gibson:

Old description:

> The [https://docs.djangoproject.com/en/6.0/topics/async/ Asynchronous
> support] topic doc was written when we first introduced async support.
> It's outdated, and the warnings it gives are misleadingly negative. Time
> to refresh it.
>

It's **often** linked to in blog posts. And it's totally misleading. The

user API is essentially finished. From the PR: """Many parts of Django
provide asynchronous APIs, including :ref:`the ORM <async-queries>`, the
cache framework, authentication, sessions, mail, and signals. For other
code, the :func:`sync_to_async` adapter is a low-cost bridge (see
:ref:`async_performance`)."""

2. The performance warnings are severely outdated.
`sync_to_async`/`async_to_sync` usage is in the order or microseconds with
modern versions of Python. This plays directly into implementation
considerations where we're constantly pulled towards duplicating whole
code trees, on the mistaken assumption that `sync_to_async` usage (in
particular) incurs a (relatively) massive performance hit.

3. It makes no mention of the remaining async difficulties — such as
concurrent DB queries — which are **not Django specific**. In particular
connection pooling is the appropriate lever to increase throughput,
regardless of whether you're using Django, any other async orm, or raw
connections by hand. (The current phrasing implies it's the ORM that's at
fault here: it's not!)

The topic doc here is a big source of the negative narrative about
Django's async story. It's time to correct that.

--
--

Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:3>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Mariusz Felisiak):

* stage: Unreviewed => Accepted

--
Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:4>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Carlton Gibson):

FWIW this has come up again today on comments on ann interview of Jeff’s
from PyCon US. “when will the ORM be async?”
--
Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:5>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Mykhailo Havelia):

related PR - https://github.com/django/django/pull/20949
--
Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:6>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:7>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson

Cleanup/optimization | Status: closed
Component: Documentation | Version: 6.0
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by nessita <124304+nessita@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"2c5e4af3cccd88a7f0ea66a56aff1a49ad274681" 2c5e4af3]:
{{{#!CommitTicketReference repository=""
revision="2c5e4af3cccd88a7f0ea66a56aff1a49ad274681"
Fixed #37165 -- Updated Async Support topics doc.

Removed outdated warnings, and updated performance considerations to
reflect current realities.

Thanks to Mykhailo Havelia for the detailed review.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:8>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: closed
Component: Documentation | Version: 6.0
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia <124304+nessita@…>):

In [changeset:"11393f27c59ca92112e097fe77d4bbd96207ca01" 11393f27]:
{{{#!CommitTicketReference repository=""
revision="11393f27c59ca92112e097fe77d4bbd96207ca01"
[6.1.x] Fixed #37165 -- Updated Async Support topics doc.

Removed outdated warnings, and updated performance considerations to
reflect current realities.

Thanks to Mykhailo Havelia for the detailed review.

Backport of 2c5e4af3cccd88a7f0ea66a56aff1a49ad274681 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:9>

[Django]

#37165: Update Async Topic Docs
-------------------------------------+-------------------------------------
Reporter: Carlton Gibson | Owner: Carlton
Type: | Gibson
Cleanup/optimization | Status: closed
Component: Documentation | Version: 6.0
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Natalia <124304+nessita@…>):

In [changeset:"a6cfda9afaf924c2793df757c85eba5a3b5b2f13" a6cfda9]:
{{{#!CommitTicketReference repository=""
revision="a6cfda9afaf924c2793df757c85eba5a3b5b2f13"
[6.0.x] Fixed #37165 -- Updated Async Support topics doc.

Removed outdated warnings, and updated performance considerations to
reflect current realities.

Thanks to Mykhailo Havelia for the detailed review.

Backport of 2c5e4af3cccd88a7f0ea66a56aff1a49ad274681 from main.
}}}
--

Ticket URL: <https://code.djangoproject.com/ticket/37165#comment:10>