DEPR: DataFrame.swapaxes

doc/source/whatsnew/v2.1.0.rst

@@ -102,7 +102,7 @@ Deprecations
 - Deprecated ``axis=1`` in :meth:`DataFrame.groupby` and in :class:`Grouper` constructor, do ``frame.T.groupby(...)`` instead (:issue:`51203`)
 - Deprecated passing a :class:`DataFrame` to :meth:`DataFrame.from_records`, use :meth:`DataFrame.set_index` or :meth:`DataFrame.drop` instead (:issue:`51353`)
 - Deprecated accepting slices in :meth:`DataFrame.take`, call ``obj[slicer]`` or pass a sequence of integers instead (:issue:`51539`)
--
+- Deprecated :meth:`DataFrame.swapaxes` and :meth:`Series.swapaxes`, use :meth:`DataFrame.transpose` or :meth:`Series.transpose` instead (:issue:`51946`)
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_210.performance:

pandas/core/generic.py

@@ -742,6 +742,15 @@ def swapaxes(
         -------
         same as input
         """
+        warnings.warn(
+            # GH#51946
+            f"'{type(self).__name__}.swapaxes' is deprecated and \
+                will be removed in a future version. \
+                Please use '{type(self).__name__}.transpose' instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         i = self._get_axis_number(axis1)
         j = self._get_axis_number(axis2)
 

pandas/tests/copy_view/test_methods.py

@@ -1,3 +1,5 @@
+import inspect
+
 import numpy as np
 import pytest
 
@@ -115,7 +117,13 @@ def test_methods_copy_keyword(
         index = date_range("2012-01-01", freq="D", periods=3, tz="Europe/Brussels")
 
     df = DataFrame({"a": [1, 2, 3], "b": [4, 5, 6], "c": [0.1, 0.2, 0.3]}, index=index)
-    df2 = method(df, copy=copy)
+
+    if "swapaxes" in inspect.getsource(method):
+        msg = "'DataFrame.swapaxes' is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df2 = method(df, copy=copy)
+    else:
+        df2 = method(df, copy=copy)
 
     share_memory = using_copy_on_write or copy is False
 
@@ -184,7 +192,13 @@ def test_methods_series_copy_keyword(request, method, copy, using_copy_on_write)
         index = MultiIndex.from_arrays([[1, 2, 3], [4, 5, 6]])
 
     ser = Series([1, 2, 3], index=index)
-    ser2 = method(ser, copy=copy)
+
+    if "swapaxes" in inspect.getsource(method):
+        msg = "'Series.swapaxes' is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            ser2 = method(ser, copy=copy)
+    else:
+        ser2 = method(ser, copy=copy)
 
     share_memory = using_copy_on_write or copy is False
 
@@ -610,7 +624,9 @@ def test_to_frame(using_copy_on_write):
 def test_swapaxes_noop(using_copy_on_write, ax):
     df = DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
     df_orig = df.copy()
-    df2 = df.swapaxes(ax, ax)
+    msg = "'DataFrame.swapaxes' is deprecated"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        df2 = df.swapaxes(ax, ax)
 
     if using_copy_on_write:
         assert np.shares_memory(get_array(df2, "a"), get_array(df, "a"))
@@ -627,7 +643,9 @@ def test_swapaxes_noop(using_copy_on_write, ax):
 def test_swapaxes_single_block(using_copy_on_write):
     df = DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]}, index=["x", "y", "z"])
     df_orig = df.copy()
-    df2 = df.swapaxes("index", "columns")
+    msg = "'DataFrame.swapaxes' is deprecated"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        df2 = df.swapaxes("index", "columns")
 
     if using_copy_on_write:
         assert np.shares_memory(get_array(df2, "x"), get_array(df, "a"))

pandas/tests/frame/methods/test_swapaxes.py

@@ -8,22 +8,30 @@
 class TestSwapAxes:
     def test_swapaxes(self):
         df = DataFrame(np.random.randn(10, 5))
-        tm.assert_frame_equal(df.T, df.swapaxes(0, 1))
-        tm.assert_frame_equal(df.T, df.swapaxes(1, 0))
+        msg = "'DataFrame.swapaxes' is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            tm.assert_frame_equal(df.T, df.swapaxes(0, 1))
+            tm.assert_frame_equal(df.T, df.swapaxes(1, 0))
 
     def test_swapaxes_noop(self):
         df = DataFrame(np.random.randn(10, 5))
-        tm.assert_frame_equal(df, df.swapaxes(0, 0))
+        msg = "'DataFrame.swapaxes' is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            tm.assert_frame_equal(df, df.swapaxes(0, 0))
 
     def test_swapaxes_invalid_axis(self):
         df = DataFrame(np.random.randn(10, 5))
-        msg = "No axis named 2 for object type DataFrame"
-        with pytest.raises(ValueError, match=msg):
-            df.swapaxes(2, 5)
+        msg = "'DataFrame.swapaxes' is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            msg = "No axis named 2 for object type DataFrame"
+            with pytest.raises(ValueError, match=msg):
+                df.swapaxes(2, 5)
 
     def test_round_empty_not_input(self):
         # GH#51032
         df = DataFrame({"a": [1, 2]})
-        result = df.swapaxes("index", "index")
+        msg = "'DataFrame.swapaxes' is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            result = df.swapaxes("index", "index")
         tm.assert_frame_equal(df, result)
         assert df is not result

pandas/tests/generic/test_finalize.py

@@ -251,7 +251,6 @@
             operator.methodcaller("isin", pd.DataFrame({"A": [1]})),
         ),
     ),
-    (pd.DataFrame, frame_data, operator.methodcaller("swapaxes", 0, 1)),
     (pd.DataFrame, frame_mi_data, operator.methodcaller("droplevel", "A")),
     (pd.DataFrame, frame_data, operator.methodcaller("pop", "A")),
     pytest.param(