DEPR: Series/DataFrame.append (pandas-dev#35407)

Author: neinkeinkaffee

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.core.reshape.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 frame.append method is deprecated and will be removed from pandas in a future version. Use pandas.core.reshape.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 frame.append method is deprecated and will be removed from pandas in a future version. Use pandas.core.reshape.concat instead.
+       A  B
+    0  1  2
+    1  3  4
+    0  5  6
+    1  7  8
+
+*Recommended syntax*
+
+.. code-block:: ipython
+
+    In [1]: pd.core.reshape.concat.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.core.reshape.concat.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.core.reshape.concat instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+
         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 frame.append method is deprecated "
+            "and will be removed from pandas in a future version. "
+            "Use pandas.core.reshape.concat instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+
         from pandas.core.reshape.concat import concat
 
         if isinstance(to_append, (list, tuple)):

pandas/tests/frame/methods/test_append.py

@@ -21,19 +21,22 @@ def test_append_multiindex(self, multiindex_dataframe_random_data, frame_or_seri
         a = obj[:5]
         b = obj[5:]
 
-        result = a.append(b)
+        with tm.assert_produces_warning(FutureWarning):
+            result = a.append(b)
         tm.assert_equal(result, obj)
 
     def test_append_empty_list(self):
         # GH 28769
         df = DataFrame()
-        result = df.append([])
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append([])
         expected = df
         tm.assert_frame_equal(result, expected)
         assert result is not df
 
         df = DataFrame(np.random.randn(5, 4), columns=["foo", "bar", "baz", "qux"])
-        result = df.append([])
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append([])
         expected = df
         tm.assert_frame_equal(result, expected)
         assert result is not df  # .append() should return a new object
@@ -43,57 +46,69 @@ def test_append_series_dict(self):
 
         series = df.loc[4]
         msg = "Indexes have overlapping values"
-        with pytest.raises(ValueError, match=msg):
+        with pytest.raises(ValueError, match=msg), tm.assert_produces_warning(
+            FutureWarning
+        ):
             df.append(series, verify_integrity=True)
 
         series.name = None
         msg = "Can only append a Series if ignore_index=True"
-        with pytest.raises(TypeError, match=msg):
+        with pytest.raises(TypeError, match=msg), tm.assert_produces_warning(
+            FutureWarning
+        ):
             df.append(series, verify_integrity=True)
 
-        result = df.append(series[::-1], ignore_index=True)
-        expected = df.append(
-            DataFrame({0: series[::-1]}, index=df.columns).T, ignore_index=True
-        )
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(series[::-1], ignore_index=True)
+            expected = df.append(
+                DataFrame({0: series[::-1]}, index=df.columns).T, ignore_index=True
+            )
         tm.assert_frame_equal(result, expected)
 
         # dict
-        result = df.append(series.to_dict(), ignore_index=True)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(series.to_dict(), ignore_index=True)
         tm.assert_frame_equal(result, expected)
 
-        result = df.append(series[::-1][:3], ignore_index=True)
-        expected = df.append(
-            DataFrame({0: series[::-1][:3]}).T, ignore_index=True, sort=True
-        )
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(series[::-1][:3], ignore_index=True)
+            expected = df.append(
+                DataFrame({0: series[::-1][:3]}).T, ignore_index=True, sort=True
+            )
         tm.assert_frame_equal(result, expected.loc[:, result.columns])
 
         msg = "Can only append a dict if ignore_index=True"
-        with pytest.raises(TypeError, match=msg):
+        with pytest.raises(TypeError, match=msg), tm.assert_produces_warning(
+            FutureWarning
+        ):
             df.append(series.to_dict())
 
         # can append when name set
         row = df.loc[4]
         row.name = 5
-        result = df.append(row)
-        expected = df.append(df[-1:], ignore_index=True)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(row)
+            expected = df.append(df[-1:], ignore_index=True)
         tm.assert_frame_equal(result, expected)
 
     def test_append_list_of_series_dicts(self):
         df = DataFrame(np.random.randn(5, 4), columns=["foo", "bar", "baz", "qux"])
 
         dicts = [x.to_dict() for idx, x in df.iterrows()]
 
-        result = df.append(dicts, ignore_index=True)
-        expected = df.append(df, ignore_index=True)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(dicts, ignore_index=True)
+            expected = df.append(df, ignore_index=True)
         tm.assert_frame_equal(result, expected)
 
         # different columns
         dicts = [
             {"foo": 1, "bar": 2, "baz": 3, "peekaboo": 4},
             {"foo": 5, "bar": 6, "baz": 7, "peekaboo": 8},
         ]
-        result = df.append(dicts, ignore_index=True, sort=True)
-        expected = df.append(DataFrame(dicts), ignore_index=True, sort=True)
+        with tm.assert_produces_warning(FutureWarning):
+            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)
 
     def test_append_list_retain_index_name(self):
@@ -109,11 +124,13 @@ def test_append_list_retain_index_name(self):
         )
 
         # append series
-        result = df.append(serc)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(serc)
         tm.assert_frame_equal(result, expected)
 
         # append list of series
-        result = df.append([serc])
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append([serc])
         tm.assert_frame_equal(result, expected)
 
     def test_append_missing_cols(self):
