PEP 646: fix nits and typos.

Author: pradeep90

Diff for: pep-0646.rst

@@ -151,15 +151,16 @@ In order to support the above use cases, we introduce
 but for a *tuple* of types.
 
 In addition, we introduce a new use for the star operator: to 'unpack'
-``TypeVarTuple`` instances and tuple types. Unpacking a
-``TypeVarTuple`` or tuple type is the typing equivalent of unpacking a
-variable or a tuple of values.
+``TypeVarTuple`` instances and tuple types such as ``Tuple[int,
+str]``. Unpacking a ``TypeVarTuple`` or tuple type is the typing
+equivalent of unpacking a variable or a tuple of values.
 
 Type Variable Tuples
 --------------------
 
-In the same way that a normal type variable is a stand-in for a single type,
-a type variable *tuple* is a stand-in for a *tuple* type.
+In the same way that a normal type variable is a stand-in for a single
+type such as ``int``, a type variable *tuple* is a stand-in for a *tuple* type such as
+``Tuple[int, str]``.
 
 Type variable tuples are created with:
 
@@ -315,13 +316,6 @@ As of this PEP, only a single type variable tuple may appear in a type parameter
 
     class Array(Generic[*Ts1, *Ts2]): ...  # Error
 
-Only one unpacking may appear in a tuple:
-
-::
-
-    x: Tuple[int, *Ts, str, *Ts2]  # Error
-    y: Tuple[int, *Tuple[int, ...], str, *Tuple[str, ...]]  # Error
-
 Type Concatenation
 ------------------
 
@@ -364,68 +358,33 @@ Normal ``TypeVar`` instances can also be prefixed and/or suffixed:
 Unpacking a Tuple Type
 ----------------------
 
-We mentioned that a ``TypeVarTuple`` simply stands for a tuple of
-types. Thus, we can cleanly replace any use of a ``TypeVarTuple`` in a
-function signature with a tuple type.
+We mentioned that a ``TypeVarTuple`` stands for a tuple of types.
+Since we can unpack an ``TypeVarTuple``, for consistency, we also
+allow unpacking a tuple type. As we shall see, this also enables a
+number of interesting features.
+
 
 Unpacking a Concrete Tuple Type
 '''''''''''''''''''''''''''''''
 
 Unpacking a concrete tuple type is analogous to unpacking a tuple of
 values at runtime. ``Tuple[int, *Tuple[bool, bool], str]`` is
