remove dtype from to_array (#325)

* remove dtype from to_array

* link to promotion doc

Author: MarcoGorelli

spec/API_specification/dataframe_api/dataframe_object.py

@@ -813,26 +813,26 @@ def drop_nulls(
         """
         ...
 
-    def to_array(self, dtype: DType) -> Any:
+    def to_array(self) -> Any:
         """Convert to array-API-compliant object.
 
-        Parameters
-        ----------
-        dtype : DType
-            The dtype of the array-API-compliant object to return.
-            Must be one of:
-
-            - Bool()
-            - Int8()
-            - Int16()
-            - Int32()
-            - Int64()
-            - UInt8()
-            - UInt16()
-            - UInt32()
-            - UInt64()
-            - Float32()
-            - Float64()
+        The resulting array will have the corresponding dtype from the
+        Array API:
+
+        - Bool() -> 'bool'
+        - Int8() -> 'int8'
+        - Int16() -> 'int16'
+        - Int32() -> 'int32'
+        - Int64() -> 'int64'
+        - UInt8() -> 'uint8'
+        - UInt16() -> 'uint16'
+        - UInt32() -> 'uint32'
+        - UInt64() -> 'uint64'
+        - Float32() -> 'float32'
+        - Float64() -> 'float64'
+
+        and multiple columns' dtypes are combined according to the
+        `Array API's type promotion rules <https://data-apis.org/array-api/latest/API_specification/type_promotion.html>`_.
 
         Returns
         -------

spec/API_specification/examples/04_datatypes.py

@@ -18,7 +18,7 @@ def main(df_raw: SupportsDataFrameAPI) -> SupportsDataFrameAPI:
             if isinstance(df.col(col_name).dtype, pdx.Int64)
         ],
     )
-    arr = df.to_array(pdx.Int64())
+    arr = df.to_array()
     arr = some_array_function(arr)
     df = pdx.dataframe_from_2d_array(arr, names=["a", "b"])
     return df.dataframe