add concat (data-apis#137)

* draft concat

* note about strictness

* note ordering

* note that order is indeed preservedd

* lint

* fixup first/last rendering

* move concat to __init__

* Update spec/API_specification/dataframe_api/dataframe_object.py

* Revert "Update spec/API_specification/dataframe_api/dataframe_object.py"

This reverts commit 2827cd6.

* Update spec/API_specification/dataframe_api/__init__.py

* Update spec/API_specification/dataframe_api/__init__.py

Co-authored-by: Keith Kraus <[email protected]>

* post-merge fixup

---------

Co-authored-by: MarcoGorelli <>
Co-authored-by: Keith Kraus <[email protected]>

Author: MarcoGorelli

spec/API_specification/dataframe_api/__init__.py

@@ -18,6 +18,26 @@
 conforming implementation adheres.
 """
 
+def concat(dataframes: Sequence[DataFrame]) -> DataFrame:
+    """
+    Concatenate DataFrames vertically.
+
+    To concatenate horizontally, please use ``insert``.
+
+    Parameters
+    ----------
+    dataframes : Sequence[DataFrame]
+        DataFrames to concatenate.
+        Column names, ordering, and dtypes must match.
+
+    Notes
+    -----
+    The order in which the input DataFrames appear in
+    the output is preserved (so long as the DataFrame implementation supports row
+    ordering).
+    """
+    ...
+
 def column_from_sequence(sequence: Sequence[object], *, dtype: dtype) -> Column:
     """
     Construct Column from sequence of elements.
@@ -52,3 +72,4 @@ def dataframe_from_dict(data: Mapping[str, Column]) -> DataFrame:
     -------
     DataFrame
     """
+    ...