bpo-40979: 'Generic ABCs' section (initial A)

python · gvanrossum · Aug 2, 2020 · Jul 21, 2020 · Jul 21, 2020 · Jul 21, 2020
commit 49d2a314e69b51a0c0c21875c12d23640dac24bb
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -1291,6 +1291,71 @@ Functions and decorators
    Note that returning instances of private classes is not recommended.
    It is usually preferable to make such classes public.
 
+Generic ABCs (with initial A)
+.............................
+
+.. class:: AbstractSet(Sized, Collection[T_co])
+
+    A generic version of :class:`collections.abc.Set`.
+
+.. class:: AsyncContextManager(Generic[T_co])
+
+   A generic version of :class:`contextlib.AbstractAsyncContextManager`.
+
+   .. versionadded:: 3.5.4
+   .. versionadded:: 3.6.2
+
+.. 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.6.1
+
+.. class:: AsyncIterable(Generic[T_co])
+
+   A generic version of :class:`collections.abc.AsyncIterable`.
+
+   .. versionadded:: 3.5.2
+
+.. class:: AsyncIterator(AsyncIterable[T_co])
+
+   A generic version of :class:`collections.abc.AsyncIterator`.
+
+   .. versionadded:: 3.5.2
+
+.. class:: Awaitable(Generic[T_co])
+
+   A generic version of :class:`collections.abc.Awaitable`.
+
+   .. versionadded:: 3.5.2
+
 Remaining classes, functions and decorators
 ...........................................
 
@@ -1320,10 +1385,6 @@ Remaining classes, functions and decorators
 
    .. versionadded:: 3.6.0
 
-.. class:: AbstractSet(Sized, Collection[T_co])
-
-    A generic version of :class:`collections.abc.Set`.
-
 .. class:: MutableSet(AbstractSet[T])
 
     A generic version of :class:`collections.abc.MutableSet`.
@@ -1374,12 +1435,6 @@ Remaining classes, functions and decorators
 
    A generic version of :class:`collections.abc.ValuesView`.
 
-.. class:: Awaitable(Generic[T_co])
-
-   A generic version of :class:`collections.abc.Awaitable`.
-
-   .. versionadded:: 3.5.2
-
 .. class:: Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co])
 
    A generic version of :class:`collections.abc.Coroutine`.
@@ -1395,32 +1450,13 @@ Remaining classes, functions and decorators
 
    .. versionadded:: 3.5.3
 
-.. class:: AsyncIterable(Generic[T_co])
-
-   A generic version of :class:`collections.abc.AsyncIterable`.
-
-   .. versionadded:: 3.5.2
-
-.. class:: AsyncIterator(AsyncIterable[T_co])
-
-   A generic version of :class:`collections.abc.AsyncIterator`.
-
-   .. versionadded:: 3.5.2
-
 .. class:: ContextManager(Generic[T_co])
 
    A generic version of :class:`contextlib.AbstractContextManager`.
 
    .. versionadded:: 3.5.4
    .. versionadded:: 3.6.0
 
-.. class:: AsyncContextManager(Generic[T_co])
-
-   A generic version of :class:`contextlib.AbstractAsyncContextManager`.
-
-   .. versionadded:: 3.5.4
-   .. versionadded:: 3.6.2
-
 .. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
 
    A generator can be annotated by the generic type
@@ -1452,39 +1488,6 @@ Remaining 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.6.1
-
 .. class:: IO
            TextIO
            BinaryIO