bpo-33649: Add a high-level section about Futures; few quick fixes (GH-9403)

Co-authored-by: Elvis Pranskevichus <elvis@magic.io>

Doc/library/asyncio-eventloop.rst

@@ -989,7 +989,7 @@ Availability: Unix.
 Executing code in thread or process pools
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. coroutinemethod:: loop.run_in_executor(executor, func, \*args)
+.. awaitablemethod:: loop.run_in_executor(executor, func, \*args)
 
    Arrange for *func* to be called in the specified executor.
 

Doc/library/asyncio-future.rst

@@ -7,7 +7,7 @@
 Futures
 =======
 
-*Future* objects are used to bridge low-level callback-based code
+*Future* objects are used to bridge **low-level callback-based code**
 with high-level async/await code.
 
 

Doc/library/asyncio.rst

@@ -17,6 +17,7 @@
            await asyncio.sleep(1)
            print('... World!')
 
+       # Python 3.7+
        asyncio.run(main())
 
 asyncio is a library to write **concurrent** code using

Doc/tools/extensions/pyspecific.py

@@ -163,6 +163,13 @@ class PyCoroutineMixin(object):
         return ret
 
 
+class PyAwaitableMixin(object):
+    def handle_signature(self, sig, signode):
+        ret = super(PyAwaitableMixin, self).handle_signature(sig, signode)
+        signode.insert(0, addnodes.desc_annotation('awaitable ', 'awaitable '))
+        return ret
+
+
 class PyCoroutineFunction(PyCoroutineMixin, PyModulelevel):
     def run(self):
         self.name = 'py:function'
@@ -175,6 +182,18 @@ class PyCoroutineMethod(PyCoroutineMixin, PyClassmember):
         return PyClassmember.run(self)
 
 
+class PyAwaitableFunction(PyAwaitableMixin, PyClassmember):
+    def run(self):
+        self.name = 'py:function'
+        return PyClassmember.run(self)
+
+
+class PyAwaitableMethod(PyAwaitableMixin, PyClassmember):
+    def run(self):
+        self.name = 'py:method'
+        return PyClassmember.run(self)
+
+
 class PyAbstractMethod(PyClassmember):
 
     def handle_signature(self, sig, signode):
@@ -394,6 +413,8 @@ def setup(app):
     app.add_directive_to_domain('py', 'decoratormethod', PyDecoratorMethod)
     app.add_directive_to_domain('py', 'coroutinefunction', PyCoroutineFunction)
     app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
+    app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
+    app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
     app.add_directive_to_domain('py', 'abstractmethod', PyAbstractMethod)
     app.add_directive('miscnews', MiscNews)
     return {'version': '1.0', 'parallel_read_safe': True}