ENH: Add allow_duplicates to MultiIndex.to_frame

doc/source/whatsnew/v1.4.0.rst

@@ -226,6 +226,7 @@ Other enhancements
 - :class:`ExtensionDtype` and :class:`ExtensionArray` are now (de)serialized when exporting a :class:`DataFrame` with :meth:`DataFrame.to_json` using ``orient='table'`` (:issue:`20612`, :issue:`44705`).
 - Add support for `Zstandard <http://facebook.github.io/zstd/>`_ compression to :meth:`DataFrame.to_pickle`/:meth:`read_pickle` and friends (:issue:`43925`)
 - :meth:`DataFrame.to_sql` now returns an ``int`` of the number of written rows (:issue:`23998`)
+- :meth:`MultiIndex.to_frame` now supports the argument ``allow_duplicates`` and raises on duplicate labels if it is missing or False (:issue:`45245`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/indexes/multi.py

@@ -1710,7 +1710,12 @@ def unique(self, level=None):
             level = self._get_level_number(level)
             return self._get_level_values(level=level, unique=True)
 
-    def to_frame(self, index: bool = True, name=lib.no_default) -> DataFrame:
+    def to_frame(
+        self,
+        index: bool = True,
+        name=lib.no_default,
+        allow_duplicates: bool = False,
+    ) -> DataFrame:
         """
         Create a DataFrame with the levels of the MultiIndex as columns.
 
@@ -1725,6 +1730,11 @@ def to_frame(self, index: bool = True, name=lib.no_default) -> DataFrame:
         name : list / sequence of str, optional
             The passed names should substitute index level names.
 
+        allow_duplicates : bool, optional default False
+            Allow duplicate column labels to be created.
+
+            .. versionadded:: 1.4.0
+
         Returns
         -------
         DataFrame : a DataFrame containing the original MultiIndex data.
@@ -1774,14 +1784,20 @@ def to_frame(self, index: bool = True, name=lib.no_default) -> DataFrame:
         else:
             idx_names = self.names
 
+        idx_names = [
+            level if name is None else name for level, name in enumerate(idx_names)
+        ]
+
+        if not allow_duplicates and len(set(idx_names)) != len(idx_names):
+            raise ValueError(
+                "Cannot create duplicate column labels if allow_duplicates is False"
+            )
+
         # Guarantee resulting column order - PY36+ dict maintains insertion order
         result = DataFrame(
-            {
-                (level if lvlname is None else lvlname): self._get_level_values(level)
-                for lvlname, level in zip(idx_names, range(len(self.levels)))
-            },
+            {level: self._get_level_values(level) for level in range(len(self.levels))},
             copy=False,
-        )
+        ).set_axis(idx_names, axis=1)
 
         if index:
             result.index = self

pandas/tests/indexes/multi/test_conversion.py

@@ -126,6 +126,28 @@ def test_to_frame_resulting_column_order():
     assert result == expected
 
 
+def test_to_frame_duplicate_labels():
+    # GH 45245
+    data = [(1, 2), (3, 4)]
+    names = ["a", "a"]
+    index = MultiIndex.from_tuples(data, names=names)
+    with pytest.raises(ValueError, match="Cannot create duplicate column labels"):
+        index.to_frame()
+
+    result = index.to_frame(allow_duplicates=True)
+    expected = DataFrame(data, index=index, columns=names)
+    tm.assert_frame_equal(result, expected)
+
+    names = [None, 0]
+    index = MultiIndex.from_tuples(data, names=names)
+    with pytest.raises(ValueError, match="Cannot create duplicate column labels"):
+        index.to_frame()
+
+    result = index.to_frame(allow_duplicates=True)
+    expected = DataFrame(data, index=index, columns=[0, 0])
+    tm.assert_frame_equal(result, expected)
+
+
 def test_to_flat_index(idx):
     expected = pd.Index(
         (