Updated the typing spec to use modern (PEP 695) generics syntax (#2089)

* Updated the typing spec to use modern (PEP 695) generics syntax

* Update docs/spec/generics.rst

Co-authored-by: Shantanu <[email protected]>

* Update docs/spec/annotations.rst

Co-authored-by: Alex Waygood <[email protected]>

* Update docs/spec/annotations.rst

Co-authored-by: Alex Waygood <[email protected]>

* Incorporated code review feedback

* Incorporated Jelle's review feedback

* Addressed code review feedback from Jelle

---------

Co-authored-by: Shantanu <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>

Author: 3 people

docs/spec/aliases.rst

@@ -34,29 +34,24 @@ Type aliases may be as complex as type hints in annotations --
 anything that is acceptable as a type hint is acceptable in a type
 alias::
 
-    from typing import TypeVar
     from collections.abc import Iterable
 
-    T = TypeVar('T', bound=float)
-    Vector = Iterable[tuple[T, T]]
+    type Vector[T: float] = Iterable[tuple[T, T]]
 
-    def inproduct(v: Vector[T]) -> T:
+    def inproduct[T: float](v: Vector[T]) -> T:
         return sum(x*y for x, y in v)
-    def dilate(v: Vector[T], scale: T) -> Vector[T]:
+    def dilate[T: float](v: Vector[T], scale: T) -> Vector[T]:
         return ((x * scale, y * scale) for x, y in v)
     vec: Vector[float] = []
 
 
 This is equivalent to::
 
-    from typing import TypeVar
     from collections.abc import Iterable
 
-    T = TypeVar('T', bound=float)
-
-    def inproduct(v: Iterable[tuple[T, T]]) -> T:
+    def inproduct[T: float](v: Iterable[tuple[T, T]]) -> T:
         return sum(x*y for x, y in v)
-    def dilate(v: Iterable[tuple[T, T]], scale: T) -> Iterable[tuple[T, T]]:
+    def dilate[T: float](v: Iterable[tuple[T, T]], scale: T) -> Iterable[tuple[T, T]]:
         return ((x * scale, y * scale) for x, y in v)
     vec: Iterable[tuple[float, float]] = []
 

docs/spec/annotations.rst

@@ -366,9 +366,8 @@ In addition, the first argument in an instance method can be annotated
 with a type variable. In this case the return type may use the same
 type variable, thus making that method a generic function. For example::
 
-  T = TypeVar('T', bound='Copyable')
   class Copyable:
-      def copy(self: T) -> T:
+      def copy[T: Copyable](self: T) -> T:
           # return a copy of self
 
   class C(Copyable): ...
@@ -378,10 +377,9 @@ type variable, thus making that method a generic function. For example::
 The same applies to class methods using ``type[]`` in an annotation
 of the first argument::
 
-  T = TypeVar('T', bound='C')
   class C:
       @classmethod
-      def factory(cls: type[T]) -> T:
+      def factory[T: C](cls: type[T]) -> T:
           # make a new instance of cls
 
   class D(C): ...

docs/spec/class-compat.rst

@@ -101,11 +101,8 @@ For example, annotating the discussed class::
 As a matter of convenience (and convention), instance variables can be
 annotated in ``__init__`` or other methods, rather than in the class::
 
-  from typing import Generic, TypeVar
-  T = TypeVar('T')
-
-  class Box(Generic[T]):
-      def __init__(self, content):
+  class Box[T]:
+      def __init__(self, content: T):
           self.content: T = content
 
 ``ClassVar`` cannot be used as a qualifier for a :ref:`TypedDict <typeddict>`

docs/spec/constructors.rst

@@ -318,16 +318,14 @@ these method evaluations, they should take on their default values.
 
   ::
 
-    T1 = TypeVar("T1")
-    T2 = TypeVar("T2")
-    T3 = TypeVar("T3", default=str)
+    from typing import Any, Self, assert_type
 
-    class MyClass1(Generic[T1, T2]):
+    class MyClass1[T1, T2]:
         def __new__(cls, x: T1) -> Self: ...
 
     assert_type(MyClass1(1), MyClass1[int, Any])
 
-    class MyClass2(Generic[T1, T3]):
+    class MyClass2[T1, T3 = str]:
         def __new__(cls, x: T1) -> Self: ...
 
     assert_type(MyClass2(1), MyClass2[int, str])

docs/spec/dataclasses.rst

@@ -72,12 +72,10 @@ Decorator function example
 
 .. code-block:: python
 
-  _T = TypeVar("_T")
-
   # The ``create_model`` decorator is defined by a library.
   # This could be in a type stub or inline.
   @typing.dataclass_transform()
-  def create_model(cls: Type[_T]) -> Type[_T]:
+  def create_model[T](cls: type[T]) -> type[T]:
       cls.__init__ = ...
       cls.__eq__ = ...
       cls.__ne__ = ...
@@ -148,7 +146,9 @@ customization of default behaviors:
 
 .. code-block:: python
 
-  _T = TypeVar("_T")
+  class _IdentityCallable(Protocol):
+      def __call__[T](self, arg: T, /) -> T:
+          ...
 
   def dataclass_transform(
       *,
@@ -158,7 +158,7 @@ customization of default behaviors:
       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,