@@ -124,39 +141,43 @@ 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):
+        with tm.assert_produces_warning(FutureWarning):
             result = df.append(dicts, ignore_index=True, sort=True)
 
-        expected = df.append(DataFrame(dicts), ignore_index=True, sort=True)
+            expected = df.append(DataFrame(dicts), ignore_index=True, sort=True)
         tm.assert_frame_equal(result, expected)
 
     def test_append_empty_dataframe(self):
 
         # Empty df append empty df
         df1 = DataFrame()
         df2 = DataFrame()
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = df1.copy()
         tm.assert_frame_equal(result, expected)
 
         # Non-empty df append empty df
         df1 = DataFrame(np.random.randn(5, 2))
         df2 = DataFrame()
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = df1.copy()
         tm.assert_frame_equal(result, expected)
 
         # Empty df with columns append empty df
         df1 = DataFrame(columns=["bar", "foo"])
         df2 = DataFrame()
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = df1.copy()
         tm.assert_frame_equal(result, expected)
 
         # Non-Empty df with columns append empty df
         df1 = DataFrame(np.random.randn(5, 2), columns=["bar", "foo"])
         df2 = DataFrame()
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = df1.copy()
         tm.assert_frame_equal(result, expected)
 
@@ -168,19 +189,22 @@ def test_append_dtypes(self):
 
         df1 = DataFrame({"bar": Timestamp("20130101")}, index=range(5))
         df2 = DataFrame()
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = df1.copy()
         tm.assert_frame_equal(result, expected)
 
         df1 = DataFrame({"bar": Timestamp("20130101")}, index=range(1))
         df2 = DataFrame({"bar": "foo"}, index=range(1, 2))
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = DataFrame({"bar": [Timestamp("20130101"), "foo"]})
         tm.assert_frame_equal(result, expected)
 
         df1 = DataFrame({"bar": Timestamp("20130101")}, index=range(1))
         df2 = DataFrame({"bar": np.nan}, index=range(1, 2))
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = DataFrame(
             {"bar": Series([Timestamp("20130101"), np.nan], dtype="M8[ns]")}
         )
@@ -189,7 +213,8 @@ def test_append_dtypes(self):
 
         df1 = DataFrame({"bar": Timestamp("20130101")}, index=range(1))
         df2 = DataFrame({"bar": np.nan}, index=range(1, 2), dtype=object)
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = DataFrame(
             {"bar": Series([Timestamp("20130101"), np.nan], dtype="M8[ns]")}
         )
@@ -198,7 +223,8 @@ def test_append_dtypes(self):
 
         df1 = DataFrame({"bar": np.nan}, index=range(1))
         df2 = DataFrame({"bar": Timestamp("20130101")}, index=range(1, 2))
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = DataFrame(
             {"bar": Series([np.nan, Timestamp("20130101")], dtype="M8[ns]")}
         )
@@ -207,7 +233,8 @@ def test_append_dtypes(self):
 
         df1 = DataFrame({"bar": Timestamp("20130101")}, index=range(1))
         df2 = DataFrame({"bar": 1}, index=range(1, 2), dtype=object)
-        result = df1.append(df2)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df1.append(df2)
         expected = DataFrame({"bar": Series([Timestamp("20130101"), 1])})
         tm.assert_frame_equal(result, expected)
 
@@ -218,7 +245,8 @@ def test_append_timestamps_aware_or_naive(self, tz_naive_fixture, timestamp):
         # GH 30238
         tz = tz_naive_fixture
         df = DataFrame([Timestamp(timestamp, tz=tz)])
-        result = df.append(df.iloc[0]).iloc[-1]
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(df.iloc[0]).iloc[-1]
         expected = Series(Timestamp(timestamp, tz=tz), name=0)
         tm.assert_series_equal(result, expected)
 
@@ -234,7 +262,8 @@ def test_append_timestamps_aware_or_naive(self, tz_naive_fixture, timestamp):
     )
     def test_other_dtypes(self, data, dtype):
         df = DataFrame(data, dtype=dtype)
-        result = df.append(df.iloc[0]).iloc[-1]
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(df.iloc[0]).iloc[-1]
         expected = Series(data, name=0, dtype=dtype)
         tm.assert_series_equal(result, expected)
 
@@ -249,7 +278,8 @@ def test_append_numpy_bug_1681(self, dtype):
         df = DataFrame()
         other = DataFrame({"A": "foo", "B": index}, index=index)
 
-        result = df.append(other)
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.append(other)
         assert (result["B"] == index).all()
 
     @pytest.mark.filterwarnings("ignore:The values in the array:RuntimeWarning")
@@ -264,7 +294,8 @@ def test_multiindex_column_append_multiple(self):
         df2 = df.copy()
         for i in range(1, 10):
             df[i, "colA"] = 10
-            df = df.append(df2, ignore_index=True)
+            with tm.assert_produces_warning(FutureWarning):
+                df = df.append(df2, ignore_index=True)
             result = df["multi"]
             expected = DataFrame(
                 {"col1": [1, 2, 3] * (i + 1), "col2": [11, 12, 13] * (i + 1)}