DEPR: Deprecate positional arguments in pivot (#48301)

doc/source/whatsnew/v1.5.0.rst

@@ -911,6 +911,7 @@ Other Deprecations
 - Deprecated :attr:`Timedelta.freq` and :attr:`Timedelta.is_populated` (:issue:`46430`)
 - Deprecated :attr:`Timedelta.delta` (:issue:`46476`)
 - Deprecated passing arguments as positional in :meth:`DataFrame.any` and :meth:`Series.any` (:issue:`44802`)
+- Deprecated passing positional arguments to :meth:`DataFrame.pivot` and :func:`pivot` except ``data`` (:issue:`30228`)
 - Deprecated the methods :meth:`DataFrame.mad`, :meth:`Series.mad`, and the corresponding groupby methods (:issue:`11787`)
 - Deprecated positional arguments to :meth:`Index.join` except for ``other``, use keyword-only arguments instead of positional arguments (:issue:`46518`)
 - Deprecated positional arguments to :meth:`StringMethods.rsplit` and :meth:`StringMethods.split` except for ``pat``, use keyword-only arguments instead of positional arguments (:issue:`47423`)

pandas/core/frame.py

@@ -8580,6 +8580,7 @@ def groupby(
 
     @Substitution("")
     @Appender(_shared_docs["pivot"])
+    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self"])
     def pivot(self, index=None, columns=None, values=None) -> DataFrame:
         from pandas.core.reshape.pivot import pivot
 

pandas/core/reshape/pivot.py

@@ -19,6 +19,7 @@
 from pandas.util._decorators import (
     Appender,
     Substitution,
+    deprecate_nonkeyword_arguments,
 )
 
 from pandas.core.dtypes.cast import maybe_downcast_to_dtype
@@ -478,6 +479,7 @@ def _convert_by(by):
 
 @Substitution("\ndata : DataFrame")
 @Appender(_shared_docs["pivot"], indents=1)
+@deprecate_nonkeyword_arguments(version=None, allowed_args=["data"])
 def pivot(
     data: DataFrame,
     index: IndexLabel | None = None,

pandas/tests/reshape/test_pivot.py

@@ -480,9 +480,11 @@ def test_pivot_index_with_nan(self, method):
             }
         )
         if method:
-            result = df.pivot("a", "b", "c")
+            with tm.assert_produces_warning(FutureWarning):
+                result = df.pivot("a", columns="b", values="c")
         else:
-            result = pd.pivot(df, "a", "b", "c")
+            with tm.assert_produces_warning(FutureWarning):
+                result = pd.pivot(df, "a", columns="b", values="c")
         expected = DataFrame(
             [
                 [nan, nan, 17, nan],
@@ -494,7 +496,7 @@ def test_pivot_index_with_nan(self, method):
             columns=Index(["C1", "C2", "C3", "C4"], name="b"),
         )
         tm.assert_frame_equal(result, expected)
-        tm.assert_frame_equal(df.pivot("b", "a", "c"), expected.T)
+        tm.assert_frame_equal(df.pivot(index="b", columns="a", values="c"), expected.T)
 
     @pytest.mark.parametrize("method", [True, False])
     def test_pivot_index_with_nan_dates(self, method):
@@ -510,18 +512,18 @@ def test_pivot_index_with_nan_dates(self, method):
         df.loc[1, "b"] = df.loc[4, "b"] = np.nan
 
         if method:
-            pv = df.pivot("a", "b", "c")
+            pv = df.pivot(index="a", columns="b", values="c")
         else:
-            pv = pd.pivot(df, "a", "b", "c")
+            pv = pd.pivot(df, index="a", columns="b", values="c")
         assert pv.notna().values.sum() == len(df)
 
         for _, row in df.iterrows():
             assert pv.loc[row["a"], row["b"]] == row["c"]
 
         if method:
-            result = df.pivot("b", "a", "c")
+            result = df.pivot(index="b", columns="a", values="c")
         else:
-            result = pd.pivot(df, "b", "a", "c")
+            result = pd.pivot(df, index="b", columns="a", values="c")
         tm.assert_frame_equal(result, pv.T)
 
     @pytest.mark.filterwarnings("ignore:Timestamp.freq is deprecated:FutureWarning")
@@ -2275,11 +2277,11 @@ def test_pivot_duplicates(self):
             }
         )
         with pytest.raises(ValueError, match="duplicate entries"):
-            data.pivot("a", "b", "c")
+            data.pivot(index="a", columns="b", values="c")
 
     def test_pivot_empty(self):
         df = DataFrame(columns=["a", "b", "c"])
-        result = df.pivot("a", "b", "c")
+        result = df.pivot(index="a", columns="b", values="c")
         expected = DataFrame()
         tm.assert_frame_equal(result, expected, check_names=False)