Incorporated code review feedback

Author: erictraut

docs/spec/dataclasses.rst

@@ -146,15 +146,19 @@ customization of default behaviors:
 
 .. code-block:: python
 
-  def dataclass_transform[T](
+  class _IdentityCallable(Protocol):
+      def __call__[T](self, arg: T, /) -> T:
+          ...
+
+  def dataclass_transform(
       *,
       eq_default: bool = True,
       order_default: bool = False,
       kw_only_default: bool = False,
       frozen_default: bool = False,
       field_specifiers: tuple[type | Callable[..., Any], ...] = (),
       **kwargs: Any,
-  ) -> Callable[[T], T]: ...
+  ) -> _IdentityCallable: ...
 
 * ``eq_default`` indicates whether the ``eq`` parameter is assumed to
   be True or False if it is omitted by the caller. If not specified,

docs/spec/generics.rst

@@ -210,15 +210,22 @@ defined class is generic if you subclass one or more other generic classes and
 specify type variables for their parameters. See :ref:`generic-base-classes`
 for details.
 
-You can use multiple inheritance with generic classes::
+You can use multiple inheritance with ``Generic``::
 
-  from collections.abc import Container, Iterable, Sized
+  from typing import TypeVar, Generic
+  from collections.abc import Sized, Iterable, Container
+
+  T = TypeVar('T')
 
-  class LinkedList[T](Sized):
+  class LinkedList(Sized, Generic[T]):
       ...
 
-  class MyMapping[K, V](Iterable[tuple[K, V]],
-                        Container[tuple[K, V]]):
+  K = TypeVar('K')
+  V = TypeVar('V')
+
+  class MyMapping(Iterable[tuple[K, V]],
+                  Container[tuple[K, V]],
+                  Generic[K, V]):
       ...
 
 Subclassing a generic class without specifying type parameters assumes
@@ -240,7 +247,7 @@ Scoping rules for type variables
 
 When using the generic class syntax introduced in Python 3.12, the location of
 its declaration defines its scope. When using the older syntax, the scoping
-rules are more subtle and complex.
+rules are more subtle and complex:
 
 * A type variable used in a generic function could be inferred to represent
   different types in the same code block. Example::
@@ -662,7 +669,7 @@ inline by prefixing its name with ``**`` inside a generic parameter list
    class CallbackWrapper[T, **P]:
        callback: Callable[P, T]
 
-Prior to 3.12, the ``ParamSpec`` constructor can be used::
+Prior to 3.12, the ``ParamSpec`` constructor can be used.
 
 .. code-block::
 
@@ -699,8 +706,8 @@ parameter specification variable (``Callable[Concatenate[int, P], int]``\ ).
                    "]"
 
 where ``parameter_specification_variable`` is introduced either inline (using
-``**``) or via ``typing.ParamSpec`` as shown above, and ``concatenate`` is
-``typing.Concatenate``.
+``**`` in a type parameter list) or via ``typing.ParamSpec`` as shown above,
+and ``concatenate`` is ``typing.Concatenate``.
 
 As before, ``parameters_expression``\ s by themselves are not acceptable in
 places where a type is expected
@@ -1086,7 +1093,7 @@ type such as ``int``, a type variable *tuple* is a stand-in for a *tuple* type s
 ``tuple[int, str]``.
 
 In Python 3.12 and newer, type variable tuples can be introduced inline by prefixing
-their name with ``*`` inside a generic parameter list.
+their name with ``*`` inside a type parameter list.
 
 ::
 

docs/spec/overload.rst

@@ -48,7 +48,8 @@ arguments depending on the type of the callable::
   @overload
   def map[T1, T2, S](
       func: Callable[[T1, T2], S],
-      iter1: Iterable[T1], iter2: Iterable[T2],
+      iter1: Iterable[T1],
+      iter2: Iterable[T2],
   ) -> Iterator[S]: ...
   # ... and we could add more items to support more than two iterables
 
@@ -91,7 +92,7 @@ A constrained ``TypeVar`` type can sometimes be used instead of
 using the ``@overload`` decorator. For example, the definitions
 of ``concat1`` and ``concat2`` in this stub file are equivalent::
 
-  def concat1[AnyStr: (str, bytes)](x: AnyStr, y: AnyStr) -> AnyStr: ...
+  def concat1[S: (str, bytes)](x: S, y: S) -> S: ...
 
   @overload
   def concat2(x: str, y: str) -> str: ...
@@ -103,13 +104,13 @@ be represented precisely using type variables. We
 recommend that ``@overload`` is only used in cases where a type
 variable is not sufficient.
 
-Another important difference between type variables such as ``AnyStr``
-and using ``@overload`` is that the prior can also be used to define
-constraints for generic class type parameters. For example, the type
-parameter of the generic class ``typing.IO`` is constrained (only
-``IO[str]``, ``IO[bytes]`` and ``IO[Any]`` are valid)::
+Another important difference between type variables and an ``@overload``
+is that the former can also be used to define constraints for generic
+class type parameters. For example, the type parameter of the generic
+class ``typing.IO`` is constrained (only ``IO[str]``, ``IO[bytes]``
+and ``IO[Any]`` are valid)::
 
-  class IO[AnyStr: (str, bytes)]: ...
+  class IO[S: (str, bytes)]: ...
 
 
 Invalid overload definitions

docs/spec/protocol.rst

@@ -271,11 +271,12 @@ non-protocol generic types::
       def __iter__(self) -> Iterator[T]:
           ...
 
-The older syntax ``Protocol[T, S, ...]`` remains available as a shorthand for
-``Protocol, Generic[T, S, ...]``. It is an error to combine the shorthand with
-``Generic[T, S, ...]`` or to mix it with the new ``class Iterable[T]`` form::
+The older (pre-3.12) syntax ``Protocol[T, S, ...]`` remains available as a
+shorthand for ``Protocol, Generic[T, S, ...]``. It is an error to combine the
+shorthand with ``Generic[T, S, ...]`` or to mix it with the new
+``class Iterable[T]`` form::
 
-  class Iterable[T](Protocol, Generic[T]):   # INVALID
+  class Iterable(Protocol[T], Generic[T]):   # INVALID
       ...
 
   class Iterable[T](Protocol[T]):   # INVALID