[3.10] Improve the typing docs (GH-92264) (#92270)

Co-authored-by: Alex Waygood <[email protected]>.
(cherry picked from commit 27e3665)

Co-authored-by: Jelle Zijlstra <[email protected]>

Author: JelleZijlstra

Doc/library/typing.rst

@@ -115,7 +115,7 @@ Note that ``None`` as a type hint is a special case and is replaced by
 NewType
 =======
 
-Use the :class:`NewType` helper class to create distinct types::
+Use the :class:`NewType` helper to create distinct types::
 
    from typing import NewType
 
@@ -144,7 +144,7 @@ accidentally creating a ``UserId`` in an invalid way::
 
 Note that these checks are enforced only by the static type checker. At runtime,
 the statement ``Derived = NewType('Derived', Base)`` will make ``Derived`` a
-class that immediately returns whatever parameter you pass it. That means
+callable that immediately returns whatever parameter you pass it. That means
 the expression ``Derived(some_value)`` does not create a new class or introduce
 much overhead beyond that of a regular function call.
 
@@ -232,7 +232,7 @@ respectively.
    See :pep:`612` for more information.
 
 .. seealso::
-   The documentation for :class:`ParamSpec` and :class:`Concatenate` provide
+   The documentation for :class:`ParamSpec` and :class:`Concatenate` provides
    examples of usage in ``Callable``.
 
 .. _generics:
@@ -401,7 +401,7 @@ to this is that a list of types can be used to substitute a :class:`ParamSpec`::
 Furthermore, a generic with only one parameter specification variable will accept
 parameter lists in the forms ``X[[Type1, Type2, ...]]`` and also
 ``X[Type1, Type2, ...]`` for aesthetic reasons.  Internally, the latter is converted
-to the former and are thus equivalent::
+to the former, so the following are equivalent::
 
    >>> class X(Generic[P]): ...
    ...
@@ -505,7 +505,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
+Initially :pep:`484` defined the Python static type system as using
 *nominal subtyping*. This means that a class ``A`` is allowed where
 a class ``B`` is expected if and only if ``A`` is a subclass of ``B``.
 
@@ -756,7 +756,6 @@ These can be used as types in annotations using ``[]``, each having a unique syn
 
       def with_lock(f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
           '''A type-safe decorator which provides a lock.'''
-          global my_lock
           def inner(*args: P.args, **kwargs: P.kwargs) -> R:
               # Provide the lock as the first argument.
               return f(my_lock, *args, **kwargs)
@@ -912,7 +911,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
    ``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``)
+   of ``T`` (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
@@ -1016,7 +1015,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
    2. If the return value is ``True``, the type of its argument
       is the type inside ``TypeGuard``.
 
-      For example::
+   For example::
 
          def is_str_list(val: List[object]) -> TypeGuard[List[str]]:
              '''Determines whether all objects in the list are strings'''
@@ -1230,11 +1229,11 @@ These are not used in annotations. They are building blocks for creating generic
    use a :class:`TypeVar` with bound ``Callable[..., Any]``.  However this
    causes two problems:
 
-      1. The type checker can't type check the ``inner`` function because
-         ``*args`` and ``**kwargs`` have to be typed :data:`Any`.
-      2. :func:`~cast` may be required in the body of the ``add_logging``
-         decorator when returning the ``inner`` function, or the static type
-         checker must be told to ignore the ``return inner``.
+   1. The type checker can't type check the ``inner`` function because
+      ``*args`` and ``**kwargs`` have to be typed :data:`Any`.
+   2. :func:`~cast` may be required in the body of the ``add_logging``
+      decorator when returning the ``inner`` function, or the static type
+      checker must be told to ignore the ``return inner``.
 
    .. attribute:: args
    .. attribute:: kwargs
@@ -1392,7 +1391,7 @@ These are not used in annotations. They are building blocks for declaring types.
    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
+   ``_field_defaults`` attribute, both of which are part of the :func:`~collections.namedtuple`
    API.)
 
    ``NamedTuple`` subclasses can also have docstrings and methods::
@@ -1467,7 +1466,7 @@ These are not used in annotations. They are building blocks for declaring types.
       Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
 
    The functional syntax should also be used when any of the keys are not valid
-   :ref:`identifiers`, for example because they are keywords or contain hyphens.
+   :ref:`identifiers <identifiers>`, for example because they are keywords or contain hyphens.
    Example::
 
       # raises SyntaxError
@@ -1506,7 +1505,7 @@ These are not used in annotations. They are building blocks for declaring types.
           y: int
           z: int
 
-   A ``TypedDict`` cannot inherit from a non-TypedDict class,
+   A ``TypedDict`` cannot inherit from a non-\ ``TypedDict`` class,
    notably including :class:`Generic`. For example::
 
       class X(TypedDict):
@@ -1915,7 +1914,7 @@ Corresponding to other types in :mod:`collections.abc`
 
 .. class:: Hashable
 
-   An alias to :class:`collections.abc.Hashable`
+   An alias to :class:`collections.abc.Hashable`.
 
 .. class:: Reversible(Iterable[T_co])
 
@@ -1927,7 +1926,7 @@ Corresponding to other types in :mod:`collections.abc`
 
 .. class:: Sized
 
-   An alias to :class:`collections.abc.Sized`
+   An alias to :class:`collections.abc.Sized`.
 
 Asynchronous programming
 """"""""""""""""""""""""
@@ -2132,7 +2131,7 @@ Functions and decorators
               ...
       class Sub(Base):
           def done(self) -> None:  # Error reported by type checker
-                ...
+              ...
 
       @final
       class Leaf:
@@ -2293,8 +2292,8 @@ Constant
 
       If ``from __future__ import annotations`` is used in Python 3.7 or later,
       annotations are not evaluated at function definition time.
-      Instead, they are stored as strings in ``__annotations__``,
-      This makes it unnecessary to use quotes around the annotation.
+      Instead, they are stored as strings in ``__annotations__``.
+      This makes it unnecessary to use quotes around the annotation
       (see :pep:`563`).
 
    .. versionadded:: 3.5.2