DEPR: Series/DataFrame.append (#35407)

doc/source/whatsnew/v1.4.0.rst

@@ -438,6 +438,61 @@ when given numeric data, but in the future, a :class:`NumericIndex` will be retu
     Out [4]: NumericIndex([1, 2, 3], dtype='uint64')
 
 
+.. _whatsnew_140.deprecations.frame_series_append:
+
+Deprecated Frame.append and Series.append
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:meth:`DataFrame.append` and :meth:`Series.append` have been deprecated and will be removed in Pandas 2.0.
+Use :func:`pandas.concat` instead (:issue:`35407`).
+
+*Deprecated syntax*
+
+.. code-block:: ipython
+
+    In [1]: pd.Series([1, 2]).append(pd.Series([3, 4])
+    Out [1]:
+    <stdin>:1: FutureWarning: The series.append method is deprecated and will be removed from pandas in a future version. Use pandas.concat instead.
+    0    1
+    1    2
+    0    3
+    1    4
+    dtype: int64
+
+    In [2]: df1 = pd.DataFrame([[1, 2], [3, 4]], columns=list('AB'))
+    In [3]: df2 = pd.DataFrame([[5, 6], [7, 8]], columns=list('AB'))
+    In [4]: df1.append(df2)
+    Out [4]:
+    <stdin>:1: FutureWarning: The series.append method is deprecated and will be removed from pandas in a future version. Use pandas.concat instead.
+       A  B
+    0  1  2
+    1  3  4
+    0  5  6
+    1  7  8
+
+*Recommended syntax*
+
+.. code-block:: ipython
+
+    In [1]: pd.concat([pd.Series([1, 2]), pd.Series([3, 4])])
+    Out [1]:
+    0    1
+    1    2
+    0    3
+    1    4
+    dtype: int64
+
+    In [2]: df1 = pd.DataFrame([[1, 2], [3, 4]], columns=list('AB'))
+    In [3]: df2 = pd.DataFrame([[5, 6], [7, 8]], columns=list('AB'))
+    In [4]: pd.concat([df1, df2])
+    Out [4]:
+       A  B
+    0  1  2
+    1  3  4
+    0  5  6
+    1  7  8
+
+
 .. _whatsnew_140.deprecations.other:
 
 Other Deprecations

pandas/core/frame.py

@@ -9114,6 +9114,14 @@ def append(
         3  3
         4  4
         """
+        warnings.warn(
+            "The frame.append method is deprecated "
+            "and will be removed from pandas in a future version. "
+            "Use pandas.concat instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         combined_columns = None
         if isinstance(other, (Series, dict)):
             if isinstance(other, dict):

pandas/core/series.py

@@ -2888,6 +2888,14 @@ def append(
         ...
         ValueError: Indexes have overlapping values: [0, 1, 2]
         """
+        warnings.warn(
+            "The series.append method is deprecated "
+            "and will be removed from pandas in a future version. "
+            "Use pandas.concat instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         from pandas.core.reshape.concat import concat
 
         if isinstance(to_append, (list, tuple)):

pandas/tests/frame/methods/test_append.py

@@ -12,6 +12,7 @@
 import pandas._testing as tm
 
 
+@pytest.mark.filterwarnings("ignore:.*append method is deprecated.*:FutureWarning")
 class TestDataFrameAppend:
     def test_append_multiindex(self, multiindex_dataframe_random_data, frame_or_series):
         obj = multiindex_dataframe_random_data
@@ -124,8 +125,7 @@ def test_append_missing_cols(self):
         df = DataFrame(np.random.randn(5, 4), columns=["foo", "bar", "baz", "qux"])
 
         dicts = [{"foo": 9}, {"bar": 10}]
-        with tm.assert_produces_warning(None):
-            result = df.append(dicts, ignore_index=True, sort=True)
+        result = df.append(dicts, ignore_index=True, sort=True)
 
         expected = df.append(DataFrame(dicts), ignore_index=True, sort=True)
         tm.assert_frame_equal(result, expected)
@@ -270,3 +270,9 @@ def test_multiindex_column_append_multiple(self):
                 {"col1": [1, 2, 3] * (i + 1), "col2": [11, 12, 13] * (i + 1)}
             )
             tm.assert_frame_equal(result, expected)
+
+    def test_append_raises_future_warning(self):
+        df1 = DataFrame([[1, 2], [3, 4]])
+        df2 = DataFrame([[5, 6], [7, 8]])
+        with tm.assert_produces_warning(FutureWarning):
+            df1.append(df2)

pandas/tests/series/methods/test_append.py

@@ -13,6 +13,7 @@
 import pandas._testing as tm
 
 
+@pytest.mark.filterwarnings("ignore:.*append method is deprecated.*:FutureWarning")
 class TestSeriesAppend:
     def test_append_preserve_name(self, datetime_series):
         result = datetime_series[:5].append(datetime_series[5:])
@@ -82,7 +83,12 @@ def test_append_dataframe_raises(self):
         with pytest.raises(TypeError, match=msg):
             df.A.append([df])
 
+    def test_append_raises_future_warning(self):
+        with tm.assert_produces_warning(FutureWarning):
+            Series([1, 2]).append(Series([3, 4]))
 
+
+@pytest.mark.filterwarnings("ignore:.*append method is deprecated.*:FutureWarning")
 class TestSeriesAppendWithDatetimeIndex:
     def test_append(self):
         rng = date_range("5/8/2012 1:45", periods=10, freq="5T")
@@ -107,6 +113,7 @@ def test_append(self):
         rng2 = rng.copy()
         rng1.name = "foo"
         rng2.name = "bar"
+
         assert rng1.append(rng1).name == "foo"
         assert rng1.append(rng2).name is None