docs: rename "value restriction" to "value-constrained type variable" (#21112)

Closes #17828.

The docs used "value restriction" to describe type variables like `T:
(str, bytes)`, but the runtime attribute is `TypeVar.__constraints__`.
This PR updates the terminology across the affected doc pages to use
"value-constrained type variable" consistently, matching the runtime
naming and the term discussed in #17828.

Changes:
- `generics.rst`: rename section title, update prose, add new anchor
`value-constrained-type-variables` (old anchor
`type-variable-value-restriction` kept for backward compat)
- `more_types.rst`: update cross-reference text
- `command_line.rst`: update cross-reference text

Made with [Cursor](https://cursor.com)

Co-authored-by: Leo Ji <nuglifeleoji@gmail.com>

Author: nuglifeleoji

docs/source/command_line.rst

@@ -551,7 +551,7 @@ potentially problematic or redundant in some way.
     .. note::
 
         Mypy currently cannot detect and report unreachable or redundant code
-        inside any functions using :ref:`type-variable-value-restriction`.
+        inside any functions using :ref:`value-constrained type variables <value-constrained-type-variables>`.
 
         This limitation will be removed in future releases of mypy.
 

docs/source/generics.rst

@@ -693,10 +693,11 @@ contravariant, use type variables defined with special keyword arguments
    my_box = Box(Square())
    look_into(my_box)  # OK, but mypy would complain here for an invariant type
 
+.. _value-constrained-type-variables:
 .. _type-variable-value-restriction:
 
-Type variables with value restriction
-*************************************
+Value-constrained type variables
+*********************************
 
 By default, a type variable can be replaced with any type -- or any type that
 is a subtype of the upper bound, which defaults to ``object``. However, sometimes
@@ -727,8 +728,9 @@ The same thing is also possibly using the legacy syntax (Python 3.11 or earlier)
    def concat(x: AnyStr, y: AnyStr) -> AnyStr:
        return x + y
 
-No matter which syntax you use, such a type variable is called a type variable
-with a value restriction. Importantly, this is different from a union type,
+No matter which syntax you use, such a type variable is called a
+value-constrained type variable (the allowed types are accessible at runtime
+via ``TypeVar.__constraints__``). Importantly, this is different from a union type,
 since combinations of ``str`` and ``bytes`` are not accepted:
 
 .. code-block:: python
@@ -760,7 +762,7 @@ for the type variable, which in this case is ``str``.
 
 This is thus subtly different from using ``str | bytes`` as an upper bound,
 where the return type would be ``S`` (see :ref:`type-variable-upper-bound`).
-Using a value restriction is correct for ``concat``, since ``concat``
+Using a value constraint is correct for ``concat``, since ``concat``
 actually returns a ``str`` instance in the above example:
 
 .. code-block:: python
@@ -775,7 +777,7 @@ value of :py:func:`re.compile`, where ``S`` can be either ``str``
 or ``bytes``. Regular expressions can be based on a string or a
 bytes pattern.
 
-A type variable may not have both a value restriction and an upper bound.
+A type variable may not have both value constraints and an upper bound.
 
 Note that you may come across :py:data:`~typing.AnyStr` imported from
 :py:mod:`typing`. This feature is now deprecated, but it means the same
@@ -1330,7 +1332,7 @@ Here are examples using the legacy syntax (Python 3.11 and earlier):
     for i, j in NewVec[int]():
         ...
 
-Using type variable bounds or value restriction in generic aliases has
+Using type variable bounds or value constraints in generic aliases has
 the same effect as in generic classes and functions.
 
 

docs/source/more_types.rst

@@ -303,8 +303,8 @@ Here is the same example using the legacy syntax (Python 3.11 and earlier):
 .. note::
 
    If you just need to constrain a type variable to certain types or
-   subtypes, you can use a :ref:`value restriction
-   <type-variable-value-restriction>`.
+   subtypes, you can use a :ref:`value-constrained type variable
+   <value-constrained-type-variables>`.
 
 The default values of a function's arguments don't affect its signature -- only
 the absence or presence of a default value does. So in order to reduce