DEPR: Enforce melt(value_name) behavior (pandas-dev#49462)

Author: mroeschke

doc/source/whatsnew/v2.0.0.rst

@@ -383,6 +383,7 @@ Removal of prior version deprecations/changes
 - Enforced disallowing ``dict`` or ``set`` objects in ``suffixes`` in :func:`merge` (:issue:`34810`)
 - Enforced disallowing :func:`merge` to produce duplicated columns through the ``suffixes`` keyword and already existing columns (:issue:`22818`)
 - Enforced disallowing using :func:`merge` or :func:`join` on a different number of levels (:issue:`34862`)
+- Enforced disallowing ``value_name`` argument in :func:`DataFrame.melt` to match an element in the :class:`DataFrame` columns (:issue:`35003`)
 - Removed setting Categorical._codes directly (:issue:`41429`)
 - Removed setting Categorical.categories directly (:issue:`47834`)
 - Removed argument ``inplace`` from :meth:`Categorical.add_categories`, :meth:`Categorical.remove_categories`, :meth:`Categorical.set_categories`, :meth:`Categorical.rename_categories`, :meth:`Categorical.reorder_categories`, :meth:`Categorical.set_ordered`, :meth:`Categorical.as_ordered`, :meth:`Categorical.as_unordered` (:issue:`37981`, :issue:`41118`, :issue:`41133`, :issue:`47834`)

pandas/core/reshape/melt.py

@@ -5,15 +5,13 @@
     TYPE_CHECKING,
     Hashable,
 )
-import warnings
 
 import numpy as np
 
 from pandas.util._decorators import (
     Appender,
     deprecate_kwarg,
 )
-from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.common import (
     is_extension_array_dtype,
@@ -56,13 +54,9 @@ def melt(
         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 resulting Dataframe. "
-            "In the future this will raise an error, please set the 'value_name' "
-            "parameter of DataFrame.melt to a unique name.",
-            FutureWarning,
-            stacklevel=find_stack_level(),
+        raise ValueError(
+            f"value_name ({value_name}) cannot match an element in "
+            "the DataFrame columns."
         )
 
     if id_vars is not None:

pandas/tests/reshape/test_melt.py

@@ -1,3 +1,5 @@
+import re
+
 import numpy as np
 import pytest
 
@@ -1073,19 +1075,16 @@ def test_col_substring_of_stubname(self):
         result = 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
+    def test_raise_of_column_name_value(self):
+        # GH34731, enforced in 2.0
+        # raise a ValueError if the resultant value column name matches
         # a name in the dataframe already (default name is "value")
         df = DataFrame({"col": list("ABC"), "value": range(10, 16, 2)})
-        expected = 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)
+        with pytest.raises(
+            ValueError, match=re.escape("value_name (value) cannot match")
+        ):
+            df.melt(id_vars="value", value_name="value")
 
     @pytest.mark.parametrize("dtype", ["O", "string"])
     def test_missing_stubname(self, dtype):