Add specification for explicitly casting an array to a specified dtype (#290)

* Add astype API and restrict asarray to type promotion rules

* Update copy

* Update copy

* Add support for a `copy` keyword

* Restrict `docutils` version

Author: kgryte

requirements.txt

@@ -3,3 +3,4 @@ sphinx-material==0.0.30
 myst-parser
 sphinx_markdown_tables
 sphinx_copybutton
+docutils<0.18

spec/API_specification/creation_functions.md

@@ -59,7 +59,7 @@ Convert the input to an array.
 
 -   **obj**: _Union\[ <array>, bool, int, float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_
 
-    -   Object to be converted to an array. Can be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting DLPack or the Python buffer protocol.
+    -   object to be converted to an array. May be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting DLPack or the Python buffer protocol.
 
     :::{tip}
     An object supporting DLPack has `__dlpack__` and `__dlpack_device__` methods.
@@ -68,21 +68,33 @@ Convert the input to an array.
 
 -   **dtype**: _Optional\[ <dtype> ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. If all input values are Python scalars, then if they're all `bool` the output dtype will be `bool`; if they're a mix of `bool`s and `int` the output dtype will be the default integer data type; if they contain `float`s the output dtype will be the default floating-point data type. Default: `None`.
+    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. If all input values are Python scalars, then
+
+        -   if all values are of type `bool`, the output data type must be `bool`.
+        -   if the values are a mixture of `bool`s and `int`, the output data type must be the default integer data type.
+        -   if one or more values are `float`s, the output data type must be the default floating-point data type.
+
+        Default: `None`.
+
+        ```{note}
+        If `dtype` is not `None`, then array conversions should obey {ref}`type-promotion` rules. Conversions not specified according to {ref}`type-promotion` rules may or may not be permitted by a conforming array library.
+
+        To perform an explicit cast, use {ref}`function-astype`.
+        ```
 
 -   **device**: _Optional\[ <device> ]_
 
     -   device on which to place the created array. If `device` is `None` and `x` is either an array or an object supporting DLPack, the output array device must be inferred from `x`. Default: `None`.
 
 -   **copy**: _Optional\[ bool ]_
 
-    -   Whether or not to make a copy of the input. If `True`, always copies. If `False`, never copies for input which supports DLPack or the buffer protocol, and raises `ValueError` in case that would be necessary. If `None`, reuses existing memory buffer if possible, copies otherwise. Default: `None`.
+    -   boolean indicating whether or not to copy the input. If `True`, the function must always copy. If `False`, the function must never copy for input which supports DLPack or the buffer protocol and must raise a `ValueError` in case a copy would be necessary. If `None`, the function must reuse existing memory buffer if possible and copy otherwise. Default: `None`.
 
 #### Returns
 
 -   **out**: _<array>_
 
-    -   An array containing the data from `obj`.
+    -   an array containing the data from `obj`.
 
 
 (function-empty)=

spec/API_specification/data_type_functions.md

@@ -7,6 +7,36 @@ A conforming implementation of the array API standard must provide and support t
 <!-- NOTE: please keep the constants in alphabetical order -->
 
 ## Objects in API
+
+(function-astype)=
+### astype(x, dtype, /, *, copy=True)
+
+Copies an array to a specified data type irrespective of {ref}`type-promotion` rules.
+
+```{note}
+Casting floating-point `NaN` and `infinity` values to integral data types is not specified and is implementation-dependent.
+```
+
+#### Parameters
+
+-   **x**: _&lt;array&gt;_
+
+    -   array to cast.
+    
+-   **dtype**: _&lt;dtype&gt;_
+
+    -   desired data type.
+    
+-   **copy**: _&lt;bool&gt;_
+
+    -   specifies whether to copy an array when the specified `dtype` matches the data type of the input array `x`. If `True`, a newly allocated array must always be returned. If `False` and the specified `dtype` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated must be returned. Default: `True`.
+    
+#### Returns
+
+-   **out**: _&lt;array&gt;_
+
+    -   an array having the specified data type. The returned array must have the same shape as `x`.
+
 (function-broadcast_arrays)=
 ### broadcast_arrays(*arrays)