BUG: raise when wrong level name is passed to "unstack"

closes pandas-dev#18303

Author: toobaz

doc/source/whatsnew/v0.25.1.rst

@@ -128,7 +128,7 @@ Groupby/resample/rolling
 Reshaping
 ^^^^^^^^^
 
--
+- A ``KeyError`` is now raised if ``.unstack()`` is called on a flat :class:`Index` passing a name which is not the correct one (:issue:`18303`)
 -
 -
 

pandas/core/indexes/base.py

@@ -1524,7 +1524,9 @@ def _validate_index_level(self, level):
                     "Too many levels:" " Index has only 1 level, not %d" % (level + 1)
                 )
         elif level != self.name:
-            raise KeyError("Level %s must be same as name (%s)" % (level, self.name))
+            raise KeyError(
+                'Level ("%s") is different from index name ("%s")' % (level, self.name)
+            )
 
     def _get_level_number(self, level):
         self._validate_index_level(level)

pandas/core/reshape/reshape.py

@@ -12,6 +12,7 @@
     ensure_platform_int,
     is_bool_dtype,
     is_extension_array_dtype,
+    is_integer,
     is_integer_dtype,
     is_list_like,
     is_object_dtype,
@@ -402,6 +403,10 @@ def unstack(obj, level, fill_value=None):
         else:
             level = level[0]
 
+    # Prioritize integer interpretation (GH #21677):
+    if not is_integer(level) and not level == "__placeholder__":
+        level = obj.index._get_level_number(level)
+
     if isinstance(obj, DataFrame):
         if isinstance(obj.index, MultiIndex):
             return _unstack_frame(obj, level, fill_value=fill_value)

pandas/tests/test_multilevel.py

@@ -524,6 +524,22 @@ def test_stack_unstack_preserve_names(self):
         restacked = unstacked.stack()
         assert restacked.index.names == self.frame.index.names
 
+    @pytest.mark.parametrize("method", ["stack", "unstack"])
+    def test_stack_unstack_wrong_level_name(self, method):
+        # GH 18303 - wrong level name should raise
+
+        # A DataFrame with flat axes:
+        df = self.frame.loc["foo"]
+
+        with pytest.raises(KeyError, match="is different from index name"):
+            getattr(df, method)("mistake")
+
+        if method == "unstack":
+            # Same on a Series:
+            s = df.iloc[:, 0]
+            with pytest.raises(KeyError, match="is different from index name"):
+                getattr(s, method)("mistake")
+
     def test_unstack_level_name(self):
         result = self.frame.unstack("second")
         expected = self.frame.unstack(level=1)