Some Alex comments

JelleZijlstra · May 26, 2023 · May 13, 2023 · May 15, 2023 · May 19, 2023 · May 19, 2023
commit 0d37675705e0e6a2e32a94131d49f18777016eac
@@ -1377,16 +1377,10 @@ without the dedicated syntax, as documented below.
 
    Type variable.
 
-   Usage::
-
-      T = TypeVar('T')  # Can be anything
-      S = TypeVar('S', bound=str)  # Can be any subtype of str
-      A = TypeVar('A', str, bytes)  # Must be exactly str or bytes
-
-   The syntax for :ref:`generic functions <generic-functions>`,
+   The preferred way to construct a type variable is via the dedicated syntax
+   for :ref:`generic functions <generic-functions>`,
    :ref:`generic classes <generic-classes>`, and
-   :ref:`generic type aliases <generic-type-aliases>` can be used to
-   create type variables::
+   :ref:`generic type aliases <generic-type-aliases>`::
 
       class Sequence[T]:  # T is a TypeVar
           ...
@@ -1401,9 +1395,16 @@ without the dedicated syntax, as documented below.
       class StrOrBytesSequence[A: (str, bytes)]:  # A is a TypeVar constrained to str or bytes
           ...
 
+   However, if desired, reusable type variables can also be constructed manually, like so::
+
+      T = TypeVar('T')  # Can be anything
+      S = TypeVar('S', bound=str)  # Can be any subtype of str
+      A = TypeVar('A', str, bytes)  # Must be exactly str or bytes
+
    Type variables exist primarily for the benefit of static type
    checkers.  They serve as the parameters for generic types as well
-   as for generic function definitions.  See :class:`Generic` for more
+   as for generic function and type alias definitions.
+   See :class:`Generic` for more
    information on generic types.  Generic functions work as follows::
 
       def repeat[T](x: T, n: int) -> Sequence[T]:
@@ -1428,8 +1429,9 @@ without the dedicated syntax, as documented below.
    through the :ref:`type parameter syntax <type-params>` and when
    ``infer_variance=True`` is passed.
    Manually created type variables may be explicitly marked covariant or contravariant by passing
-   ``covariant=True`` or ``contravariant=True``.  See :pep:`484` and :pep:`695` for more
-   details.  By default, type variables are invariant.
+   ``covariant=True`` or ``contravariant=True``.
+   By default, manually created type variables are invariant.
+   See :pep:`484` and :pep:`695` for more details.
 
    Bound type variables and constrained type variables have different
    semantics in several important ways. Using a *bound* type variable means
@@ -1449,13 +1451,13 @@ without the dedicated syntax, as documented below.
    Type variables can be bound to concrete types, abstract types (ABCs or
    protocols), and even unions of types::
 
-      U = TypeVar('U', bound=str|bytes)  # Can be any subtype of the union str|bytes
-      V = TypeVar('V', bound=SupportsAbs)  # Can be anything with an __abs__ method
-
       # Can be anything with an __abs__ method
-      def print_abs[V: SupportsAbs](arg: V) -> None:
+      def print_abs[T: SupportsAbs](arg: T) -> None:
           print("Absolute value:", abs(arg))
 
+      U = TypeVar('U', bound=str|bytes)  # Can be any subtype of the union str|bytes
+      V = TypeVar('V', bound=SupportsAbs)  # Can be anything with an __abs__ method
+
    .. _typing-constrained-typevar:
 
    Using a *constrained* type variable, however, means that the ``TypeVar``
@@ -1469,20 +1471,19 @@ without the dedicated syntax, as documented below.
 
       c = concatenate('one', b'two')  # error: type variable 'A' can be either str or bytes in a function call, but not both
 
-   At runtime, ``isinstance(x, T)`` will raise :exc:`TypeError`.  In general,
-   :func:`isinstance` and :func:`issubclass` should not be used with types.
+   At runtime, ``isinstance(x, T)`` will raise :exc:`TypeError`.
 
    .. attribute:: __name__
 
       The name of the type variable.
 
    .. attribute:: __covariant__
 
-      Whether the type variable is covariant.
+      Whether the type var has been explicitly marked as covariant.
 
    .. attribute:: __contravariant__
 
-      Whether the type variable is contravariant.
+      Whether the type var has been explicitly marked as contravariant.
 
    .. attribute:: __infer_variance__
 

@@ -443,42 +443,42 @@ static PyMethodDef typevar_methods[] = {
 PyDoc_STRVAR(typevar_doc,
 "Type variable.\n\
 \n\
-Usage::\n\
+The preferred way to construct a type variable is via the dedicated syntax\n\
+for :ref:`generic functions <generic-functions>`,\n\
+:ref:`generic classes <generic-classes>`, and\n\
+:ref:`generic type aliases <generic-type-aliases>`::\n\
 \n\
-  T = TypeVar('T')  # Can be anything\n\
-  S = TypeVar('S', bound=str)  # Can be any subtype of str\n\
-  A = TypeVar('A', str, bytes)  # Must be str or bytes\n\
+   class Sequence[T]:  # T is a TypeVar\n\
+         ...\n\
 \n\
-The syntax for generic functions, classes, and type aliases can\n\
-be used to create type variables::\n\
+This syntax can also be used to create bound and constrained type\n\
+variables::\n\
 \n\
-  class Sequence[T]:  # T is a TypeVar\n\
-    ...\n\
+   class StrSequence[S: str]:  # S is a TypeVar bound to str\n\
+         ...\n\
 \n\
-Type variables exist primarily for the benefit of static type\n\
-checkers.  They serve as the parameters for generic types as well\n\
-as for generic function definitions.  See class Generic for more\n\
-information on generic types.  Generic functions work as follows:\n\
 \n\
-\n\
-\n\
-  def repeat[T](x: T, n: int) -> Sequence[T]:\n\
-      '''Return a list containing n references to x.'''\n\
-      return [x]*n\n\
+   class StrOrBytesSequence[A: (str, bytes)]:  # A is a TypeVar constrained to str or bytes\n\
+         ...\n\
 \n\
-  def print_capitalized[S: str](x: S) -> S:\n\
-      '''Print x capitalized, and return x.'''\n\
-      print(x.capitalize())\n\
-      return x\n\
+However, if desired, reusable type variables can also be constructed\n\
+manually, like so::\n\
 \n\
-  def concatenate[A: (str, bytes)](x: A, y: A) -> A:\n\
-      '''Add two strings or bytes objects together.'''\n\
-      return x + y\n\
+   T = TypeVar('T')  # Can be anything\n\
+   S = TypeVar('S', bound=str)  # Can be any subtype of str\n\
+   A = TypeVar('A', str, bytes)  # Must be exactly str or bytes\n\
+\n\
+Type variables exist primarily for the benefit of static type\n\
+checkers.  They serve as the parameters for generic types as well\n\
+as for generic function and type alias definitions.\n\
 \n\
 The variance of type variables is inferred by type checkers when they are created\n\
 through the type parameter syntax and when\n\
 ``infer_variance=True`` is passed.\n\
-Manually created type variables may be explicitly marked covariant or contravariant by passing\n\
-``covariant=True`` or ``contravariant=True``.  See PEP 484 and PEP 695 for more\n\
-details.  By default, type variables are invariant.\n\
+Manually created type variables may be explicitly marked covariant or\n\
+contravariant by passing ``covariant=True`` or ``contravariant=True``.\n\
+By default, manually created type variables are invariant. See PEP 484\n\
+and PEP 695 for more details.\n\
 ");
 
 static PyType_Slot typevar_slots[] = {