[Python-checkins] [doc] Leverage the fact that the actual types can now be indexed for typing (GH-22340)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/bdf46bc7e12c08aaab676a2c947f03daffe035a7
commit: bdf46bc7e12c08aaab676a2c947f03daffe035a7
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-09-27T12:42:29-07:00
summary:

[doc] Leverage the fact that the actual types can now be indexed for typing (GH-22340)


This shows users that they can use the actual types. Using deprecated types is confusing.

This also prefers colections.abc.Sized instead of the alias typing.Sized. I guess the aliases were created to make it convenient to import all collections related types from the same place.

This should be backported to 3.9.

Automerge-Triggered-By: @gvanrossum
(cherry picked from commit d9ab95ff1fe81efdf70e545d536d9f6927d1ba81)

Co-authored-by: Andre Delfino <adelfino at gmail.com>

files:
M Doc/glossary.rst
M Doc/library/typing.rst

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 7be755e411310..9fdbdb1a83f28 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -1084,19 +1084,15 @@ Glossary
       Type aliases are useful for simplifying :term:`type hints <type hint>`.
       For example::
 
-         from typing import List, Tuple
-
          def remove_gray_shades(
-                 colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
+                 colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
              pass
 
       could be made more readable like this::
 
-         from typing import List, Tuple
-
-         Color = Tuple[int, int, int]
+         Color = tuple[int, int, int]
 
-         def remove_gray_shades(colors: List[Color]) -> List[Color]:
+         def remove_gray_shades(colors: list[Color]) -> list[Color]:
              pass
 
       See :mod:`typing` and :pep:`484`, which describe this functionality.
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 6d6b76c1d0895..78d90d19f74e0 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -38,10 +38,9 @@ Type aliases
 ============
 
 A type alias is defined by assigning the type to the alias. In this example,
-``Vector`` and ``List[float]`` will be treated as interchangeable synonyms::
+``Vector`` and ``list[float]`` will be treated as interchangeable synonyms::
 
-   from typing import List
-   Vector = List[float]
+   Vector = list[float]
 
    def scale(scalar: float, vector: Vector) -> Vector:
        return [scalar * num for num in vector]
@@ -51,11 +50,11 @@ A type alias is defined by assigning the type to the alias. In this example,
 
 Type aliases are useful for simplifying complex type signatures. For example::
 
-   from typing import Dict, Tuple, Sequence
+   from collections.abc import Sequence
 
-   ConnectionOptions = Dict[str, str]
-   Address = Tuple[str, int]
-   Server = Tuple[Address, ConnectionOptions]
+   ConnectionOptions = dict[str, str]
+   Address = tuple[str, int]
+   Server = tuple[Address, ConnectionOptions]
 
    def broadcast_message(message: str, servers: Sequence[Server]) -> None:
        ...
@@ -64,7 +63,7 @@ Type aliases are useful for simplifying complex type signatures. For example::
    # being exactly equivalent to this one.
    def broadcast_message(
            message: str,
-           servers: Sequence[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:
+           servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None:
        ...
 
 Note that ``None`` as a type hint is a special case and is replaced by
@@ -157,7 +156,7 @@ type hinted using ``Callable[[Arg1Type, Arg2Type], ReturnType]``.
 
 For example::
 
-   from typing import Callable
+   from collections.abc import Callable
 
    def feeder(get_next_item: Callable[[], str]) -> None:
        # Body
@@ -181,7 +180,7 @@ subscription to denote expected types for container elements.
 
 ::
 
-   from typing import Mapping, Sequence
+   from collections.abc import Mapping, Sequence
 
    def notify_by_email(employees: Sequence[Employee],
                        overrides: Mapping[str, str]) -> None: ...
@@ -191,7 +190,8 @@ called :class:`TypeVar`.
 
 ::
 
-   from typing import Sequence, TypeVar
+   from collections.abc import Sequence
+   from typing import TypeVar
 
    T = TypeVar('T')      # Declare type variable
 
@@ -235,7 +235,7 @@ class body.
 The :class:`Generic` base class defines :meth:`__class_getitem__` so that
 ``LoggedVar[t]`` is valid as a type::
 
-   from typing import Iterable
+   from collections.abc import Iterable
 
    def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
        for var in vars:
@@ -266,7 +266,8 @@ This is thus invalid::
 
 You can use multiple inheritance with :class:`Generic`::
 
-   from typing import TypeVar, Generic, Sized
+   from collections.abc import Sized
+   from typing import TypeVar, Generic
 
    T = TypeVar('T')
 
@@ -275,7 +276,8 @@ You can use multiple inheritance with :class:`Generic`::
 
 When inheriting from generic classes, some type variables could be fixed::
 
-    from typing import TypeVar, Mapping
+    from collections.abc import Mapping
+    from typing import TypeVar
 
     T = TypeVar('T')
 
@@ -288,13 +290,14 @@ Using a generic class without specifying type parameters assumes
 :data:`Any` for each position. In the following example, ``MyIterable`` is
 not generic but implicitly inherits from ``Iterable[Any]``::
 
-   from typing import Iterable
+   from collections.abc import Iterable
 
    class MyIterable(Iterable): # Same as Iterable[Any]
 
 User defined generic type aliases are also supported. Examples::
 
-   from typing import TypeVar, Iterable, Tuple, Union
+   from collections.abc import Iterable
+   from typing import TypeVar, Union
    S = TypeVar('S')
    Response = Union[Iterable[S], int]
 
@@ -303,9 +306,9 @@ User defined generic type aliases are also supported. Examples::
        ...
 
    T = TypeVar('T', int, float, complex)
-   Vec = Iterable[Tuple[T, T]]
+   Vec = Iterable[tuple[T, T]]
 
-   def inproduct(v: Vec[T]) -> T: # Same as Iterable[Tuple[T, T]]
+   def inproduct(v: Vec[T]) -> T: # Same as Iterable[tuple[T, T]]
        return sum(x*y for x, y in v)
 
 .. versionchanged:: 3.7
@@ -408,7 +411,7 @@ to be explicitly marked to support them, which is unpythonic and unlike
 what one would normally do in idiomatic dynamically typed Python code.
 For example, this conforms to the :pep:`484`::
 
-   from typing import Sized, Iterable, Iterator
+   from collections.abc import Sized, Iterable, Iterator
 
    class Bucket(Sized, Iterable[int]):
        ...
@@ -421,7 +424,7 @@ allowing ``Bucket`` to be implicitly considered a subtype of both ``Sized``
 and ``Iterable[int]`` by static type checkers. This is known as
 *structural subtyping* (or static duck-typing)::
 
-   from typing import Iterator, Iterable
+   from collections.abc import Iterator, Iterable
 
    class Bucket:  # Note: no base classes
        ...
@@ -1371,10 +1374,10 @@ Asynchronous programming
    The variance and order of type variables
    correspond to those of :class:`Generator`, for example::
 
-      from typing import List, Coroutine
-      c = None # type: Coroutine[List[str], str, int]
+      from collections.abc import Coroutine
+      c = None # type: Coroutine[list[str], str, int]
       ...
-      x = c.send('hi') # type: List[str]
+      x = c.send('hi') # type: list[str]
       async def bar() -> None:
           x = await c # type: int