bpo-29679: Implement @contextlib.asynccontextmanager (#360)

1 files changed, 30 insertions, 0 deletions

diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
index dd34c96..1979369 100644
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -80,6 +80,36 @@ Functions and classes provided:
       Use of :class:`ContextDecorator`.
 
 
+.. decorator:: asynccontextmanager
+
+   Similar to :func:`~contextlib.contextmanager`, but creates an
+   :ref:`asynchronous context manager <async-context-managers>`.
+
+   This function is a :term:`decorator` that can be used to define a factory
+   function for :keyword:`async with` statement asynchronous context managers,
+   without needing to create a class or separate :meth:`__aenter__` and
+   :meth:`__aexit__` methods. It must be applied to an :term:`asynchronous
+   generator` function.
+
+   A simple example::
+
+      from contextlib import asynccontextmanager
+
+      @asynccontextmanager
+      async def get_connection():
+          conn = await acquire_db_connection()
+          try:
+              yield
+          finally:
+              await release_db_connection(conn)
+
+      async def get_all_users():
+          async with get_connection() as conn:
+              return conn.query('SELECT ...')
+
+   .. versionadded:: 3.7
+
+
 .. function:: closing(thing)
 
    Return a context manager that closes *thing* upon completion of the block.  This