Skip to content

Commit 9da27dd

Browse files
committed
- Variety of style/phrasing improvements based on PR feedback.
1 parent 689d517 commit 9da27dd

File tree

1 file changed

+16
-14
lines changed

1 file changed

+16
-14
lines changed

Doc/howto/a-conceptual-overview-of-asyncio.rst

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,7 @@ It's behind the scenes managing resources.
4242
Some power is explicitly granted to it, but a lot of its ability to get things
4343
done comes from the respect and cooperation of its teammates.
4444

45-
In more technical terms, the event loop contains a queue of jobs (or "chunks
46-
of work") to be run.
45+
In more technical terms, the event loop contains a queue of jobs to be run.
4746
Some jobs are added directly by you, and some indirectly by :mod:`!asyncio`.
4847
The event loop pops a job from the queue and invokes it (or "gives it control"),
4948
similar to calling a function, then that job runs.
@@ -183,15 +182,16 @@ different ways::
183182
await task
184183
await coroutine
185184

186-
Unfortunately, it does matter which type of object is awaited.
185+
Unfortunately, it does matter which type of object is ``await``\ ed.
187186

188187
``await``\ ing a task will cede control from the current task or coroutine to
189188
the event loop.
190-
And while doing so, adds a callback to the awaited task's list of callbacks
191-
indicating it should resume the current task/coroutine when it (the
192-
``await``\ ed one) finishes.
193-
In other words, when that awaited task finishes, the original task is added
194-
back to the event loops queue.
189+
In the process of relinquishing control, the task that's giving up control
190+
adds a callback to the ``await``\ ed task's list of callbacks indicating it
191+
should resume the current task/coroutine when it (the ``await``\ ed one)
192+
finishes.
193+
In other words, when that ``await``\ ed task finishes, the original task is
194+
added back to the event loops queue.
195195

196196
This is a basic, yet reliable mental model.
197197
In practice, it's slightly more complex, but not by much.
@@ -268,8 +268,8 @@ resume a coroutine.
268268
If the coroutine was paused and is now being resumed, the argument ``arg``
269269
will be sent in as the return value of the ``yield`` statement which originally
270270
paused it.
271-
If the coroutine is being started, as opposed to resumed, ``arg`` must be
272-
``None``.
271+
If the coroutine is being used for the first time, as opposed to being resumed,
272+
arg must be ``None``.
273273

274274
:ref:`yield <yieldexpr>`, like usual, pauses execution and returns control
275275
to the caller.
@@ -334,11 +334,13 @@ The only way to yield (or effectively cede control) from a coroutine is to
334334
``await`` an object that ``yield``\ s in its ``__await__`` method.
335335
That might sound odd to you. You might be thinking:
336336

337-
1. What about a ``yield`` directly within the coroutine? The coroutine becomes
338-
an async generator, a different beast entirely.
337+
1. What about a ``yield`` directly within the coroutine function? The
338+
coroutine function becomes an
339+
:ref:`async generator function <asynchronous-generator-functions>`, a
340+
different beast entirely.
339341

340-
2. What about a ``yield from`` within the coroutine to a function that yields
341-
(that is, a plain generator)?
342+
2. What about a ``yield from`` within the coroutine function to a (plain)
343+
generator?
342344
``SyntaxError: yield from not allowed in a coroutine.``
343345
This was intentionally designed for the sake of simplicity -- mandating only
344346
one way of using coroutines. Originally ``yield`` was actually barred as well,

0 commit comments

Comments
 (0)