bpo-32258: Replace 'yield from' to 'await' in asyncio docs (#4779)

* Replace 'yield from' to 'await' in asyncio docs

* Fix docstrings

Lib/asyncio/coroutines.py

@@ -19,8 +19,9 @@ def _is_debug_mode():
     # If you set _DEBUG to true, @coroutine will wrap the resulting
     # generator objects in a CoroWrapper instance (defined below).  That
     # instance will log a message when the generator is never iterated
-    # over, which may happen when you forget to use "yield from" with a
-    # coroutine call.  Note that the value of the _DEBUG flag is taken
+    # over, which may happen when you forget to use "await" or "yield from"
+    # with a coroutine call.
+    # Note that the value of the _DEBUG flag is taken
     # when the decorator is used, so to be of any use it must be set
     # before you define your coroutines.  A downside of using this feature
     # is that tracebacks show entries for the CoroWrapper.__next__ method

Lib/asyncio/futures.py

@@ -59,7 +59,8 @@ class Future:
     #   The value must also be not-None, to enable a subclass to declare
     #   that it is not compatible by setting this to None.
     # - It is set by __iter__() below so that Task._step() can tell
-    #   the difference between `yield from Future()` (correct) vs.
+    #   the difference between
+    #   `await Future()` or`yield from Future()` (correct) vs.
     #   `yield Future()` (incorrect).
     _asyncio_future_blocking = False
 
@@ -236,7 +237,7 @@ class Future:
         if not self.done():
             self._asyncio_future_blocking = True
             yield self  # This tells Task to wait for completion.
-        assert self.done(), "yield from wasn't used with future"
+        assert self.done(), "await wasn't used with future"
         return self.result()  # May raise too.
 
     __await__ = __iter__  # make compatible with 'await' expression

Lib/asyncio/locks.py

@@ -23,6 +23,10 @@ class _ContextManager:
 
         with lock:
             <block>
+
+    Deprecated, use 'async with' statement:
+        async with lock:
+            <block>
     """
 
     def __init__(self, lock):
@@ -64,6 +68,9 @@ class _ContextManagerMixin:
         #         <block>
         #     finally:
         #         lock.release()
+        # Deprecated, use 'async with' statement:
+        #     async with lock:
+        #         <block>
         warnings.warn("'with (yield from lock)' is deprecated "
                       "use 'async with lock' instead",
                       DeprecationWarning, stacklevel=2)
@@ -113,16 +120,16 @@ class Lock(_ContextManagerMixin):
     release() call resets the state to unlocked; first coroutine which
     is blocked in acquire() is being processed.
 
-    acquire() is a coroutine and should be called with 'yield from'.
+    acquire() is a coroutine and should be called with 'await'.
 
-    Locks also support the context management protocol.  '(yield from lock)'
-    should be used as the context manager expression.
+    Locks also support the asynchronous context management protocol.
+    'async with lock' statement should be used.
 
     Usage:
 
         lock = Lock()
         ...
-        yield from lock
+        await lock.acquire()
         try:
             ...
         finally:
@@ -132,13 +139,13 @@ class Lock(_ContextManagerMixin):
 
         lock = Lock()
         ...
-        with (yield from lock):
+        async with lock:
              ...
 
     Lock objects can be tested for locking state:
 
         if not lock.locked():
-           yield from lock
+           await lock.acquire()
         else:
            # lock is acquired
            ...