BUG: DataFrame.melt gives unexpected result when column "value" already exists

doc/source/whatsnew/v1.1.0.rst

@@ -816,6 +816,7 @@ Deprecations
 - :meth:`util.testing.assert_almost_equal` now accepts both relative and absolute
   precision through the ``rtol``, and ``atol`` parameters, thus deprecating the
   ``check_less_precise`` parameter. (:issue:`13357`).
+- :func:`DataFrame.melt` accepting a value_name that already exists is deprecated, and will be removed in a future version (:issue:`34731`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/reshape/melt.py

@@ -1,5 +1,6 @@
 import re
 from typing import TYPE_CHECKING, List, cast
+import warnings
 
 import numpy as np
 
@@ -40,6 +41,16 @@ def melt(
     else:
         cols = list(frame.columns)
 
+    if value_name in frame.columns:
+        warnings.warn(
+            "This dataframe has a column name that matches the 'value_name' column "
+            "name of the resultiing Dataframe. "
+            "In the future this will raise an error, please set the 'value_name' "
+            "parameter of DataFrame.melt to a unique name.",
+            FutureWarning,
+            stacklevel=3,
+        )
+
     if id_vars is not None:
         if not is_list_like(id_vars):
             id_vars = [id_vars]

pandas/tests/reshape/test_melt.py

@@ -1014,3 +1014,17 @@ def test_col_substring_of_stubname(self):
         )
         result = pd.wide_to_long(wide_df, stubnames="PA", i=["node_id", "A"], j="time")
         tm.assert_frame_equal(result, expected)
+
+    def test_warn_of_column_name_value(self):
+        # GH34731
+        # raise a warning if the resultant value column name matches
+        # a name in the dataframe already (default name is "value")
+        df = pd.DataFrame({"col": list("ABC"), "value": range(10, 16, 2)})
+        expected = pd.DataFrame(
+            [["A", "col", "A"], ["B", "col", "B"], ["C", "col", "C"]],
+            columns=["value", "variable", "value"],
+        )
+
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.melt(id_vars="value")
+            tm.assert_frame_equal(result, expected)