gh-96377: Update asyncio policy doc intro paras to be clear and accurate #97603
Conversation
CAM-Gerlach
requested review from
1st1,
asvetlov and
gvanrossum
as code owners
| that can override these behaviors. | ||
|
|
||
| The :ref:`policy object <asyncio-policy-objects>` | ||
| gets and sets a separate event loop per *context*. |
There was a problem hiding this comment.
Should/could context link to anything?
It's only mentioned here and in a couple of methods below, but it's otherwise not defined in this page.
There was a problem hiding this comment.
Perhaps we should add -- in a separate PR -- a concise list of asyncio-related terms/concepts (coroutines, tasks, futures, event loops, transports, contexts, policies, ...).
There was a problem hiding this comment.
If we did so as a proper Sphinx glossary, they could be easily referenced with, e.g. :term:`coroutine` from anywhere (including via intersphinx).
There was a problem hiding this comment.
Good luck defining context. It has at least four unrelated uses/meanings:
- context manager, e.g.
TaskGroupandtimeout; see alsocontextlib - a collection of context variables (see
contextvars) used to pass contextual state along to child tasks (e.g.create_task(..., context=...)) - a dict with assorted things passed to exception handlers
- The context referred to by the docs for event loop policies
gvanrossum
added
needs backport to 3.10
|
Thanks @CAM-Gerlach for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11. |
|
GH-97604 is a backport of this pull request to the 3.11 branch. |
|
GH-97605 is a backport of this pull request to the 3.10 branch. |
… accurate (pythonGH-97603) Also fix up some cross-references in the asyncio docs. (cherry picked from commit cc0f3a1) Co-authored-by: C.A.M. Gerlach <[email protected]>
… accurate (pythonGH-97603) Also fix up some cross-references in the asyncio docs. (cherry picked from commit cc0f3a1) Co-authored-by: C.A.M. Gerlach <[email protected]>
…ate (GH-97603) Also fix up some cross-references in the asyncio docs. (cherry picked from commit cc0f3a1) Co-authored-by: C.A.M. Gerlach <[email protected]>
…ate (GH-97603) Also fix up some cross-references in the asyncio docs. (cherry picked from commit cc0f3a1) Co-authored-by: C.A.M. Gerlach <[email protected]>
Oops, I forgot to add the backport tags, sorry. Thanks for taking care of that. |
| By using a custom event loop policy, the behavior of | ||
| :func:`get_event_loop`, :func:`set_event_loop`, and | ||
| :func:`new_event_loop` functions can be customized. | ||
| An event loop policy is a global (per-interpreter) object |
There was a problem hiding this comment.
An event loop policy is a global (per-interpreter)
I know the details here are hard to understand but "per-interpreter" can give false sense that asyncio can work under multiple interpreters. It doesn't since it caches the thread id and does not checks the interp id. It would be better to remove per-interpreter altogether here.
See #91375
There was a problem hiding this comment.
Oh, you're right, I remember now. We should add a note to that issue to add "per-interpreter" back here once that's been fixed. (It's not rocket science to fix it, IIRC, just work?)
There was a problem hiding this comment.
Oh and since this is already merged we'd need a new PR. :-(
…ate (GH-97603) Also fix up some cross-references in the asyncio docs. (cherry picked from commit cc0f3a1) Co-authored-by: C.A.M. Gerlach <[email protected]>
As reported in #96377 , the introductory paragraphs of the Asyncio Policies doc are confusing and not particularly accurate. Therefore, as discussed there, I've rewritten them to better reflect and explain the current reality, per the guidance of @gvanrossum . I've also added refs to the various relevant sections as they are mentioned, and also linked the doc explaining what an event loop is to begin with when mentioned.
To note, the previous
asyncio-event-loopref target label actually pointed to the table of low-level event loop methods, instead of pointing to the top-level summary of what an event loop actually is as you'd expect and also what most actual usages treated it as, which was in fact missing a ref target label entirely. Therefore, I moved it up a bit to point to that top-level document heading so I could use such, and added a newasyncio-event-loop-methodsref pointing specifically to the section with the table, updating the few instances that actually did treat the previous as the methods table to point to that instead.Preview: