[Python-checkins] bpo-38260: Add Docs on asyncio.run (GH-16337)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/d3666945d78508970002653c4d46221a4306f55b
commit: d3666945d78508970002653c4d46221a4306f55b
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-09-25T02:13:00-07:00
summary:

bpo-38260: Add Docs on asyncio.run (GH-16337)


Add docs about return and raise exception on asyncio.run

https://bugs.python.org/issue38260

Automerge-Triggered-By: @asvetlov
(cherry picked from commit 17deb16883fa574a86e42551cc37f044182347ad)

Co-authored-by: Emmanuel Arias <emmanuelarias30 at gmail.com>

files:
M Doc/library/asyncio-task.rst
M Lib/asyncio/runners.py

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 29ccafee908b..a9f6f9cfc4b6 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -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.
+
+    Example::
+
+        async def main():
+            await asyncio.sleep(1)
+            print('hello')
+
+        asyncio.run(main())
+
     .. versionadded:: 3.7
        **Important:** this function has been added to asyncio in
        Python 3.7 on a :term:`provisional basis <provisional api>`.
diff --git a/Lib/asyncio/runners.py b/Lib/asyncio/runners.py
index 5fbab03dd001..df686386b8fd 100644
--- a/Lib/asyncio/runners.py
+++ b/Lib/asyncio/runners.py
@@ -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():