DOC: Add whatsnew entry for MultiIndex.insert_level

cloudboat · cloudboat · commit 77f3af87b307 · 2025-10-14T21:26:21.000+08:00
diff --git a/doc/source/whatsnew/v3.0.0.rst b/doc/source/whatsnew/v3.0.0.rst
@@ -214,6 +214,7 @@ Other enhancements
 - :meth:`pandas.concat` will raise a ``ValueError`` when ``ignore_index=True`` and ``keys`` is not ``None`` (:issue:`59274`)
 - :py:class:`frozenset` elements in pandas objects are now natively printed (:issue:`60690`)
 - Add ``"delete_rows"`` option to ``if_exists`` argument in :meth:`DataFrame.to_sql` deleting all records of the table before inserting data (:issue:`37210`).
+- Added :meth:`MultiIndex.insert_level` to insert new levels at specified positions in a MultiIndex (:issue:`62558`)
 - Added half-year offset classes :class:`HalfYearBegin`, :class:`HalfYearEnd`, :class:`BHalfYearBegin` and :class:`BHalfYearEnd` (:issue:`60928`)
 - Added support for ``axis=1`` with ``dict`` or :class:`Series` arguments into :meth:`DataFrame.fillna` (:issue:`4514`)
 - Added support to read and write from and to Apache Iceberg tables with the new :func:`read_iceberg` and :meth:`DataFrame.to_iceberg` functions (:issue:`61383`)
@@ -228,7 +229,7 @@ Other enhancements
 - Support reading Stata 102-format (Stata 1) dta files (:issue:`58978`)
 - Support reading Stata 110-format (Stata 7) dta files (:issue:`47176`)
 - Switched wheel upload to **PyPI Trusted Publishing** (OIDC) for release-tag pushes in ``wheels.yml``. (:issue:`61718`)
--
+
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_300.notable_bug_fixes:
diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py
@@ -2775,7 +2775,6 @@ def insert_level(self, position: int, value, name=None) -> MultiIndex:
 
         new_names.insert(position, name)
 
-
         return MultiIndex.from_tuples(new_tuples, names=new_names)
 
     def _reorder_ilevels(self, order) -> MultiIndex:
diff --git a/pandas/tests/frame/test_query_eval.py b/pandas/tests/frame/test_query_eval.py
@@ -160,21 +160,13 @@ def test_query_empty_string(self):
             df.query("")
 
     def test_query_duplicate_column_name(self, engine, parser):
-        df = DataFrame(
-            {
-                "A": range(3),
-                "B": range(3),
-                "C": range(3)
-            }
-        ).rename(columns={"B": "A"})
+        df = DataFrame({"A": range(3), "B": range(3), "C": range(3)}).rename(
+            columns={"B": "A"}
+        )
 
         res = df.query("C == 1", engine=engine, parser=parser)
 
-        expect = DataFrame(
-            [[1, 1, 1]],
-            columns=["A", "A", "C"],
-            index=[1]
-        )
+        expect = DataFrame([[1, 1, 1]], columns=["A", "A", "C"], index=[1])
 
         tm.assert_frame_equal(res, expect)
 
@@ -1140,9 +1132,7 @@ def test_query_with_nested_special_character(self, parser, engine):
             [">=", operator.ge],
         ],
     )
-    def test_query_lex_compare_strings(
-        self, parser, engine, op, func
-    ):
+    def test_query_lex_compare_strings(self, parser, engine, op, func):
         a = Series(np.random.default_rng(2).choice(list("abcde"), 20))
         b = Series(np.arange(a.size))
         df = DataFrame({"X": a, "Y": b})
diff --git a/pandas/tests/indexes/multi/test_insert_level.py b/pandas/tests/indexes/multi/test_insert_level.py
@@ -5,87 +5,119 @@
 
 
 class TestMultiIndexInsertLevel:
