8000 bpo-38260: Add Docs on asyncio.run by eamanu · Pull Request #16337 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

bpo-38260: Add Docs on asyncio.run #16337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 25, 2019
Merged

bpo-38260: Add Docs on asyncio.run #16337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
39cd32b
Add Docs on asyncio.run
eamanu Sep 23, 2019
1ba3164
Fix documentation according to @asvetlov
eamanu Sep 23, 2019
9dc8cb3
Add @corona10 comments
eamanu Sep 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions Doc/library/asyncio-task.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,18 @@ Running an asyncio Program
the end. It should be used as a main entry point for asyncio
programs, and should ideally only be called once.

Return a result of *coro* execution, or raise a :exc:`RuntimeError`
if ``asyncio.run()`` is called from a running event loop, or a
:exc:`ValueError` if *coro* is not a courutine.
Copy link
Contributor
@aeros aeros Sep 25, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the adding the additional information @eamanu, but I noticed a couple of issues with the section added.

The more apparent one was a spelling typo, "courutine" should be "coroutine" (misspelled here and in the docstring). Also, it's helpful to link to the glossary using:

:term:`coroutine`

Also, while this section is helpful (particularly with specifying the RuntimeError and ValueError scenarios), I think it could be phrased significantly better. I would suggest the following changes:

Within the new event loop, *coro* is executed, returning the result. If
``asyncio.run()`` is called within a running event loop, a :exc:`RuntimeError`
is raised. If *coro* is not a coroutine, a :exc:`ValueError` is raised.

Personally, I think it's especially important to phrase this section of the documentation as well as possible, since it's likely one of the most read sections for the entire asyncio module.

Let me know what you think @asvetlov and @1st1. If you approve of the suggestions, I'll open a new PR that makes the changes I mentioned above in the docs for ascynio.run() and in the docstring as well (since this one was already merged and backported).

Grammar tip: When chaining together multiple instances of "or", each of the items should be separated by a comma, but only the last one is supposed to have the "or". For example: "item1, item2, or item3" instead of "item1, or item2, or item3". The section added to the documentation in this PR used the latter.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I follow "Within the new event loop, coro is executed, returning the result." -- I can't parse it. I'd keep the original one "Return the result of coro execution."

IMO it's not necessary to document RuntimeError and ValueError; "This function cannot be called when another asyncio event loop is running in the same thread." already covers that.

Copy link
Contributor
@aeros aeros Sep 27, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@1st1 Okay, I'll make the suggested changes in #16403.

Edit: Actually, I think specifying that ValueError is raised when something other than a coroutine is passed might be useful (for basic debugging purposes). Do you think that can remain since it's not covered by the existing section?


Example::

async def main():
await asyncio.sleep(1)
print('hello')

asyncio.run(main())

.. versionadded:: 3.7

.. versionchanged:: 3.9
Expand Down
4 changes: 4 additions & 0 deletions Lib/asyncio/runners.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@ def run(main, *, debug=False):
It should be used as a main entry point for asyncio programs, and should
ideally only be called once.

Return a result of *coro* execution, or raise a RuntimeError
if `asyncio.run()`is called from a running event loop, or a ValueError
if `main` is not a courutine.

Example:

async def main():
Expand Down
0