-equivalent to ``Tuple[int, bool, bool, str]``. While this is unlikely
-to be useful by itself, we mention it to cleanly specify how we unpack
-a ``TypeVarTuple`` that is substituted by a concrete tuple type:
-
-::
-
-    def strip_and_add_float(x: Tuple[int, *Ts, str]) -> Tuple[float, *Ts, float]: ...
-
-When ``strip_and_add_float`` is called with a value that has a concrete
-tuple type, say, ``Tuple[int, bool, bool, str]``, ``Ts`` is bound to
-the concrete tuple ``Tuple[bool, bool]``.
-
-::
-
-    x: Tuple[int, bool, bool, str] = (1, True, False, "hello")
-
-    y = strip_and_add_float(x)
-    # Inferred type of y: Tuple[float, bool, bool, float]
-
-The inferred type is ``Tuple[float, bool, bool, float]`` because
-unpacking ``Tuple[bool, bool]`` in the return type ``Tuple[float, *Ts,
-float]`` gives back ``Tuple[float, bool, bool, float]``.
+equivalent to ``Tuple[int, bool, bool, str]``.
 
 Unpacking an Unbounded Tuple Type
 '''''''''''''''''''''''''''''''''
 
 Unpacking an unbounded tuple preserves the unbounded tuple as it is.
-``Tuple[int, *Tuple[str, ...], str]`` signifies a tuple
-type where the first element is guaranteed to be of type ``int``, the
-last element is guaranteed to be of type ``str``, and there may be
-zero or more elements of type ``str`` in between. Note that
-``Tuple[*Tuple[int, ...]]`` is equivalent to ``Tuple[int, ...]``.
-
-Consider the following functions:
-
-::
-
-    def add_first_last(x: Tuple[*Ts]) -> Tuple[int, *Ts, str]: ...
-
-When ``add_first_last`` is called with a value that has an *unbounded*
-tuple type, say, ``Tuple[str, ...]``, ``Ts`` is bound to the concrete
-tuple ``Tuple[str, ...]`` and substituted in the return type.
-
-::
-
-    x: Tuple[str, ...]
-
-    y = add_first_last(x)
-    # Inferred type of y: Tuple[int, *Tuple[str, ...], str]
-
-
-Unpacking unbounded tuples is useful in function signatures where we
-don't care about the exact elements and do not want to define an
+That is, ``*Tuple[int, ...]`` remains ``*Tuple[int, ...]``; there's no
+simpler form. This enables us to specify types such as ``Tuple[int,
+*Tuple[str, ...], str]`` - a tuple type where the first element is
+guaranteed to be of type ``int``, the last element is guaranteed to be
+of type ``str``, and the elements in the middle are zero or more
+elements of type ``str``. Note that ``Tuple[*Tuple[int, ...]]`` is
+equivalent to ``Tuple[int, ...]``.
+
+Unpacking unbounded tuples is also useful in function signatures where
+we don't care about the exact elements and don't want to define an
 unnecessary ``TypeVarTuple``:
 
 ::
@@ -444,25 +403,26 @@ unnecessary ``TypeVarTuple``:
     process_batch_channels(z)  # Error: Expected Channels.
 
 
-We can also pass a ``Tuple[int, ...]`` wherever a ``Tuple[*Ts]`` is
+We can also pass a ``*Tuple[int, ...]`` wherever a ``*Ts`` is
 expected. This is useful when we have particularly dynamic code and
-cannot infer the precise number of dimensions or the precise types for
+cannot state the precise number of dimensions or the precise types for
 each of the dimensions. In those cases, we can smoothly fall back to
 an unbounded tuple:
 
 ::
 
+    y: Array[*Tuple[Any, ...]] = read_from_file()
+
     def expect_variadic_array(
         x: Array[Batch, *Shape]
     ) -> None: ...
 
+    expect_variadic_array(y)  # OK
+
     def expect_precise_array(
         x: Array[Batch, Height, Width, Channels]
     ) -> None: ...
 
-    y: Array[*Tuple[Any, ...]] = read_from_file()
-
-    expect_variadic_array(y)  # OK
     expect_precise_array(y)  # OK
 
 ``Array[*Tuple[Any, ...]]`` stands for an array with an arbitrary
@@ -473,10 +433,21 @@ is bound to ``Tuple[Any, ...]``. In the call to
 ``Width``, and ``Channels`` are all bound to ``Any``.
 
 This allows users to handle dynamic code gracefully while still
-explicitly marking the code as unsafe (by using ``*Tuple[Any, ...]``).
-Otherwise, users would face noisy errors from the type checker every
-time they tried to use the variable ``y``, which would hinder them
-when migrating a legacy code base to use ``TypeVarTuple``.
+explicitly marking the code as unsafe (by using ``y: Array[*Tuple[Any,
+...]]``).  Otherwise, users would face noisy errors from the type
+checker every time they tried to use the variable ``y``, which would
+hinder them when migrating a legacy code base to use ``TypeVarTuple``.
+
+Multiple Unpackings in a Tuple: Not Allowed
+''''''''''''''''''''''''''''''''''''''''''
+
+As with ``TypeVarTuple``, only one unpacking may appear in a tuple:
+
+::
+
+    x: Tuple[int, *Ts, str, *Ts2]  # Error
+    y: Tuple[int, *Tuple[int, ...], str, *Tuple[str, ...]]  # Error
+
 
 ``*args`` as a Type Variable Tuple
 ----------------------------------
@@ -508,18 +479,19 @@ or suffixes of the variadic argument list. For example:
 ::
 
     # os.execle takes arguments 'path, arg0, arg1, ..., env'
-    def execle(path: str, *args: *Tuple[*Ts, Mapping[str, str]]) -> None: ...
+    def execle(path: str, *args: *Tuple[*Ts, Env]) -> None: ...
 
 Note this this is different to
 
 ::
 
-    def execle(path: str, *args: *Ts, env: Mapping[str, str]) -> None: ...
+    def execle(path: str, *args: *Ts, env: Env) -> None: ...
 
 as this would make ``env`` a keyword-only argument.
 
-Unpacking an unbounded tuple is equivalent to the PEP 484 behavior of
-``*args: int``, which accepts zero or more values of type ``int``:
+Using an unpacked unbounded tuple is equivalent to the PEP 484
+behavior [#pep-484-args]_ of ``*args: int``, which accepts zero or
+more values of type ``int``:
 
 ::
 
@@ -587,10 +559,10 @@ Type variable tuples can also be used in the arguments section of a
       def __init__(
         self,
         target: Callable[[*Ts], None],
-        args: Tuple[*Ts]
-      ): ...
+        args: Tuple[*Ts],
+      ) -> None: ...
 
-    def func(arg1: int, arg2: str): ...
+    def func(arg1: int, arg2: str) -> None: ...
 
     Process(target=func, args=(0, 'foo'))  # Valid
     Process(target=func, args=('foo', 0))  # Error
@@ -621,7 +593,7 @@ the function:
     def foo(*args: *Tuple[int, *Ts, T]) -> Tuple[T, *Ts]: ...
 
 Behaviour when Type Parameters are not Specified
-''''''''''''''''''''''''''''''''''''''''''''''''
+------------------------------------------------
 
 When a generic class parameterised by a type variable tuple is used without
 any type parameters, it behaves as if the type variable tuple was
@@ -729,7 +701,7 @@ Normal ``TypeVar`` instances can also be used in such aliases:
     Foo[str, int]
     # T bound to float, Ts to Tuple[()]
     Foo[float]
-    # T bound to Any, Ts to an arbitrary number of Any
+    # T bound to Any, Ts to an Tuple[Any, ...]
     Foo
 
 Overloads for Accessing Individual Types
@@ -1470,6 +1442,8 @@ References
 
 .. [#dan-endorsement] https://mail.python.org/archives/list/python-dev@python.org/message/HTCARTYYCHETAMHB6OVRNR5EW5T2CP4J/
 
+.. [#pep-484-args] https://www.python.org/dev/peps/pep-0484/#arbitrary-argument-lists-and-default-argument-values
+
 Copyright
 =========