PEP 637: Added clause for star unpacking leaving the index as a tuple (GH-1790)

pep-0637.rst

@@ -392,22 +392,43 @@ The successful implementation of this PEP will result in the following behavior:
        obj[*items]
 
    This allows notations such as ``[:, *args, :]``, which could be treated 
-   as ``[(slice(None), *args, slice(None))]``.
+   as ``[(slice(None), *args, slice(None))]``. Multiple star unpacking are
+   allowed::
 
-   The following notation equivalence should be honored::
+       obj[1, *(2, 3), *(4, 5), 6, foo=5]
+       # Equivalent to obj[(1, 2, 3, 4, 5, 6), foo=3)
+
+   The following notation equivalence must be honored::
 
        obj[*()]        
        # Equivalent to obj[()]
        
        obj[*(), foo=3] 
-       # Equivalent to obj[foo=3]
+       # Equivalent to obj[(), foo=3]
 
        obj[*(x,)]      
-       # Equivalent to obj[x] 
+       # Equivalent to obj[(x,)]
        
        obj[*(x,),]     
-       # Equivalent to obj[x,]
+       # Equivalent to obj[(x,)]
 
+   Note in particular case 3: sequence unpacking of a single element will 
+   not behave as if only one single argument was passed. A related case is 
+   the following example::
+
+      obj[1, *(), foo=5]
+      # Equivalent to obj[(1,), foo=5]
+      # calls type(obj).__getitem__(obj, (1,), foo=5)
+
+   However, as we saw earlier, for backward compatibility a single index will be passed as is::
+
+      obj[1, foo=5]
+      # calls type(obj).__getitem__(obj, 1, foo=5)
+
+   In other words, a single positional index will be passed "as is" only if no sequence
+   unpacking is present. If a sequence unpacking is present, then the index will become a tuple,
+   regardless of the resulting number of elements in the index after the unpacking has taken place.
+ 
 8. Dict unpacking is permitted::
 
        items = {'spam': 1, 'eggs': 2}