-    def setup_method(self):
-        self.simple_idx = pd.MultiIndex.from_tuples(
+    @pytest.mark.parametrize(
+        "position, value, name, expected_tuples, expected_names",
+        [
+            (
+                0,
+                "new_value",
+                None,
+                [("new_value", "A", 1), ("new_value", "B", 2), ("new_value", "C", 3)],
+                [None, "level1", "level2"],
+            ),
+            (
+                1,
+                "middle",
+                None,
+                [("A", "middle", 1), ("B", "middle", 2), ("C", "middle", 3)],
+                ["level1", None, "level2"],
+            ),
+            (
+                0,
+                "new_val",
+                "new_level",
+                [("new_val", "A", 1), ("new_val", "B", 2), ("new_val", "C", 3)],
+                ["new_level", "level1", "level2"],
+            ),
+            (
+                1,
+                "middle",
+                "custom_name",
+                [("A", "middle", 1), ("B", "middle", 2), ("C", "middle", 3)],
+                ["level1", "custom_name", "level2"],
+            ),
+        ],
+    )
+    def test_insert_level_basic(
+        self, position, value, name, expected_tuples, expected_names
+    ):
+        simple_idx = pd.MultiIndex.from_tuples(
             [("A", 1), ("B", 2), ("C", 3)], names=["level1", "level2"]
         )
-        self.empty_idx = pd.MultiIndex.from_tuples([], names=["level1", "level2"])
 
-    def test_insert_level_basic(self):
-        result = self.simple_idx.insert_level(0, "new_value")
-        expected = pd.MultiIndex.from_tuples(
-            [("new_value", "A", 1), ("new_value", "B", 2), ("new_value", "C", 3)],
-            names=[None, "level1", "level2"],
-        )
+        result = simple_idx.insert_level(position, value, name=name)
+        expected = pd.MultiIndex.from_tuples(expected_tuples, names=expected_names)
         tm.assert_index_equal(result, expected)
 
-        result = self.simple_idx.insert_level(1, "middle")
-        expected = pd.MultiIndex.from_tuples(
-            [("A", "middle", 1), ("B", "middle", 2), ("C", "middle", 3)],
-            names=["level1", None, "level2"],
+    @pytest.mark.parametrize(
+        "position, value",
+        [
+            (0, "start"),
+            (2, "end"),
+        ],
+    )
+    def test_insert_level_edge_positions(self, position, value):
+        simple_idx = pd.MultiIndex.from_tuples(
+            [("A", 1), ("B", 2), ("C", 3)], names=["level1", "level2"]
         )
-        tm.assert_index_equal(result, expected)
 
-    def test_insert_level_with_different_values(self):
-        new_values = ["X", "Y", "Z"]
-        result = self.simple_idx.insert_level(1, new_values)
-        expected = pd.MultiIndex.from_tuples(
-            [("A", "X", 1), ("B", "Y", 2), ("C", "Z", 3)],
-            names=["level1", None, "level2"],
+        result = simple_idx.insert_level(position, value)
+        assert result.nlevels == 3
+
+    @pytest.mark.parametrize(
+        "position, value, expected_error",
+        [
+            (5, "invalid", "position must be between"),
+            (-1, "invalid", "position must be between"),
+            (1, ["too", "few"], "Length of values must match"),
+        ],
+    )
+    def test_insert_level_error_cases(self, position, value, expected_error):
+        simple_idx = pd.MultiIndex.from_tuples(
+            [("A", 1), ("B", 2), ("C", 3)], names=["level1", "level2"]
         )
-        tm.assert_index_equal(result, expected)
-
-    def test_insert_level_with_name(self):
-        result = self.simple_idx.insert_level(0, "new_val", name="new_level")
-        assert result.names[0] == "new_level"
-
-    def test_insert_level_edge_positions(self):
-        result_start = self.simple_idx.insert_level(0, "start")
-        assert result_start.nlevels == 3
-
-        result_end = self.simple_idx.insert_level(2, "end")
-        assert result_end.nlevels == 3
-
-    def test_insert_level_error_cases(self):
-        with pytest.raises(ValueError, match="position must be between"):
-            self.simple_idx.insert_level(5, "invalid")
 
-        with pytest.raises(ValueError, match="position must be between"):
-            self.simple_idx.insert_level(-1, "invalid")
+        with pytest.raises(ValueError, match=expected_error):
+            simple_idx.insert_level(position, value)
 
-        with pytest.raises(ValueError, match="Length of values must match"):
-            self.simple_idx.insert_level(1, ["too", "few"])
-
-    def test_insert_level_with_different_data_types(self):
-        result_int = self.simple_idx.insert_level(1, 100)
-
-        result_float = self.simple_idx.insert_level(1, 1.5)
-
-        result_none = self.simple_idx.insert_level(1, None)
+    @pytest.mark.parametrize(
+        "value",
+        [100, 1.5, None],
+    )
+    def test_insert_level_with_different_data_types(self, value):
+        simple_idx = pd.MultiIndex.from_tuples(
+            [("A", 1), ("B", 2), ("C", 3)], names=["level1", "level2"]
+        )
 
-        assert result_int.nlevels == 3
-        assert result_float.nlevels == 3
-        assert result_none.nlevels == 3
+        result = simple_idx.insert_level(1, value)
+        assert result.nlevels == 3
 
     def test_insert_level_preserves_original(self):
-        original = self.simple_idx.copy()
-        result = self.simple_idx.insert_level(1, "temp")
+        simple_idx = pd.MultiIndex.from_tuples(
+            [("A", 1), ("B", 2), ("C", 3)], names=["level1", "level2"]
+        )
 
-        tm.assert_index_equal(original, self.simple_idx)
+        original = simple_idx.copy()
+        simple_idx.insert_level(1, "temp")
 
-        assert result.nlevels == original.nlevels + 1
+        tm.assert_index_equal(original, simple_idx)
 
-        def test_debug_names():
-            idx = pd.MultiIndex.from_tuples(
-                [("A", 1), ("B", 2), ("C", 3)], names=["level1", "level2"]
-            )
-            print("Original names:", idx.names)
+    def test_insert_level_empty_index(self):
+        empty_idx = pd.MultiIndex.from_tuples([], names=["level1", "level2"])
 
-            result = idx.insert_level(0, "new_value")
-            print("Result names:", result.names)
+        result = empty_idx.insert_level(0, [])
+        assert result.nlevels == 3
+        assert len(result) == 0
 
-            expected = pd.MultiIndex.from_tuples(
-                [("new_value", "A", 1), ("new_value", "B", 2), ("new_value", "C", 3)],
-                names=[None, "level1", "level2"],
-            )
-            print("Expected names:", expected.names)
+    def test_insert_level_with_different_values(self):
+        simple_idx = pd.MultiIndex.from_tuples(
+            [("A", 1), ("B", 2), ("C", 3)], names=["level1", "level2"]
+        )
+
+        new_values = ["X", "Y", "Z"]
+        result = simple_idx.insert_level(1, new_values)
+        expected = pd.MultiIndex.from_tuples(
+            [("A", "X", 1), ("B", "Y", 2), ("C", "Z", 3)],
+            names=["level1", None, "level2"],
+        )
+        tm.assert_index_equal(result, expected)
