Add deprecation and whatsnew

doc/source/whatsnew/v0.24.0.rst

@@ -1251,7 +1251,7 @@ Other API Changes
 - :class:`pandas.io.formats.style.Styler` supports a ``number-format`` property when using :meth:`~pandas.io.formats.style.Styler.to_excel` (:issue:`22015`)
 - :meth:`DataFrame.corr` and :meth:`Series.corr` now raise a ``ValueError`` along with a helpful error message instead of a ``KeyError`` when supplied with an invalid method (:issue:`22298`)
 - :meth:`shift` will now always return a copy, instead of the previous behaviour of returning self when shifting by 0 (:issue:`22397`)
-- :meth:`DataFrame.set_index` now allows all one-dimensional list-likes, raises a ``TypeError`` for incorrect types,
+- :meth:`DataFrame.set_index` now gives a better (and less frequent) KeyError, and raises a ``ValueError`` for incorrect types,
   has an improved ``KeyError`` message, and will not fail on duplicate column names with ``drop=True``. (:issue:`22484`)
 - Slicing a single row of a DataFrame with multiple ExtensionArrays of the same type now preserves the dtype, rather than coercing to object (:issue:`22784`)
 - :class:`DateOffset` attribute `_cacheable` and method `_should_cache` have been removed (:issue:`23118`)
@@ -1309,6 +1309,7 @@ Deprecations
 - In :meth:`Series.where` with Categorical data, providing an ``other`` that is not present in the categories is deprecated. Convert the categorical to a different dtype or add the ``other`` to the categories first (:issue:`24077`).
 - :meth:`Series.clip_lower`, :meth:`Series.clip_upper`, :meth:`DataFrame.clip_lower` and :meth:`DataFrame.clip_upper` are deprecated and will be removed in a future version. Use ``Series.clip(lower=threshold)``, ``Series.clip(upper=threshold)`` and the equivalent ``DataFrame`` methods (:issue:`24203`)
 - :meth:`Series.nonzero` is deprecated and will be removed in a future version (:issue:`18262`)
+- :meth:`DataFrame.set_index` has deprecated using lists of values *within* lists. It remains possible to pass array-likes, both directly and within a list.
 
 .. _whatsnew_0240.deprecations.datetimelike_int_ops:
 

pandas/core/frame.py

@@ -4139,20 +4139,27 @@ def set_index(self, keys, drop=True, append=False, inplace=False,
             raise ValueError(err_msg)
 
         missing = []
+        depr_warn = False
         for col in keys:
             if (is_scalar(col) or isinstance(col, tuple)) and col in self:
                 # if col is a valid column key, everything is fine
                 continue
             elif is_scalar(col) and col not in self:
-                # tuples that are not keys will be are excluded here;
-                # will be considered list-like, not missing
+                # tuples that are not keys are not considered missing,
+                # but as an illegal list-like
                 missing.append(col)
+            elif isinstance(col, list):
+                depr_warn = True
             elif (not isinstance(col, (ABCIndexClass, ABCSeries, np.ndarray))
                   or getattr(col, 'ndim', 1) > 1):
                 raise ValueError(err_msg)
 
         if missing:
             raise KeyError('{}'.format(missing))
+        if depr_warn:
+            msg = ('passing lists within a list to the parameter "keys" is '
+                   'deprecated and will be removed in a future version.')
+            warnings.warn(msg, FutureWarning, stacklevel=2)
 
         if inplace:
             frame = self

pandas/tests/frame/test_alter_axes.py

@@ -143,7 +143,7 @@ def test_set_index_pass_single_array(self, frame_of_index_cols,
 
     # MultiIndex constructor does not work directly on Series -> lambda
     # also test index name if append=True (name is duplicate here for A & B)
-    @pytest.mark.parametrize('box', [Series, Index, np.array,
+    @pytest.mark.parametrize('box', [Series, Index, np.array, list,
                                      lambda x: MultiIndex.from_arrays([x])])
     @pytest.mark.parametrize('append, index_name',
                              [(True, None), (True, 'A'), (True, 'B'),
@@ -156,9 +156,13 @@ def test_set_index_pass_arrays(self, frame_of_index_cols,
 
         keys = ['A', box(df['B'])]
         # np.array "forgets" the name of B
-        names = ['A', None if box in [np.array] else 'B']
+        names = ['A', None if box in [list, np.array] else 'B']
 
-        result = df.set_index(keys, drop=drop, append=append)
+        if box == list:
+            with tm.assert_produces_warning(FutureWarning):
+                result = df.set_index(keys, drop=drop, append=append)
+        else:
+            result = df.set_index(keys, drop=drop, append=append)
 
         # only valid column keys are dropped
         # since B is always passed as array above, only A is dropped, if at all
@@ -171,10 +175,10 @@ def test_set_index_pass_arrays(self, frame_of_index_cols,
     # MultiIndex constructor does not work directly on Series -> lambda
     # We also emulate a "constructor" for the label -> lambda
     # also test index name if append=True (name is duplicate here for A)
-    @pytest.mark.parametrize('box2', [Series, Index, np.array,
+    @pytest.mark.parametrize('box2', [Series, Index, np.array, list,
                                       lambda x: MultiIndex.from_arrays([x]),
                                       lambda x: x.name])
-    @pytest.mark.parametrize('box1', [Series, Index, np.array,
+    @pytest.mark.parametrize('box1', [Series, Index, np.array, list,
                                       lambda x: MultiIndex.from_arrays([x]),
                                       lambda x: x.name])
     @pytest.mark.parametrize('append, index_name', [(True, None),
@@ -186,17 +190,31 @@ def test_set_index_pass_arrays_duplicate(self, frame_of_index_cols, drop,
         df.index.name = index_name
 
         keys = [box1(df['A']), box2(df['A'])]
-        result = df.set_index(keys, drop=drop, append=append)
+
+        if box1 == list or box2 == list:
+            with tm.assert_produces_warning(FutureWarning):
+                result = df.set_index(keys, drop=drop, append=append)
+        else:
+            result = df.set_index(keys, drop=drop, append=append)
 
         # need to adapt first drop for case that both keys are 'A' --
         # cannot drop the same column twice;
         # use "is" because == would give ambiguous Boolean error for containers
         first_drop = False if (keys[0] is 'A' and keys[1] is 'A') else drop
 
         # to test against already-tested behaviour, we add sequentially,
-        # hence second append always True
-        expected = df.set_index(keys[0], drop=first_drop, append=append)
-        expected = expected.set_index(keys[1], drop=drop, append=True)
+        # hence second append always True; must wrap keys in list, otherwise
+        # box = list would be interpreted as keys
+        if box1 == list or box2 == list:
+            with tm.assert_produces_warning(FutureWarning):
+                expected = df.set_index([keys[0]], drop=first_drop,
+                                        append=append)
+                expected = expected.set_index([keys[1]], drop=drop,
+                                              append=True)
+        else:
+            expected = df.set_index([keys[0]], drop=first_drop, append=append)
+            expected = expected.set_index([keys[1]], drop=drop, append=True)
+
         tm.assert_frame_equal(result, expected)
 
     @pytest.mark.parametrize('append', [True, False])