Add 2d constructor (#208)

* add 2d constructor

* add names and dtypes params

* add column from 1d array too

* add note about casting

Author: MarcoGorelli

spec/API_specification/dataframe_api/__init__.py

@@ -15,8 +15,10 @@
     "DataFrame",
     "Column",
     "column_from_sequence",
+    "column_from_1d_array",
     "concat",
     "dataframe_from_dict",
+    "dataframe_from_2d_array",
     "is_null",
     "null",
     "Int64",
@@ -105,6 +107,57 @@ def dataframe_from_dict(data: Mapping[str, Column[Any]]) -> DataFrame:
     """
     ...
 
+
+def column_from_1d_array(array: Any, *, name: str, dtype: Any) -> Column[Any]:
+    """
+    Construct Column from 1D array.
+
+    See `dataframe_from_2d_array` for related 2D function.
+
+    Only Array-API-compliant 1D arrays are supported.
+    Cross-kind casting is undefined and may vary across implementations.
+    Downcasting is disallowed.
+
+    Parameters
+    ----------
+    array : array
+        array-API compliant 1D array
+    name : str
+        Name to give columns.
+    dtype : DType
+        Dtype of column.
+
+    Returns
+    -------
+    Column
+    """
+    ...
+
+def dataframe_from_2d_array(array: Any, *, names: Sequence[str], dtypes: Mapping[str, Any]) -> DataFrame:
+    """
+    Construct DataFrame from 2D array.
+
+    See `column_from_1d_array` for related 1D function.
+
+    Only Array-API-compliant 2D arrays are supported.
+    Cross-kind casting is undefined and may vary across implementations.
+    Downcasting is disallowed.
+
+    Parameters
+    ----------
+    array : array
+        array-API compliant 2D array
+    names : Sequence[str]
+        Names to give columns. Must be the same length as ``array.shape[1]``.
+    dtypes : Mapping[str, DType]
+        Dtype of each column. Must be the same length as ``array.shape[1]``.
+
+    Returns
+    -------
+    DataFrame
+    """
+    ...
+
 class null:
     """
     A `null` object to represent missing data.

spec/API_specification/index.rst

@@ -27,6 +27,10 @@ of objects and functions in the top-level namespace. The latter are:
    Float64
    Float32
    Bool
+   column_from_sequence
+   column_from_1d_array
+   dataframe_from_dict
+   dataframe_from_2d_array
 
 The ``DataFrame``, ``Column`` and ``GroupBy`` objects have the following
 methods and attributes: