[3.14] gh-149995: Update typing.py docstrings and documentation (#150216)

[3.14] gh-149995: Update typing.py docstrings and documentation (GH-149996)

Some of these docstrings read as if they were written when typing.py was
first written, and things have evolved since then.

A few motivations:
- Call protocols protocols instead of ABCs. They are also ABCs, but the fact
  they are protocols is more relevant to typing.
- Avoid recommending direct use of .__annotations__ and steer users to
  annotationlib instead.
- For TypedDict, mention NotRequired before total=False since it is more
  general and probably more frequently useful.
- For overloads, mention runtime use first instead of stub use. I think early on
  there was talk of allowing overload only in stubs, but it is now heavily used at
  runtime too and that's more likely to be relevant to users.
(cherry picked from commit f159419)

Author: JelleZijlstra

Doc/library/typing.rst

@@ -719,8 +719,8 @@ 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
-compatible with every type.
+every type as assignable to :data:`Any` and :data:`Any` as assignable to
+every type.
 
 This means that it is possible to perform any operation or method call on a
 value of type :data:`Any` and assign it to any variable::
@@ -785,7 +785,7 @@ it as a return value) of a more specialized type is a type error. For example::
    hash_a(42)
    hash_a("foo")
 
-   # Passes type checking, since Any is compatible with all types
+   # Passes type checking, since Any is assignable to all types
    hash_b(42)
    hash_b("foo")
 
@@ -851,8 +851,8 @@ using ``[]``.
 
    Special type indicating an unconstrained type.
 
-   * Every type is compatible with :data:`Any`.
-   * :data:`Any` is compatible with every type.
+   * Every type is assignable to :data:`Any`.
+   * :data:`Any` is assignable to every type.
 
    .. versionchanged:: 3.11
       :data:`Any` can now be used as a base class. This can be useful for
@@ -1292,10 +1292,10 @@ These can be used as types in annotations. They all support subscription using
 
    :data:`ClassVar` accepts only types and cannot be further subscribed.
 
-   :data:`ClassVar` is not a class itself, and should not
+   :data:`ClassVar` is not a class itself, and cannot
    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
+   it can be used by static type checkers. For example, a type checker
    might flag the following code as an error::
 
       enterprise_d = Starship(3000)
@@ -1365,7 +1365,7 @@ These can be used as types in annotations. They all support subscription using
 
       def mutate_movie(m: Movie) -> None:
          m["year"] = 1999  # allowed
-         m["title"] = "The Matrix"  # typechecker error
+         m["title"] = "The Matrix"  # type checker error
 
    There is no runtime checking for this property.
 
@@ -2381,9 +2381,9 @@ types.
 
    Fields with a default value must come after any fields without a default.
 
-   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
+   The types for each field name can be retrieved by calling
+   :func:`annotationlib.get_annotations` on the resulting class. (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 :func:`~collections.namedtuple`
    API.)
 
@@ -2457,7 +2457,7 @@ types.
 
    Helper class to create low-overhead :ref:`distinct types <distinct>`.
 
-   A ``NewType`` is considered a distinct type by a typechecker. At runtime,
+   A ``NewType`` is considered a distinct type by a type checker. At runtime,
    however, calling a ``NewType`` returns its argument unchanged.
 
    Usage::
@@ -2532,7 +2532,7 @@ types.
    Mark a protocol class as a runtime protocol.
 
    Such a protocol can be used with :func:`isinstance` and :func:`issubclass`.
-   This allows a simple-minded structural check, very similar to "one trick ponies"
+   This allows a simple-minded structural check, very similar to "one-trick ponies"
    in :mod:`collections.abc` such as :class:`~collections.abc.Iterable`.  For example::
 
       @runtime_checkable
@@ -2723,9 +2723,9 @@ types.
           key: T
           group: list[T]
 
-   A ``TypedDict`` can be introspected via annotations dicts
-   (see :ref:`annotations-howto` for more information on annotations best practices),
-   :attr:`__total__`, :attr:`__required_keys__`, and :attr:`__optional_keys__`.
+   A ``TypedDict`` can be introspected via :func:`annotationlib.get_annotations`
+   (see :ref:`annotations-howto` for more information on annotations best practices)
+   and the following attributes:
 
    .. attribute:: __total__
 
@@ -2766,7 +2766,7 @@ types.
 
       For backwards compatibility with Python 3.10 and below,
       it is also possible to use inheritance to declare both required and
-      non-required keys in the same ``TypedDict`` . This is done by declaring a
+      non-required keys in the same ``TypedDict``. This is done by declaring a
       ``TypedDict`` with one value for the ``total`` argument and then
       inheriting from it in another ``TypedDict`` with a different value for
       ``total``:
@@ -2848,34 +2848,34 @@ with :deco:`runtime_checkable`.
 
 .. class:: SupportsAbs
 
-    An ABC with one abstract method ``__abs__`` that is covariant
+    A protocol with one abstract method ``__abs__`` that is covariant
     in its return type.
 
 .. class:: SupportsBytes
 
-    An ABC with one abstract method ``__bytes__``.
+    A protocol with one abstract method ``__bytes__``.
 
 .. class:: SupportsComplex
 
-    An ABC with one abstract method ``__complex__``.
+    A protocol with one abstract method ``__complex__``.
 
 .. class:: SupportsFloat
 
-    An ABC with one abstract method ``__float__``.
+    A protocol with one abstract method ``__float__``.
 
 .. class:: SupportsIndex
 
-    An ABC with one abstract method ``__index__``.
+    A protocol with one abstract method ``__index__``.
 
     .. versionadded:: 3.8
 
 .. class:: SupportsInt
 
-    An ABC with one abstract method ``__int__``.
+    A protocol with one abstract method ``__int__``.
 
 .. class:: SupportsRound
 
-    An ABC with one abstract method ``__round__``
+    A protocol with one abstract method ``__round__``
     that is covariant in its return type.
 
 .. _typing-io:
@@ -3595,7 +3595,7 @@ Constant
 
 .. data:: TYPE_CHECKING
 
-   A special constant that is assumed to be ``True`` by 3rd party static
+   A special constant that is assumed to be ``True`` by static
    type checkers. It's ``False`` at runtime.
 
    A module which is expensive to import, and which only contain types