Add api_version to constructors (#233)

* add api versions to some constructors

* namespace -> object

* remove "to be returned,"

Author: MarcoGorelli

spec/API_specification/dataframe_api/__init__.py

@@ -63,7 +63,7 @@ def concat(dataframes: Sequence[DataFrame]) -> DataFrame:
     """
     ...
 
-def column_from_sequence(sequence: Sequence[Any], *, dtype: Any, name: str = '') -> Column[Any]:
+def column_from_sequence(sequence: Sequence[Any], *, dtype: Any, name: str = '', api_version: str | None = None) -> Column[Any]:
     """
     Construct Column from sequence of elements.
 
@@ -77,14 +77,21 @@ def column_from_sequence(sequence: Sequence[Any], *, dtype: Any, name: str = '')
         Name of column.
     dtype : DType
         Dtype of result. Must be specified.
+    api_version: str | None
+        A string representing the version of the dataframe API specification
+        in ``'YYYY.MM'`` form, for example, ``'2023.04'``.
+        If it is ``None``, it should return an object corresponding to
+        latest version of the dataframe API specification.  If the given
+        version is invalid or not implemented for the given module, an
+        error should be raised. Default: ``None``.
 
     Returns
     -------
     Column
     """
     ...
 
-def dataframe_from_dict(data: Mapping[str, Column[Any]]) -> DataFrame:
+def dataframe_from_dict(data: Mapping[str, Column[Any]], *, api_version: str | None = None) -> DataFrame:
     """
     Construct DataFrame from map of column names to Columns.
 
@@ -94,6 +101,13 @@ def dataframe_from_dict(data: Mapping[str, Column[Any]]) -> DataFrame:
         Column must be of the corresponding type of the DataFrame.
         For example, it is only supported to build a ``LibraryXDataFrame`` using
         ``LibraryXColumn`` instances.
+    api_version: str | None
+        A string representing the version of the dataframe API specification
+        in ``'YYYY.MM'`` form, for example, ``'2023.04'``.
+        If it is ``None``, it should return an object corresponding to
+        latest version of the dataframe API specification.  If the given
+        version is invalid or not implemented for the given module, an
+        error should be raised. Default: ``None``.
 
     Returns
     -------
@@ -109,7 +123,7 @@ def dataframe_from_dict(data: Mapping[str, Column[Any]]) -> DataFrame:
     ...
 
 
-def column_from_1d_array(array: Any, *, dtype: Any, name: str = '') -> Column[Any]:
+def column_from_1d_array(array: Any, *, dtype: Any, name: str = '', api_version: str | None = None) -> Column[Any]:
     """
     Construct Column from 1D array.
 
@@ -127,14 +141,21 @@ def column_from_1d_array(array: Any, *, dtype: Any, name: str = '') -> Column[An
         Name to give columns.
     dtype : DType
         Dtype of column.
+    api_version: str | None
+        A string representing the version of the dataframe API specification
+        in ``'YYYY.MM'`` form, for example, ``'2023.04'``.
+        If it is ``None``, it should return an object corresponding to
+        latest version of the dataframe API specification.  If the given
+        version is invalid or not implemented for the given module, an
+        error should be raised. Default: ``None``.
 
     Returns
     -------
     Column
     """
     ...
 
-def dataframe_from_2d_array(array: Any, *, names: Sequence[str], dtypes: Mapping[str, Any]) -> DataFrame:
+def dataframe_from_2d_array(array: Any, *, names: Sequence[str], dtypes: Mapping[str, Any], api_version: str | None = None) -> DataFrame:
     """
     Construct DataFrame from 2D array.
 
@@ -152,6 +173,13 @@ def dataframe_from_2d_array(array: Any, *, names: Sequence[str], dtypes: Mapping
         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]``.
+    api_version: str | None
+        A string representing the version of the dataframe API specification
+        in ``'YYYY.MM'`` form, for example, ``'2023.04'``.
+        If it is ``None``, it should return an object corresponding to
+        latest version of the dataframe API specification.  If the given
+        version is invalid or not implemented for the given module, an
+        error should be raised. Default: ``None``.
 
     Returns
     -------