Edit doc-string, test failure cases.

Author: gcaria

pandas/core/frame.py

@@ -5614,6 +5614,12 @@ def reset_index(
         col_fill : object, default ''
             If the columns have multiple levels, determines how the other
             levels are named. If None then the index name is repeated.
+        names : str, tuple or list, default None
+            Using the given string, rename the DataFrame column which contains the index data.
+            If the DataFrame has a MultiIndex, this has to be a list or tuple with length
+            equal to the number of levels.
+
+            .. versionadded:: 1.4.0
 
         Returns
         -------
@@ -5756,6 +5762,14 @@ class    max    type
             if len(level) < self.index.nlevels:
                 new_index = self.index.droplevel(level)
 
+        if names is not None:
+            if isinstance(self.index, MultiIndex):
+                if not isinstance(names, (tuple, list)):
+                    raise ValueError("Names must be a tuple or list")
+            else:
+                if not isinstance(names, str):
+                    raise ValueError("Names must be a string")
+
         if not drop:
             to_insert: Iterable[tuple[Any, Any | None]]
             if isinstance(self.index, MultiIndex):
@@ -5764,6 +5778,14 @@ class    max    type
                         (n if n is not None else f"level_{i}")
                         for i, n in enumerate(self.index.names)
                     ]
+                else:
+
+                    if len(names) != self.index.nlevels:
+                        raise ValueError(
+                            f"The number of provided names "
+                            f"({len(names)}) does not match the number of"
+                            f" MultiIndex levels ({self.index.nlevels})"
+                        )
                 to_insert = zip(self.index.levels, self.index.codes)
             else:
                 default = "index" if "index" not in self else "level_0"

pandas/tests/frame/methods/test_reset_index.py

@@ -189,6 +189,9 @@ def test_reset_index_rename(self, float_frame):
         exp = Series(float_frame.index.values, name="new_name")
         tm.assert_series_equal(rdf["new_name"], exp)
 
+        with pytest.raises(ValueError, match="Names must be a string"):
+            float_frame.reset_index(names=1)
+
     def test_reset_index_rename_multiindex(self, float_frame):
         # GH 6878
         stacked = float_frame.stack()[::2]
@@ -205,6 +208,12 @@ def test_reset_index_rename_multiindex(self, float_frame):
             deleveled["second"], deleveled2["new_second"], check_names=False
         )
 
+        with pytest.raises(ValueError, match=r".* number of provided names .*"):
+            stacked.reset_index(names=["new_first"])
+
+        with pytest.raises(ValueError, match="Names must be a tuple or list"):
+            stacked.reset_index(names={"first": "new_first", "second": "new_second"})
+
     def test_reset_index_level(self):
         df = DataFrame([[1, 2, 3, 4], [5, 6, 7, 8]], columns=["A", "B", "C", "D"])