DOC: add warning to append about inefficiency (#17017)

Author: shanral

pandas/core/frame.py

@@ -4715,6 +4715,11 @@ def append(self, other, ignore_index=False, verify_integrity=False):
         the DataFrame's index, the order of the columns in the resulting
         DataFrame will be unchanged.
 
+        Iteratively appending rows to a DataFrame can be more computationally
+        intensive than a single concatenate. A better solution is to append
+        those rows to a list and then concatenate the list with the original
+        DataFrame all at once.
+
         See also
         --------
         pandas.concat : General function to concatenate DataFrame, Series
@@ -4745,6 +4750,33 @@ def append(self, other, ignore_index=False, verify_integrity=False):
         2  5  6
         3  7  8
 
+        The following, while not recommended methods for generating DataFrames,
+        show two ways to generate a DataFrame from multiple data sources.
+
+        Less efficient:
+
+        >>> df = pd.DataFrame(columns=['A'])
+        >>> for i in range(5):
+        ...     df = df.append({'A'}: i}, ignore_index=True)
+        >>> df
+           A
+        0  0
+        1  1
+        2  2
+        3  3
+        4  4
+
+        More efficient:
+
+        >>> pd.concat([pd.DataFrame([i], columns=['A']) for i in range(5)],
+        ...           ignore_index=True)
+           A
+        0  0
+        1  1
+        2  2
+        3  3
+        4  4
+
         """
         if isinstance(other, (Series, dict)):
             if isinstance(other, dict):

pandas/core/series.py

@@ -1563,6 +1563,18 @@ def append(self, to_append, ignore_index=False, verify_integrity=False):
         verify_integrity : boolean, default False
             If True, raise Exception on creating index with duplicates
 
+        Notes
+        -----
+        Iteratively appending to a Series can be more computationally intensive
+        than a single concatenate. A better solution is to append values to a
+        list and then concatenate the list with the original Series all at
+        once.
+
+        See also
+        --------
+        pandas.concat : General function to concatenate DataFrame, Series
+            or Panel objects
+
         Returns
         -------
         appended : Series