Issue #29198: Document typing.AsyncGenerator

Patch by Jelle Zijlstra.

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index f89d886cd7c3f9d8a251e15d89229eb8bebf6053..aaa43e4a444bedb110556adbd2b349482ddb5c06 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -670,6 +670,39 @@ The module defines the following classes, functions and decorators:
               yield start
               start += 1
 
+.. class:: AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])
+
+   An async generator can be annotated by the generic type
+   ``AsyncGenerator[YieldType, SendType]``. For example::
+
+      async def echo_round() -> AsyncGenerator[int, float]:
+          sent = yield 0
+          while sent >= 0.0:
+              rounded = await round(sent)
+              sent = yield rounded
+
+   Unlike normal generators, async generators cannot return a value, so there
+   is no ``ReturnType`` type parameter. As with :class:`Generator`, the
+   ``SendType`` behaves contravariantly.
+
+   If your generator will only yield values, set the ``SendType`` to
+   ``None``::
+
+      async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
+          while True:
+              yield start
+              start = await increment(start)
+
+   Alternatively, annotate your generator as having a return type of
+   either ``AsyncIterable[YieldType]`` or ``AsyncIterator[YieldType]``::
+
+      async def infinite_stream(start: int) -> AsyncIterator[int]:
+          while True:
+              yield start
+              start = await increment(start)
+
+   .. versionadded:: 3.5.4
+
 .. class:: Text
 
    ``Text`` is an alias for ``str``. It is provided to supply a forward