bpo-40979: refactored typing.rst; (mostly) same content, new sub-sections and ordering (#21574)

Also added PEP 585 deprecation notes.

1 files changed, 823 insertions, 614 deletions

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index e5143c5..44b537f 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -1,3 +1,4 @@
+========================================
 :mod:`typing` --- Support for type hints
 ========================================
 
@@ -34,7 +35,7 @@ In the function ``greeting``, the argument ``name`` is expected to be of type
 arguments.
 
 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::
@@ -72,7 +73,7 @@ Note that ``None`` as a type hint is a special case and is replaced by
 .. _distinct:
 
 NewType
--------
+=======
 
 Use the :func:`NewType` helper function to create distinct types::
 
@@ -149,7 +150,7 @@ See :pep:`484` for more details.
 .. versionadded:: 3.5.2
 
 Callable
---------
+========
 
 Frameworks expecting callback functions of specific signatures might be
 type hinted using ``Callable[[Arg1Type, Arg2Type], ReturnType]``.
@@ -172,7 +173,7 @@ for the list of arguments in the type hint: ``Callable[..., ReturnType]``.
 .. _generics:
 
 Generics
---------
+========
 
 Since type information about objects kept in containers cannot be statically
 inferred in a generic way, abstract base classes have been extended to support
@@ -199,7 +200,7 @@ called :class:`TypeVar`.
 
 
 User-defined generic types
---------------------------
+==========================
 
 A user-defined class can be defined as a generic class.
 
@@ -317,7 +318,7 @@ comparable for equality.
 
 
 The :data:`Any` type
---------------------
+====================
 
 A special kind of type is :data:`Any`. A static type checker will treat
 every type as being compatible with :data:`Any` and :data:`Any` as being
@@ -395,7 +396,7 @@ manner. Use :data:`Any` to indicate that a value is dynamically typed.
 
 
 Nominal vs structural subtyping
--------------------------------
+===============================
 
 Initially :pep:`484` defined Python static type system as using
 *nominal subtyping*. This means that a class ``A`` is allowed where
@@ -434,11 +435,377 @@ Moreover, by subclassing a special class :class:`Protocol`, a user
 can define new custom protocols to fully enjoy structural subtyping
 (see examples below).
 
+Module contents
+===============
+
+The module defines the following classes, functions and decorators.
+
+.. note::
+
+   This module defines several types that are subclasses of pre-existing
+   standard library classes which also extend :class:`Generic`
+   to support type variables inside ``[]``.
+   These types became redundant in Python 3.9 when the
+   corresponding pre-existing classes were enhanced to support ``[]``.
+
+   The redundant types are deprecated as of Python 3.9 but no
+   deprecation warnings will be issued by the interpreter.
+   It is expected that type checkers will flag the deprecated types
+   when the checked program targets Python 3.9 or newer.
+
+   The deprecated types will be removed from the :mod:`typing` module
+   in the first Python version released 5 years after the release of Python 3.9.0.
+   See details in :pep:`585`—*Type Hinting Generics In Standard Collections*.
+
+
+Special typing primitives
+-------------------------
+
+Special types
+"""""""""""""
+
+These can be used as types in annotations and do not support ``[]``.
+
+.. data:: Any
+
+   Special type indicating an unconstrained type.
+
+   * Every type is compatible with :data:`Any`.
+   * :data:`Any` is compatible with every type.
+
+.. data:: NoReturn
+
+   Special type indicating that a function never returns.
+   For example::
+
+      from typing import NoReturn
+
+      def stop() -> NoReturn:
+          raise RuntimeError('no way')
+
+   .. versionadded:: 3.5.4
+   .. versionadded:: 3.6.2
+
+Special forms
+"""""""""""""
+
+These can be used as types in annotations using ``[]``, each having a unique syntax.
+
+.. data:: Tuple
+
+   Tuple type; ``Tuple[X, Y]`` is the type of a tuple of two items
+   with the first item of type X and the second of type Y. The type of
+   the empty tuple can be written as ``Tuple[()]``.
+
+   Example: ``Tuple[T1, T2]`` is a tuple of two elements corresponding
+   to type variables T1 and T2.  ``Tuple[int, float, str]`` is a tuple
+   of an int, a float and a string.
+
+   To specify a variable-length tuple of homogeneous type,
+   use literal ellipsis, e.g. ``Tuple[int, ...]``. A plain :data:`Tuple`
+   is equivalent to ``Tuple[Any, ...]``, and in turn to :class:`tuple`.
+
+   .. deprecated:: 3.9
+      :class:`builtins.tuple <tuple>` now supports ``[]``. See :pep:`585`.
+
+.. data:: Union
+
+   Union type; ``Union[X, Y]`` means either X or Y.
+
+   To define a union, use e.g. ``Union[int, str]``.  Details:
+
+   * The arguments must be types and there must be at least one.
+
+   * Unions of unions are flattened, e.g.::
+
+       Union[Union[int, str], float] == Union[int, str, float]
+
+   * Unions of a single argument vanish, e.g.::
+
+       Union[int] == int  # The constructor actually returns int
+
+   * Redundant arguments are skipped, e.g.::
+
+       Union[int, str, int] == Union[int, str]
+
+   * When comparing unions, the argument order is ignored, e.g.::
+
+       Union[int, str] == Union[str, int]
+
+   * You cannot subclass or instantiate a union.
 
-Classes, functions, and decorators
-----------------------------------
+   * You cannot write ``Union[X][Y]``.
 
-The module defines the following classes, functions and decorators:
+   * You can use ``Optional[X]`` as a shorthand for ``Union[X, None]``.
+
+   .. versionchanged:: 3.7
+      Don't remove explicit subclasses from unions at runtime.
+
+.. data:: Optional
+
+   Optional type.
+
+   ``Optional[X]`` is equivalent to ``Union[X, None]``.
+
+   Note that this is not the same concept as an optional argument,
+   which is one that has a default.  An optional argument with a
+   default does not require the ``Optional`` qualifier on its type
+   annotation just because it is optional. For example::
+
+      def foo(arg: int = 0) -> None:
+          ...
+
+   On the other hand, if an explicit value of ``None`` is allowed, the
+   use of ``Optional`` is appropriate, whether the argument is optional
+   or not. For example::
+
+      def foo(arg: Optional[int] = None) -> None:
+          ...
+
+.. data:: Callable
+
+   Callable type; ``Callable[[int], str]`` is a function of (int) -> str.
+
+   The subscription syntax must always be used with exactly two
+   values: the argument list and the return type.  The argument list
+   must be a list of types or an ellipsis; the return type must be
+   a single type.
+
+   There is no syntax to indicate optional or keyword arguments;
+   such function types are rarely used as callback types.
+   ``Callable[..., ReturnType]`` (literal ellipsis) can be used to
+   type hint a callable taking any number of arguments and returning
+   ``ReturnType``.  A plain :data:`Callable` is equivalent to
+   ``Callable[..., Any]``, and in turn to
+   :class:`collections.abc.Callable`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.Callable` now supports ``[]``. See :pep:`585`.
+
+.. class:: Type(Generic[CT_co])
+
+   A variable annotated with ``C`` may accept a value of type ``C``. In
+   contrast, a variable annotated with ``Type[C]`` may accept values that are
+   classes themselves -- specifically, it will accept the *class object* of
+   ``C``. For example::
+
+      a = 3         # Has type 'int'
+      b = int       # Has type 'Type[int]'
+      c = type(a)   # Also has type 'Type[int]'
+
+   Note that ``Type[C]`` is covariant::
+
+      class User: ...
+      class BasicUser(User): ...
+      class ProUser(User): ...
+      class TeamUser(User): ...
+
+      # Accepts User, BasicUser, ProUser, TeamUser, ...
+      def make_new_user(user_class: Type[User]) -> User:
+          # ...
+          return user_class()
+
+   The fact that ``Type[C]`` is covariant implies that all subclasses of
+   ``C`` should implement the same constructor signature and class method
+   signatures as ``C``. The type checker should flag violations of this,
+   but should also allow constructor calls in subclasses that match the
+   constructor calls in the indicated base class. How the type checker is
+   required to handle this particular case may change in future revisions of
+   :pep:`484`.
+
+   The only legal parameters for :class:`Type` are classes, :data:`Any`,
+   :ref:`type variables <generics>`, and unions of any of these types.
+   For example::
+
+      def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...
+
+   ``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent
+   to ``type``, which is the root of Python's metaclass hierarchy.
+
+   .. versionadded:: 3.5.2
+
+   .. deprecated:: 3.9
+      :class:`builtins.type <type>` now supports ``[]``. See :pep:`585`.
+
+.. data:: Literal
+
+   A type that can be used to indicate to type checkers that the
+   corresponding variable or function parameter has a value equivalent to
+   the provided literal (or one of several literals). For example::
+
+      def validate_simple(data: Any) -> Literal[True]:  # always returns True
+          ...
+
+      MODE = Literal['r', 'rb', 'w', 'wb']
+      def open_helper(file: str, mode: MODE) -> str:
+          ...
+
+      open_helper('/some/path', 'r')  # Passes type check
+      open_helper('/other/path', 'typo')  # Error in type checker
+
+   ``Literal[...]`` cannot be subclassed. At runtime, an arbitrary value
+   is allowed as type argument to ``Literal[...]``, but type checkers may
+   impose restrictions. See :pep:`586` for more details about literal types.
+
+   .. versionadded:: 3.8
+
+.. data:: ClassVar
+
+   Special type construct to mark class variables.
+
+   As introduced in :pep:`526`, a variable annotation wrapped in ClassVar
+   indicates that a given attribute is intended to be used as a class variable
+   and should not be set on instances of that class. Usage::
+
+      class Starship:
+          stats: ClassVar[Dict[str, int]] = {} # class variable
+          damage: int = 10                     # instance variable
+
+   :data:`ClassVar` accepts only types and cannot be further subscribed.
+
+   :data:`ClassVar` is not a class itself, and should not
+   be used with :func:`isinstance` or :func:`issubclass`.
+   :data:`ClassVar` does not change Python runtime behavior, but
+   it can be used by third-party type checkers. For example, a type checker
+   might flag the following code as an error::
+
+      enterprise_d = Starship(3000)
+      enterprise_d.stats = {} # Error, setting class variable on instance
+      Starship.stats = {}     # This is OK
+
+   .. versionadded:: 3.5.3
+
+.. data:: Final
+
+   A special typing construct to indicate to type checkers that a name
+   cannot be re-assigned or overridden in a subclass. For example::
+
+      MAX_SIZE: Final = 9000
+      MAX_SIZE += 1  # Error reported by type checker
+
+      class Connection:
+          TIMEOUT: Final[int] = 10
+
+      class FastConnector(Connection):
+          TIMEOUT = 1  # Error reported by type checker
+
+   There is no runtime checking of these properties. See :pep:`591` for
+   more details.
+
+   .. versionadded:: 3.8
+
+.. data:: Annotated
+
+   A type, introduced in :pep:`593` (``Flexible function and variable
+   annotations``), to decorate existing types with context-specific metadata
+   (possibly multiple pieces of it, as ``Annotated`` is variadic).
+   Specifically, a type ``T`` can be annotated with metadata ``x`` via the
+   typehint ``Annotated[T, x]``. This metadata can be used for either static
+   analysis or at runtime. If a library (or tool) encounters a typehint
+   ``Annotated[T, x]`` and has no special logic for metadata ``x``, it
+   should ignore it and simply treat the type as ``T``. Unlike the
+   ``no_type_check`` functionality that currently exists in the ``typing``
+   module which completely disables typechecking annotations on a function
+   or a class, the ``Annotated`` type allows for both static typechecking
+   of ``T`` (e.g., via mypy or Pyre, which can safely ignore ``x``)
+   together with runtime access to ``x`` within a specific application.
+
+   Ultimately, the responsibility of how to interpret the annotations (if
+   at all) is the responsibility of the tool or library encountering the
+   ``Annotated`` type. A tool or library encountering an ``Annotated`` type
+   can scan through the annotations to determine if they are of interest
+   (e.g., using ``isinstance()``).
+
+   When a tool or a library does not support annotations or encounters an
+   unknown annotation it should just ignore it and treat annotated type as
+   the underlying type.
+
+   It's up to the tool consuming the annotations to decide whether the
+   client is allowed to have several annotations on one type and how to
+   merge those annotations.
+
+   Since the ``Annotated`` type allows you to put several annotations of
+   the same (or different) type(s) on any node, the tools or libraries
+   consuming those annotations are in charge of dealing with potential
+   duplicates. For example, if you are doing value range analysis you might
+   allow this::
+
+       T1 = Annotated[int, ValueRange(-10, 5)]
+       T2 = Annotated[T1, ValueRange(-20, 3)]
+
+   Passing ``include_extras=True`` to :func:`get_type_hints` lets one
+   access the extra annotations at runtime.
+
+   The details of the syntax:
+
+   * The first argument to ``Annotated`` must be a valid type
+
+   * Multiple type annotations are supported (``Annotated`` supports variadic
+     arguments)::
+
+       Annotated[int, ValueRange(3, 10), ctype("char")]
+
+   * ``Annotated`` must be called with at least two arguments (
+     ``Annotated[int]`` is not valid)
+
+   * The order of the annotations is preserved and matters for equality
+     checks::
+
+       Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
+           int, ctype("char"), ValueRange(3, 10)
+       ]
+
+   * Nested ``Annotated`` types are flattened, with metadata ordered
+     starting with the innermost annotation::
+
+       Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
+           int, ValueRange(3, 10), ctype("char")
+       ]
+
+   * Duplicated annotations are not removed::
+
+       Annotated[int, ValueRange(3, 10)] != Annotated[
+           int, ValueRange(3, 10), ValueRange(3, 10)
+       ]
+
+   * ``Annotated`` can be used with nested and generic aliases::
+
+       T = TypeVar('T')
+       Vec = Annotated[List[Tuple[T, T]], MaxLen(10)]
+       V = Vec[int]
+
+       V == Annotated[List[Tuple[int, int]], MaxLen(10)]
+
+   .. versionadded:: 3.9
+
+Building generic types
+""""""""""""""""""""""
+
+These are not used in annotations. They are building blocks for creating generic types.
+
+.. class:: Generic
+
+   Abstract base class for generic types.
+
+   A generic type is typically declared by inheriting from an
+   instantiation of this class with one or more type variables.
+   For example, a generic mapping type might be defined as::
+
+      class Mapping(Generic[KT, VT]):
+          def __getitem__(self, key: KT) -> VT:
+              ...
+              # Etc.
+
+   This class can then be used as follows::
+
+      X = TypeVar('X')
+      Y = TypeVar('Y')
+
+      def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:
+          try:
+              return mapping[key]
+          except KeyError:
+              return default
 
 .. class:: TypeVar
 
@@ -478,29 +845,20 @@ The module defines the following classes, functions and decorators:
     for the type variable must be a subclass of the boundary type,
     see :pep:`484`.
 
-.. class:: Generic
-
-   Abstract base class for generic types.
-
-   A generic type is typically declared by inheriting from an
-   instantiation of this class with one or more type variables.
-   For example, a generic mapping type might be defined as::
+.. data:: AnyStr
 
-      class Mapping(Generic[KT, VT]):
-          def __getitem__(self, key: KT) -> VT:
-              ...
-              # Etc.
+   ``AnyStr`` is a type variable defined as
+   ``AnyStr = TypeVar('AnyStr', str, bytes)``.
 
-   This class can then be used as follows::
+   It is meant to be used for functions that may accept any kind of string
+   without allowing different kinds of strings to mix. For example::
 
-      X = TypeVar('X')
-      Y = TypeVar('Y')
+      def concat(a: AnyStr, b: AnyStr) -> AnyStr:
+          return a + b
 
-      def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:
-          try:
-              return mapping[key]
-          except KeyError:
-              return default
+      concat(u"foo", u"bar")  # Ok, output has type 'unicode'
+      concat(b"foo", b"bar")  # Ok, output has type 'bytes'
+      concat(u"foo", b"bar")  # Error, cannot mix unicode and bytes
 
 .. class:: Protocol(Generic)
 
@@ -535,154 +893,171 @@ The module defines the following classes, functions and decorators:
 
    .. versionadded:: 3.8
 
-.. class:: Type(Generic[CT_co])
-
-   A variable annotated with ``C`` may accept a value of type ``C``. In
-   contrast, a variable annotated with ``Type[C]`` may accept values that are
-   classes themselves -- specifically, it will accept the *class object* of
-   ``C``. For example::
-
-      a = 3         # Has type 'int'
-      b = int       # Has type 'Type[int]'
-      c = type(a)   # Also has type 'Type[int]'
-
-   Note that ``Type[C]`` is covariant::
-
-      class User: ...
-      class BasicUser(User): ...
-      class ProUser(User): ...
-      class TeamUser(User): ...
-
-      # Accepts User, BasicUser, ProUser, TeamUser, ...
-      def make_new_user(user_class: Type[User]) -> User:
-          # ...
-          return user_class()
-
-   The fact that ``Type[C]`` is covariant implies that all subclasses of
-   ``C`` should implement the same constructor signature and class method
-   signatures as ``C``. The type checker should flag violations of this,
-   but should also allow constructor calls in subclasses that match the
-   constructor calls in the indicated base class. How the type checker is
-   required to handle this particular case may change in future revisions of
-   :pep:`484`.
-
-   The only legal parameters for :class:`Type` are classes, :data:`Any`,
-   :ref:`type variables <generics>`, and unions of any of these types.
-   For example::
+.. decorator:: runtime_checkable
 
-      def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...
+   Mark a protocol class as a runtime protocol.
 
-   ``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent
-   to ``type``, which is the root of Python's metaclass hierarchy.
+   Such a protocol can be used with :func:`isinstance` and :func:`issubclass`.
+   This raises :exc:`TypeError` when applied to a non-protocol class.  This
+   allows a simple-minded structural check, very similar to "one trick ponies"
+   in :mod:`collections.abc` such as :class:`Iterable`.  For example::
 
-   .. versionadded:: 3.5.2
+      @runtime_checkable
+      class Closable(Protocol):
+          def close(self): ...
 
-.. class:: Iterable(Generic[T_co])
+      assert isinstance(open('/some/file'), Closable)
 
-    A generic version of :class:`collections.abc.Iterable`.
+   .. note::
 
-.. class:: Iterator(Iterable[T_co])
+        :func:`runtime_checkable` will check only the presence of the required methods,
+        not their type signatures! For example, :class:`builtins.complex <complex>`
+        implements :func:`__float__`, therefore it passes an :func:`issubclass` check
+        against :class:`SupportsFloat`. However, the ``complex.__float__`` method
+        exists only to raise a :class:`TypeError` with a more informative message.
 
-    A generic version of :class:`collections.abc.Iterator`.
+   .. versionadded:: 3.8
 
-.. class:: Reversible(Iterable[T_co])
+Other special directives
+""""""""""""""""""""""""
 
-    A generic version of :class:`collections.abc.Reversible`.
+These are not used in annotations. They are building blocks for declaring types.
 
-.. class:: SupportsInt
+.. class:: NamedTuple
 
-    An ABC with one abstract method ``__int__``.
+   Typed version of :func:`collections.namedtuple`.
 
-.. class:: SupportsFloat
+   Usage::
 
-    An ABC with one abstract method ``__float__``.
+       class Employee(NamedTuple):
+           name: str
+           id: int
 
-.. class:: SupportsComplex
+   This is equivalent to::
 
-    An ABC with one abstract method ``__complex__``.
+       Employee = collections.namedtuple('Employee', ['name', 'id'])
 
-.. class:: SupportsBytes
+   To give a field a default value, you can assign to it in the class body::
 
-    An ABC with one abstract method ``__bytes__``.
+      class Employee(NamedTuple):
+          name: str
+          id: int = 3
 
-.. class:: SupportsIndex
+      employee = Employee('Guido')
+      assert employee.id == 3
 
-    An ABC with one abstract method ``__index__``.
+   Fields with a default value must come after any fields without a default.
 
-    .. versionadded:: 3.8
+   The resulting class has an extra attribute ``__annotations__`` giving a
+   dict that maps the field names to the field types.  (The field names are in
+   the ``_fields`` attribute and the default values are in the
+   ``_field_defaults`` attribute both of which are part of the namedtuple
+   API.)
 
-.. class:: SupportsAbs
+   ``NamedTuple`` subclasses can also have docstrings and methods::
 
-    An ABC with one abstract method ``__abs__`` that is covariant
-    in its return type.
+      class Employee(NamedTuple):
+          """Represents an employee."""
+          name: str
+          id: int = 3
 
-.. class:: SupportsRound
+          def __repr__(self) -> str:
+              return f'<Employee {self.name}, id={self.id}>'
 
-    An ABC with one abstract method ``__round__``
-    that is covariant in its return type.
+   Backward-compatible usage::
 
-.. class:: Container(Generic[T_co])
+       Employee = NamedTuple('Employee', [('name', str), ('id', int)])
 
-    A generic version of :class:`collections.abc.Container`.
+   .. versionchanged:: 3.6
+      Added support for :pep:`526` variable annotation syntax.
 
-.. class:: Hashable
+   .. versionchanged:: 3.6.1
+      Added support for default values, methods, and docstrings.
 
-   An alias to :class:`collections.abc.Hashable`
+   .. versionchanged:: 3.8
+      The ``_field_types`` and ``__annotations__`` attributes are
+      now regular dictionaries instead of instances of ``OrderedDict``.
 
-.. class:: Sized
+   .. versionchanged:: 3.9
+      Removed the ``_field_types`` attribute in favor of the more
+      standard ``__annotations__`` attribute which has the same information.
 
-   An alias to :class:`collections.abc.Sized`
+.. function:: NewType(name, tp)
 
-.. class:: Collection(Sized, Iterable[T_co], Container[T_co])
+   A helper function to indicate a distinct type to a typechecker,
+   see :ref:`distinct`. At runtime it returns a function that returns
+   its argument. Usage::
 
-   A generic version of :class:`collections.abc.Collection`
+      UserId = NewType('UserId', int)
+      first_user = UserId(1)
 
-   .. versionadded:: 3.6.0
+   .. versionadded:: 3.5.2
 
-.. class:: AbstractSet(Sized, Collection[T_co])
+.. class:: TypedDict(dict)
 
-    A generic version of :class:`collections.abc.Set`.
+   Special construct to add type hints to a dictionary.
+   At runtime it is a plain :class:`dict`.
 
-.. class:: MutableSet(AbstractSet[T])
+   ``TypedDict`` declares a dictionary type that expects all of its
+   instances to have a certain set of keys, where each key is
+   associated with a value of a consistent type. This expectation
+   is not checked at runtime but is only enforced by type checkers.
+   Usage::
 
-    A generic version of :class:`collections.abc.MutableSet`.
+      class Point2D(TypedDict):
+          x: int
+          y: int
+          label: str
 
-.. class:: Mapping(Sized, Collection[KT], Generic[VT_co])
+      a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
+      b: Point2D = {'z': 3, 'label': 'bad'}           # Fails type check
 
-    A generic version of :class:`collections.abc.Mapping`.
-    This type can be used as follows::
+      assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
 
-      def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
-          return word_list[word]
+   The type info for introspection can be accessed via ``Point2D.__annotations__``
+   and ``Point2D.__total__``.  To allow using this feature with older versions
+   of Python that do not support :pep:`526`, ``TypedDict`` supports two additional
+   equivalent syntactic forms::
 
-.. class:: MutableMapping(Mapping[KT, VT])
+      Point2D = TypedDict('Point2D', x=int, y=int, label=str)
+      Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
 
-    A generic version of :class:`collections.abc.MutableMapping`.
+   By default, all keys must be present in a TypedDict. It is possible
+   to override this by specifying totality.
+   Usage::
 
-.. class:: Sequence(Reversible[T_co], Collection[T_co])
+      class point2D(TypedDict, total=False):
+          x: int
+          y: int
 
-    A generic version of :class:`collections.abc.Sequence`.
+   This means that a point2D TypedDict can have any of the keys omitted. A type
+   checker is only expected to support a literal False or True as the value of
+   the total argument. True is the default, and makes all items defined in the
+   class body be required.
 
-.. class:: MutableSequence(Sequence[T])
+   See :pep:`589` for more examples and detailed rules of using ``TypedDict``.
 
-   A generic version of :class:`collections.abc.MutableSequence`.
+   .. versionadded:: 3.8
 
-.. class:: ByteString(Sequence[int])
+Generic concrete collections
+----------------------------
 
-   A generic version of :class:`collections.abc.ByteString`.
+Corresponding to built-in types
+"""""""""""""""""""""""""""""""
 
-   This type represents the types :class:`bytes`, :class:`bytearray`,
-   and :class:`memoryview` of byte sequences.
+.. class:: Dict(dict, MutableMapping[KT, VT])
 
-   As a shorthand for this type, :class:`bytes` can be used to
-   annotate arguments of any of the types mentioned above.
+   A generic version of :class:`dict`.
+   Useful for annotating return types. To annotate arguments it is preferred
+   to use an abstract collection type such as :class:`Mapping`.
 
-.. class:: Deque(deque, MutableSequence[T])
+   This type can be used as follows::
 
-   A generic version of :class:`collections.deque`.
+      def count_words(text: str) -> Dict[str, int]:
+          ...
 
-   .. versionadded:: 3.5.4
-   .. versionadded:: 3.6.1
+   .. deprecated:: 3.9
+      :class:`builtins.dict <dict>` now supports ``[]``. See :pep:`585`.
 
 .. class:: List(list, MutableSequence[T])
 
@@ -701,115 +1076,242 @@ The module defines the following classes, functions and decorators:
       def keep_positives(vector: Sequence[T]) -> List[T]:
           return [item for item in vector if item > 0]
 
+   .. deprecated:: 3.9
+      :class:`builtins.list <list>` now supports ``[]``. See :pep:`585`.
+
 .. class:: Set(set, MutableSet[T])
 
    A generic version of :class:`builtins.set <set>`.
    Useful for annotating return types. To annotate arguments it is preferred
    to use an abstract collection type such as :class:`AbstractSet`.
 
+   .. deprecated:: 3.9
+      :class:`builtins.set <set>` now supports ``[]``. See :pep:`585`.
+
 .. class:: FrozenSet(frozenset, AbstractSet[T_co])
 
    A generic version of :class:`builtins.frozenset <frozenset>`.
 
-.. class:: MappingView(Sized, Iterable[T_co])
+   .. deprecated:: 3.9
+      :class:`builtins.frozenset <frozenset>` now supports ``[]``. See :pep:`585`.
 
-   A generic version of :class:`collections.abc.MappingView`.
+.. note:: :data:`Tuple` is a special form.
 
-.. class:: KeysView(MappingView[KT_co], AbstractSet[KT_co])
+Corresponding to types in :mod:`collections`
+""""""""""""""""""""""""""""""""""""""""""""
 
-   A generic version of :class:`collections.abc.KeysView`.
+.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
 
-.. class:: ItemsView(MappingView, Generic[KT_co, VT_co])
+   A generic version of :class:`collections.defaultdict`.
 
-   A generic version of :class:`collections.abc.ItemsView`.
+   .. versionadded:: 3.5.2
 
-.. class:: ValuesView(MappingView[VT_co])
+   .. deprecated:: 3.9
+      :class:`collections.defaultdict` now supports ``[]``. See :pep:`585`.
 
-   A generic version of :class:`collections.abc.ValuesView`.
+.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])
 
-.. class:: Awaitable(Generic[T_co])
+   A generic version of :class:`collections.OrderedDict`.
 
-   A generic version of :class:`collections.abc.Awaitable`.
+   .. versionadded:: 3.7.2
 
-   .. versionadded:: 3.5.2
+   .. deprecated:: 3.9
+      :class:`collections.OrderedDict` now supports ``[]``. See :pep:`585`.
 
-.. class:: Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co])
+.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT])
 
-   A generic version of :class:`collections.abc.Coroutine`.
-   The variance and order of type variables
-   correspond to those of :class:`Generator`, for example::
+   A generic version of :class:`collections.ChainMap`.
 
-      from typing import List, Coroutine
-      c = None # type: Coroutine[List[str], str, int]
-      ...
-      x = c.send('hi') # type: List[str]
-      async def bar() -> None:
-          x = await c # type: int
+   .. versionadded:: 3.5.4
+   .. versionadded:: 3.6.1
 
-   .. versionadded:: 3.5.3
+   .. deprecated:: 3.9
+      :class:`collections.ChainMap` now supports ``[]``. See :pep:`585`.
 
-.. class:: AsyncIterable(Generic[T_co])
+.. class:: Counter(collections.Counter, Dict[T, int])
 
-   A generic version of :class:`collections.abc.AsyncIterable`.
+   A generic version of :class:`collections.Counter`.
 
-   .. versionadded:: 3.5.2
+   .. versionadded:: 3.5.4
+   .. versionadded:: 3.6.1
 
-.. class:: AsyncIterator(AsyncIterable[T_co])
+   .. deprecated:: 3.9
+      :class:`collections.Counter` now supports ``[]``. See :pep:`585`.
 
-   A generic version of :class:`collections.abc.AsyncIterator`.
+.. class:: Deque(deque, MutableSequence[T])
+
+   A generic version of :class:`collections.deque`.
+
+   .. versionadded:: 3.5.4
+   .. versionadded:: 3.6.1
+
+   .. deprecated:: 3.9
+      :class:`collections.deque` now supports ``[]``. See :pep:`585`.
+
+Other concrete types
+""""""""""""""""""""
+
+.. class:: IO
+           TextIO
+           BinaryIO
+
+   Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])``
+   and ``BinaryIO(IO[bytes])``
+   represent the types of I/O streams such as returned by
+   :func:`open`. These types are also in the ``typing.io`` namespace.
+
+.. class:: Pattern
+           Match
+
+   These type aliases
+   correspond to the return types from :func:`re.compile` and
+   :func:`re.match`.  These types (and the corresponding functions)
+   are generic in ``AnyStr`` and can be made specific by writing
+   ``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or
+   ``Match[bytes]``. These types are also in the ``typing.re`` namespace.
+
+   .. deprecated:: 3.9
+      Classes ``Pattern`` and ``Match`` from :mod:`re` now support ``[]``. See :pep:`585`.
+
+.. class:: Text
+
+   ``Text`` is an alias for ``str``. It is provided to supply a forward
+   compatible path for Python 2 code: in Python 2, ``Text`` is an alias for
+   ``unicode``.
+
+   Use ``Text`` to indicate that a value must contain a unicode string in
+   a manner that is compatible with both Python 2 and Python 3::
+
+       def add_unicode_checkmark(text: Text) -> Text:
+           return text + u' \u2713'
 
    .. versionadded:: 3.5.2
 
-.. class:: ContextManager(Generic[T_co])
+Abstract Base Classes
+---------------------
 
-   A generic version of :class:`contextlib.AbstractContextManager`.
+Corresponding to collections in :mod:`collections.abc`
+""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. class:: AbstractSet(Sized, Collection[T_co])
+
+    A generic version of :class:`collections.abc.Set`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.Set` now supports ``[]``. See :pep:`585`.
+
+.. class:: ByteString(Sequence[int])
+
+   A generic version of :class:`collections.abc.ByteString`.
+
+   This type represents the types :class:`bytes`, :class:`bytearray`,
+   and :class:`memoryview` of byte sequences.
+
+   As a shorthand for this type, :class:`bytes` can be used to
+   annotate arguments of any of the types mentioned above.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.ByteString` now supports ``[]``. See :pep:`585`.
+
+.. class:: Collection(Sized, Iterable[T_co], Container[T_co])
+
+   A generic version of :class:`collections.abc.Collection`
 
-   .. versionadded:: 3.5.4
    .. versionadded:: 3.6.0
 
-.. class:: AsyncContextManager(Generic[T_co])
+   .. deprecated:: 3.9
+      :class:`collections.abc.Collection` now supports ``[]``. See :pep:`585`.
 
-   A generic version of :class:`contextlib.AbstractAsyncContextManager`.
+.. class:: Container(Generic[T_co])
 
-   .. versionadded:: 3.5.4
-   .. versionadded:: 3.6.2
+    A generic version of :class:`collections.abc.Container`.
 
-.. class:: Dict(dict, MutableMapping[KT, VT])
+   .. deprecated:: 3.9
+      :class:`collections.abc.Container` now supports ``[]``. See :pep:`585`.
 
-   A generic version of :class:`dict`.
-   Useful for annotating return types. To annotate arguments it is preferred
-   to use an abstract collection type such as :class:`Mapping`.
+.. class:: ItemsView(MappingView, Generic[KT_co, VT_co])
 
-   This type can be used as follows::
+   A generic version of :class:`collections.abc.ItemsView`.
 
-      def count_words(text: str) -> Dict[str, int]:
-          ...
+   .. deprecated:: 3.9
+      :class:`collections.abc.ItemsView` now supports ``[]``. See :pep:`585`.
 
-.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
+.. class:: KeysView(MappingView[KT_co], AbstractSet[KT_co])
 
-   A generic version of :class:`collections.defaultdict`.
+   A generic version of :class:`collections.abc.KeysView`.
 
-   .. versionadded:: 3.5.2
+   .. deprecated:: 3.9
+      :class:`collections.abc.KeysView` now supports ``[]``. See :pep:`585`.
 
-.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])
+.. class:: Mapping(Sized, Collection[KT], Generic[VT_co])
 
-   A generic version of :class:`collections.OrderedDict`.
+    A generic version of :class:`collections.abc.Mapping`.
+    This type can be used as follows::
 
-   .. versionadded:: 3.7.2
+      def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
+          return word_list[word]
 
-.. class:: Counter(collections.Counter, Dict[T, int])
+   .. deprecated:: 3.9
+      :class:`collections.abc.Mapping` now supports ``[]``. See :pep:`585`.
 
-   A generic version of :class:`collections.Counter`.
+.. class:: MappingView(Sized, Iterable[T_co])
 
-   .. versionadded:: 3.5.4
-   .. versionadded:: 3.6.1
+   A generic version of :class:`collections.abc.MappingView`.
 
-.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT])
+   .. deprecated:: 3.9
+      :class:`collections.abc.MappingView` now supports ``[]``. See :pep:`585`.
 
-   A generic version of :class:`collections.ChainMap`.
+.. class:: MutableMapping(Mapping[KT, VT])
 
-   .. versionadded:: 3.5.4
-   .. versionadded:: 3.6.1
+    A generic version of :class:`collections.abc.MutableMapping`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.MutableMapping` now supports ``[]``. See :pep:`585`.
+
+.. class:: MutableSequence(Sequence[T])
+
+   A generic version of :class:`collections.abc.MutableSequence`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.MutableSequence` now supports ``[]``. See :pep:`585`.
+
+.. class:: MutableSet(AbstractSet[T])
+
+    A generic version of :class:`collections.abc.MutableSet`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.MutableSet` now supports ``[]``. See :pep:`585`.
+
+.. class:: Sequence(Reversible[T_co], Collection[T_co])
+
+    A generic version of :class:`collections.abc.Sequence`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.Sequence` now supports ``[]``. See :pep:`585`.
+
+.. class:: ValuesView(MappingView[VT_co])
+
+   A generic version of :class:`collections.abc.ValuesView`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.ValuesView` now supports ``[]``. See :pep:`585`.
+
+Corresponding to other types in :mod:`collections.abc`
+""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. class:: Iterable(Generic[T_co])
+
+    A generic version of :class:`collections.abc.Iterable`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.Iterable` now supports ``[]``. See :pep:`585`.
+
+.. class:: Iterator(Iterable[T_co])
+
+    A generic version of :class:`collections.abc.Iterator`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.Iterator` now supports ``[]``. See :pep:`585`.
 
 .. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
 
@@ -842,6 +1344,45 @@ The module defines the following classes, functions and decorators:
               yield start
               start += 1
 
+   .. deprecated:: 3.9
+      :class:`collections.abc.Generator` now supports ``[]``. See :pep:`585`.
+
+.. class:: Hashable
+
+   An alias to :class:`collections.abc.Hashable`
+
+.. class:: Reversible(Iterable[T_co])
+
+    A generic version of :class:`collections.abc.Reversible`.
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.Reversible` now supports ``[]``. See :pep:`585`.
+
+.. class:: Sized
+
+   An alias to :class:`collections.abc.Sized`
+
+Asynchronous programming
+""""""""""""""""""""""""
+
+.. class:: Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co])
+
+   A generic version of :class:`collections.abc.Coroutine`.
+   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]
+      ...
+      x = c.send('hi') # type: List[str]
+      async def bar() -> None:
+          x = await c # type: int
+
+   .. versionadded:: 3.5.3
+
+   .. deprecated:: 3.9
+      :class:`collections.abc.Coroutine` now supports ``[]``. See :pep:`585`.
+
 .. class:: AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])
 
    An async generator can be annotated by the generic type
@@ -875,162 +1416,99 @@ The module defines the following classes, functions and decorators:
 
    .. versionadded:: 3.6.1
 
-.. class:: Text
-
-   ``Text`` is an alias for ``str``. It is provided to supply a forward
-   compatible path for Python 2 code: in Python 2, ``Text`` is an alias for
-   ``unicode``.
+   .. deprecated:: 3.9
+      :class:`collections.abc.AsyncGenerator` now supports ``[]``. See :pep:`585`.
 
-   Use ``Text`` to indicate that a value must contain a unicode string in
-   a manner that is compatible with both Python 2 and Python 3::
+.. class:: AsyncIterable(Generic[T_co])
 
-       def add_unicode_checkmark(text: Text) -> Text:
-           return text + u' \u2713'
+   A generic version of :class:`collections.abc.AsyncIterable`.
 
    .. versionadded:: 3.5.2
 
-.. class:: IO
-           TextIO
-           BinaryIO
-
-   Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])``
-   and ``BinaryIO(IO[bytes])``
-   represent the types of I/O streams such as returned by
-   :func:`open`.
-
-.. class:: Pattern
-           Match
-
-   These type aliases
-   correspond to the return types from :func:`re.compile` and
-   :func:`re.match`.  These types (and the corresponding functions)
-   are generic in ``AnyStr`` and can be made specific by writing
-   ``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or
-   ``Match[bytes]``.
+   .. deprecated:: 3.9
+      :class:`collections.abc.AsyncIterable` now supports ``[]``. See :pep:`585`.
 
-.. class:: NamedTuple
-
-   Typed version of :func:`collections.namedtuple`.
-
-   Usage::
-
-       class Employee(NamedTuple):
-           name: str
-           id: int
-
-   This is equivalent to::
+.. class:: AsyncIterator(AsyncIterable[T_co])
 
-       Employee = collections.namedtuple('Employee', ['name', 'id'])
+   A generic version of :class:`collections.abc.AsyncIterator`.
 
-   To give a field a default value, you can assign to it in the class body::
+   .. versionadded:: 3.5.2
 
-      class Employee(NamedTuple):
-          name: str
-          id: int = 3
+   .. deprecated:: 3.9
+      :class:`collections.abc.AsyncIterator` now supports ``[]``. See :pep:`585`.
 
-      employee = Employee('Guido')
-      assert employee.id == 3
+.. class:: Awaitable(Generic[T_co])
 
-   Fields with a default value must come after any fields without a default.
+   A generic version of :class:`collections.abc.Awaitable`.
 
-   The resulting class has an extra attribute ``__annotations__`` giving a
-   dict that maps the field names to the field types.  (The field names are in
-   the ``_fields`` attribute and the default values are in the
-   ``_field_defaults`` attribute both of which are part of the namedtuple
-   API.)
+   .. versionadded:: 3.5.2
 
-   ``NamedTuple`` subclasses can also have docstrings and methods::
+   .. deprecated:: 3.9
+      :class:`collections.abc.Awaitable` now supports ``[]``. See :pep:`585`.
 
-      class Employee(NamedTuple):
-          """Represents an employee."""
-          name: str
-          id: int = 3
 
-          def __repr__(self) -> str:
-              return f'<Employee {self.name}, id={self.id}>'
+Context manager types
+"""""""""""""""""""""
 
-   Backward-compatible usage::
+.. class:: ContextManager(Generic[T_co])
 
-       Employee = NamedTuple('Employee', [('name', str), ('id', int)])
+   A generic version of :class:`contextlib.AbstractContextManager`.
 
-   .. versionchanged:: 3.6
-      Added support for :pep:`526` variable annotation syntax.
+   .. versionadded:: 3.5.4
+   .. versionadded:: 3.6.0
 
-   .. versionchanged:: 3.6.1
-      Added support for default values, methods, and docstrings.
+   .. deprecated:: 3.9
+      :class:`collections.contextlib.AbstractContextManager` now supports ``[]``. See :pep:`585`.
 
-   .. versionchanged:: 3.8
-      The ``_field_types`` and ``__annotations__`` attributes are
-      now regular dictionaries instead of instances of ``OrderedDict``.
+.. class:: AsyncContextManager(Generic[T_co])
 
-   .. versionchanged:: 3.9
-      Removed the ``_field_types`` attribute in favor of the more
-      standard ``__annotations__`` attribute which has the same information.
+   A generic version of :class:`contextlib.AbstractAsyncContextManager`.
 
+   .. versionadded:: 3.5.4
+   .. versionadded:: 3.6.2
 
-.. class:: TypedDict(dict)
+   .. deprecated:: 3.9
+      :class:`collections.contextlib.AbstractAsyncContextManager` now supports ``[]``. See :pep:`585`.
 
-   A simple typed namespace. At runtime it is equivalent to
-   a plain :class:`dict`.
+Protocols
+---------
 
-   ``TypedDict`` creates a dictionary type that expects all of its
-   instances to have a certain set of keys, where each key is
-   associated with a value of a consistent type. This expectation
-   is not checked at runtime but is only enforced by type checkers.
-   Usage::
+These protocols are decorated with :func:`runtime_checkable`.
 
-      class Point2D(TypedDict):
-          x: int
-          y: int
-          label: str
+.. class:: SupportsAbs
 
-      a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
-      b: Point2D = {'z': 3, 'label': 'bad'}           # Fails type check
+    An ABC with one abstract method ``__abs__`` that is covariant
+    in its return type.
 
-      assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
+.. class:: SupportsBytes
 
-   The type info for introspection can be accessed via ``Point2D.__annotations__``
-   and ``Point2D.__total__``.  To allow using this feature with older versions
-   of Python that do not support :pep:`526`, ``TypedDict`` supports two additional
-   equivalent syntactic forms::
+    An ABC with one abstract method ``__bytes__``.
 
-      Point2D = TypedDict('Point2D', x=int, y=int, label=str)
-      Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
+.. class:: SupportsComplex
 
-   By default, all keys must be present in a TypedDict. It is possible
-   to override this by specifying totality.
-   Usage::
+    An ABC with one abstract method ``__complex__``.
 
-      class point2D(TypedDict, total=False):
-          x: int
-          y: int
+.. class:: SupportsFloat
 
-   This means that a point2D TypedDict can have any of the keys omitted. A type
-   checker is only expected to support a literal False or True as the value of
-   the total argument. True is the default, and makes all items defined in the
-   class body be required.
+    An ABC with one abstract method ``__float__``.
 
-   See :pep:`589` for more examples and detailed rules of using ``TypedDict``.
+.. class:: SupportsIndex
 
-   .. versionadded:: 3.8
+    An ABC with one abstract method ``__index__``.
 
-.. class:: ForwardRef
+    .. versionadded:: 3.8
 
-   A class used for internal typing representation of string forward references.
-   For example, ``List["SomeClass"]`` is implicitly transformed into
-   ``List[ForwardRef("SomeClass")]``.  This class should not be instantiated by
-   a user, but may be used by introspection tools.
+.. class:: SupportsInt
 
-.. function:: NewType(name, tp)
+    An ABC with one abstract method ``__int__``.
 
-   A helper function to indicate a distinct type to a typechecker,
-   see :ref:`distinct`. At runtime it returns a function that returns
-   its argument. Usage::
+.. class:: SupportsRound
 
-      UserId = NewType('UserId', int)
-      first_user = UserId(1)
+    An ABC with one abstract method ``__round__``
+    that is covariant in its return type.
 
-   .. versionadded:: 3.5.2
+Functions and decorators
+------------------------
 
 .. function:: cast(typ, val)
 
@@ -1041,54 +1519,6 @@ The module defines the following classes, functions and decorators:
    runtime we intentionally don't check anything (we want this
    to be as fast as possible).
 
-.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False)
-
-   Return a dictionary containing type hints for a function, method, module
-   or class object.
-
-   This is often the same as ``obj.__annotations__``. In addition,
-   forward references encoded as string literals are handled by evaluating
-   them in ``globals`` and ``locals`` namespaces. If necessary,
-   ``Optional[t]`` is added for function and method annotations if a default
-   value equal to ``None`` is set. For a class ``C``, return
-   a dictionary constructed by merging all the ``__annotations__`` along
-   ``C.__mro__`` in reverse order.
-
-   The function recursively replaces all ``Annotated[T, ...]`` with ``T``,
-   unless ``include_extras`` is set to ``True`` (see :class:`Annotated` for
-   more information). For example::
-
-       class Student(NamedTuple):
-           name: Annotated[str, 'some marker']
-
-       get_type_hints(Student) == {'name': str}
-       get_type_hints(Student, include_extras=False) == {'name': str}
-       get_type_hints(Student, include_extras=True) == {
-           'name': Annotated[str, 'some marker']
-       }
-
-   .. versionchanged:: 3.9
-      Added ``include_extras`` parameter as part of :pep:`593`.
-
-.. function:: get_origin(tp)
-.. function:: get_args(tp)
-
-   Provide basic introspection for generic types and special typing forms.
-
-   For a typing object of the form ``X[Y, Z, ...]`` these functions return
-   ``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or
-   :mod:`collections` class, it gets normalized to the original class.
-   For unsupported objects return ``None`` and ``()`` correspondingly.
-   Examples::
-
-      assert get_origin(Dict[str, int]) is dict
-      assert get_args(Dict[int, str]) == (int, str)
-
-      assert get_origin(Union[int, str]) is Union
-      assert get_args(Union[int, str]) == (int, str)
-
-   .. versionadded:: 3.8
-
 .. decorator:: overload
 
    The ``@overload`` decorator allows describing functions and methods
@@ -1177,212 +1607,66 @@ The module defines the following classes, functions and decorators:
    Note that returning instances of private classes is not recommended.
    It is usually preferable to make such classes public.
 
-.. decorator:: runtime_checkable
-
-   Mark a protocol class as a runtime protocol.
-
-   Such a protocol can be used with :func:`isinstance` and :func:`issubclass`.
-   This raises :exc:`TypeError` when applied to a non-protocol class.  This
-   allows a simple-minded structural check, very similar to "one trick ponies"
-   in :mod:`collections.abc` such as :class:`Iterable`.  For example::
-
-      @runtime_checkable
-      class Closable(Protocol):
-          def close(self): ...
-
-      assert isinstance(open('/some/file'), Closable)
-
-   **Warning:** this will check only the presence of the required methods,
-   not their type signatures!
-
-   .. versionadded:: 3.8
-
-.. data:: Any
-
-   Special type indicating an unconstrained type.
-
-   * Every type is compatible with :data:`Any`.
-   * :data:`Any` is compatible with every type.
-
-.. data:: NoReturn
-
-   Special type indicating that a function never returns.
-   For example::
-
-      from typing import NoReturn
-
-      def stop() -> NoReturn:
-          raise RuntimeError('no way')
-
-   .. versionadded:: 3.5.4
-   .. versionadded:: 3.6.2
-
-.. data:: Union
-
-   Union type; ``Union[X, Y]`` means either X or Y.
-
-   To define a union, use e.g. ``Union[int, str]``.  Details:
-
-   * The arguments must be types and there must be at least one.
-
-   * Unions of unions are flattened, e.g.::
-
-       Union[Union[int, str], float] == Union[int, str, float]
-
-   * Unions of a single argument vanish, e.g.::
-
-       Union[int] == int  # The constructor actually returns int
-
-   * Redundant arguments are skipped, e.g.::
-
-       Union[int, str, int] == Union[int, str]
-
-   * When comparing unions, the argument order is ignored, e.g.::
-
-       Union[int, str] == Union[str, int]
-
-   * You cannot subclass or instantiate a union.
-
-   * You cannot write ``Union[X][Y]``.
-
-   * You can use ``Optional[X]`` as a shorthand for ``Union[X, None]``.
-
-   .. versionchanged:: 3.7
-      Don't remove explicit subclasses from unions at runtime.
-
-.. data:: Optional
-
-   Optional type.
-
-   ``Optional[X]`` is equivalent to ``Union[X, None]``.
-
-   Note that this is not the same concept as an optional argument,
-   which is one that has a default.  An optional argument with a
-   default does not require the ``Optional`` qualifier on its type
-   annotation just because it is optional. For example::
-
-      def foo(arg: int = 0) -> None:
-          ...
-
-   On the other hand, if an explicit value of ``None`` is allowed, the
-   use of ``Optional`` is appropriate, whether the argument is optional
-   or not. For example::
-
-      def foo(arg: Optional[int] = None) -> None:
-          ...
-
-.. data:: Tuple
+Introspection helpers
+---------------------
 
-   Tuple type; ``Tuple[X, Y]`` is the type of a tuple of two items
-   with the first item of type X and the second of type Y. The type of
-   the empty tuple can be written as ``Tuple[()]``.
-
-   Example: ``Tuple[T1, T2]`` is a tuple of two elements corresponding
-   to type variables T1 and T2.  ``Tuple[int, float, str]`` is a tuple
-   of an int, a float and a string.
-
-   To specify a variable-length tuple of homogeneous type,
-   use literal ellipsis, e.g. ``Tuple[int, ...]``. A plain :data:`Tuple`
-   is equivalent to ``Tuple[Any, ...]``, and in turn to :class:`tuple`.
-
-.. data:: Callable
-
-   Callable type; ``Callable[[int], str]`` is a function of (int) -> str.
-
-   The subscription syntax must always be used with exactly two
-   values: the argument list and the return type.  The argument list
-   must be a list of types or an ellipsis; the return type must be
-   a single type.
-
-   There is no syntax to indicate optional or keyword arguments;
-   such function types are rarely used as callback types.
-   ``Callable[..., ReturnType]`` (literal ellipsis) can be used to
-   type hint a callable taking any number of arguments and returning
-   ``ReturnType``.  A plain :data:`Callable` is equivalent to
-   ``Callable[..., Any]``, and in turn to
-   :class:`collections.abc.Callable`.
-
-.. data:: Literal
-
-   A type that can be used to indicate to type checkers that the
-   corresponding variable or function parameter has a value equivalent to
-   the provided literal (or one of several literals). For example::
-
-      def validate_simple(data: Any) -> Literal[True]:  # always returns True
-          ...
-
-      MODE = Literal['r', 'rb', 'w', 'wb']
-      def open_helper(file: str, mode: MODE) -> str:
-          ...
-
-      open_helper('/some/path', 'r')  # Passes type check
-      open_helper('/other/path', 'typo')  # Error in type checker
-
-   ``Literal[...]`` cannot be subclassed. At runtime, an arbitrary value
-   is allowed as type argument to ``Literal[...]``, but type checkers may
-   impose restrictions. See :pep:`586` for more details about literal types.
-
-   .. versionadded:: 3.8
-
-.. data:: ClassVar
-
-   Special type construct to mark class variables.
-
-   As introduced in :pep:`526`, a variable annotation wrapped in ClassVar
-   indicates that a given attribute is intended to be used as a class variable
-   and should not be set on instances of that class. Usage::
+.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False)
 
-      class Starship:
-          stats: ClassVar[Dict[str, int]] = {} # class variable
-          damage: int = 10                     # instance variable
+   Return a dictionary containing type hints for a function, method, module
+   or class object.
 
-   :data:`ClassVar` accepts only types and cannot be further subscribed.
+   This is often the same as ``obj.__annotations__``. In addition,
+   forward references encoded as string literals are handled by evaluating
+   them in ``globals`` and ``locals`` namespaces. If necessary,
+   ``Optional[t]`` is added for function and method annotations if a default
+   value equal to ``None`` is set. For a class ``C``, return
+   a dictionary constructed by merging all the ``__annotations__`` along
+   ``C.__mro__`` in reverse order.
 
-   :data:`ClassVar` is not a class itself, and should not
-   be used with :func:`isinstance` or :func:`issubclass`.
-   :data:`ClassVar` does not change Python runtime behavior, but
-   it can be used by third-party type checkers. For example, a type checker
-   might flag the following code as an error::
+   The function recursively replaces all ``Annotated[T, ...]`` with ``T``,
+   unless ``include_extras`` is set to ``True`` (see :class:`Annotated` for
+   more information). For example::
 
-      enterprise_d = Starship(3000)
-      enterprise_d.stats = {} # Error, setting class variable on instance
-      Starship.stats = {}     # This is OK
+       class Student(NamedTuple):
+           name: Annotated[str, 'some marker']
 
-   .. versionadded:: 3.5.3
+       get_type_hints(Student) == {'name': str}
+       get_type_hints(Student, include_extras=False) == {'name': str}
+       get_type_hints(Student, include_extras=True) == {
+           'name': Annotated[str, 'some marker']
+       }
 
-.. data:: Final
+   .. versionchanged:: 3.9
+      Added ``include_extras`` parameter as part of :pep:`593`.
 
-   A special typing construct to indicate to type checkers that a name
-   cannot be re-assigned or overridden in a subclass. For example::
+.. function:: get_args(tp)
+.. function:: get_origin(tp)
 
-      MAX_SIZE: Final = 9000
-      MAX_SIZE += 1  # Error reported by type checker
+   Provide basic introspection for generic types and special typing forms.
 
-      class Connection:
-          TIMEOUT: Final[int] = 10
+   For a typing object of the form ``X[Y, Z, ...]`` these functions return
+   ``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or
+   :mod:`collections` class, it gets normalized to the original class.
+   For unsupported objects return ``None`` and ``()`` correspondingly.
+   Examples::
 
-      class FastConnector(Connection):
-          TIMEOUT = 1  # Error reported by type checker
+      assert get_origin(Dict[str, int]) is dict
+      assert get_args(Dict[int, str]) == (int, str)
 
-   There is no runtime checking of these properties. See :pep:`591` for
-   more details.
+      assert get_origin(Union[int, str]) is Union
+      assert get_args(Union[int, str]) == (int, str)
 
    .. versionadded:: 3.8
 
-.. data:: AnyStr
-
-   ``AnyStr`` is a type variable defined as
-   ``AnyStr = TypeVar('AnyStr', str, bytes)``.
-
-   It is meant to be used for functions that may accept any kind of string
-   without allowing different kinds of strings to mix. For example::
+.. class:: ForwardRef
 
-      def concat(a: AnyStr, b: AnyStr) -> AnyStr:
-          return a + b
+   A class used for internal typing representation of string forward references.
+   For example, ``List["SomeClass"]`` is implicitly transformed into
+   ``List[ForwardRef("SomeClass")]``.  This class should not be instantiated by
+   a user, but may be used by introspection tools.
 
-      concat(u"foo", u"bar")  # Ok, output has type 'unicode'
-      concat(b"foo", b"bar")  # Ok, output has type 'bytes'
-      concat(u"foo", b"bar")  # Error, cannot mix unicode and bytes
+Constant
+--------
 
 .. data:: TYPE_CHECKING
 
@@ -1395,93 +1679,18 @@ The module defines the following classes, functions and decorators:
       def fun(arg: 'expensive_mod.SomeType') -> None:
           local_var: expensive_mod.AnotherType = other_fun()
 
-   Note that the first type annotation must be enclosed in quotes, making it a
+   The first type annotation must be enclosed in quotes, making it a
    "forward reference", to hide the ``expensive_mod`` reference from the
    interpreter runtime.  Type annotations for local variables are not
    evaluated, so the second annotation does not need to be enclosed in quotes.
 
-   .. versionadded:: 3.5.2
-
-.. data:: Annotated
-
-   A type, introduced in :pep:`593` (``Flexible function and variable
-   annotations``), to decorate existing types with context-specific metadata
-   (possibly multiple pieces of it, as ``Annotated`` is variadic).
-   Specifically, a type ``T`` can be annotated with metadata ``x`` via the
-   typehint ``Annotated[T, x]``. This metadata can be used for either static
-   analysis or at runtime. If a library (or tool) encounters a typehint
-   ``Annotated[T, x]`` and has no special logic for metadata ``x``, it
-   should ignore it and simply treat the type as ``T``. Unlike the
-   ``no_type_check`` functionality that currently exists in the ``typing``
-   module which completely disables typechecking annotations on a function
-   or a class, the ``Annotated`` type allows for both static typechecking
-   of ``T`` (e.g., via mypy or Pyre, which can safely ignore ``x``)
-   together with runtime access to ``x`` within a specific application.
-
-   Ultimately, the responsibility of how to interpret the annotations (if
-   at all) is the responsibility of the tool or library encountering the
-   ``Annotated`` type. A tool or library encountering an ``Annotated`` type
-   can scan through the annotations to determine if they are of interest
-   (e.g., using ``isinstance()``).
-
-   When a tool or a library does not support annotations or encounters an
-   unknown annotation it should just ignore it and treat annotated type as
-   the underlying type.
-
-   It's up to the tool consuming the annotations to decide whether the
-   client is allowed to have several annotations on one type and how to
-   merge those annotations.
-
-   Since the ``Annotated`` type allows you to put several annotations of
-   the same (or different) type(s) on any node, the tools or libraries
-   consuming those annotations are in charge of dealing with potential
-   duplicates. For example, if you are doing value range analysis you might
-   allow this::
-
-       T1 = Annotated[int, ValueRange(-10, 5)]
-       T2 = Annotated[T1, ValueRange(-20, 3)]
+   .. note::
 
-   Passing ``include_extras=True`` to :func:`get_type_hints` lets one
-   access the extra annotations at runtime.
-
-   The details of the syntax:
+      If ``from __future__ import annotations`` is used in Python 3.7 or later,
+      annotations are not evaluated at function definition time.
+      Instead, the are stored as strings in ``__annotations__``,
+      This makes it unnecessary to use quotes around the annotation.
+      (see :pep:`563`).
 
-   * The first argument to ``Annotated`` must be a valid type
-
-   * Multiple type annotations are supported (``Annotated`` supports variadic
-     arguments)::
-
-       Annotated[int, ValueRange(3, 10), ctype("char")]
-
-   * ``Annotated`` must be called with at least two arguments (
-     ``Annotated[int]`` is not valid)
-
-   * The order of the annotations is preserved and matters for equality
-     checks::
-
-       Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
-           int, ctype("char"), ValueRange(3, 10)
-       ]
-
-   * Nested ``Annotated`` types are flattened, with metadata ordered
-     starting with the innermost annotation::
-
-       Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
-           int, ValueRange(3, 10), ctype("char")
-       ]
-
-   * Duplicated annotations are not removed::
-
-       Annotated[int, ValueRange(3, 10)] != Annotated[
-           int, ValueRange(3, 10), ValueRange(3, 10)
-       ]
-
-   * ``Annotated`` can be used with nested and generic aliases::
-
-       T = TypeVar('T')
-       Vec = Annotated[List[Tuple[T, T]], MaxLen(10)]
-       V = Vec[int]
-
-       V == Annotated[List[Tuple[int, int]], MaxLen(10)]
+   .. versionadded:: 3.5.2
 
-   .. versionadded:: 3.9