Update API specification for creation and manipulation functions (#167)

rgommers · web-flow · commit e6d827afdbeb · 2021-04-27T20:40:33.000+02:00
* Update specification for arange Addresses comments in gh-85 and gh-107 * Update the specification for `full` and `full_like` Addresses comments in gh-85 and gh-107 * Update specification for `linspace` Addresses comments in gh-85 and gh-107 * Update specification for `empty`, `ones`, `zeros` Addresses comments in gh-85 and gh-107 * Update specification for `eye` This is useful/needed because `M` is not a descriptive name and that name does not match between different array libraries. * Update specification for `expand_dims`, `roll` and `reshape` Address comment in gh-85 * One more change to `eye`, more descriptive positional arguments * Address the default integer dtype issue for 32/64-bit Python Closes gh-151 * Update signature of `broadcast_to` Address a review comment; makes it consistent with other functions using `shape`.
diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md
@@ -12,7 +12,7 @@ A conforming implementation of the array API standard must provide and support t
 <!-- NOTE: please keep the functions in alphabetical order -->
 
 (function-arange)=
-### arange(start, /, *, stop=None, step=1, dtype=None, device=None)
+### arange(start, /, stop=None, step=1, *, dtype=None, device=None)
 
 Returns evenly spaced values within the half-open interval `[start, stop)` as a one-dimensional array.
 
@@ -33,11 +33,11 @@ This function cannot guarantee that the interval does not include the `stop` val
 
 -   **step**: _Union\[ int, float ]_
 
-    -   the distance between two adjacent elements (`out[i+1] - out[i]`). Default: `1`.
+    -   the distance between two adjacent elements (`out[i+1] - out[i]`). Must not be `0`; may be negative, this results in an empty array if `stop >= start`. Default: `1`.
 
 -   **dtype**: _Optional\[ &lt;dtype&gt; ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must 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 `start`, `stop` and `step`. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type `float`, then the output array dtype must be the default floating-point data type. Default: `None`.
 
 -   **device**: _Optional\[ &lt;device&gt; ]_
 
@@ -47,7 +47,7 @@ This function cannot guarantee that the interval does not include the `stop` val
 
 -   **out**: _&lt;array&gt;_
 
-    -   a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)`.
+    -   a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)` if `stop - start` and `step` have the same sign, and length 0 otherwise.
 
 
 (function-asarray)=
@@ -68,7 +68,7 @@ Convert the input to an array.
 
 -   **dtype**: _Optional\[ &lt;dtype&gt; ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. 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 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`.
 
 -   **device**: _Optional\[ &lt;device&gt; ]_
 
@@ -86,7 +86,7 @@ Convert the input to an array.
 
 
 (function-empty)=
-### empty(shape, /, *, dtype=None, device=None)
+### empty(shape, *, dtype=None, device=None)
 
 Returns an uninitialized array having a specified `shape`.
 
@@ -136,19 +136,19 @@ Returns an uninitialized array with the same `shape` as an input array `x`.
     -   an array having the same shape as `x` and containing uninitialized data.
 
 (function-eye)=
-### eye(N, /, *, M=None, k=0, dtype=None, device=None)
+### eye(n_rows, n_cols=None, /, *, k=0, dtype=None, device=None)
 
 Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewhere.
 
 #### Parameters
 
--   **N**: _int_
+-   **n_rows**: _int_
 
     -   number of rows in the output array.
 
--   **M**: _Optional\[ int ]_
+-   **n_cols**: _Optional\[ int ]_
 
-    -   number of columns in the output array. If `None`, the default number of columns in the output array is `N`. Default: `None`.
+    -   number of columns in the output array. If `None`, the default number of columns in the output array is equal to `n_rows`. Default: `None`.
 
 -   **k**: _Optional\[ int ]_
 
@@ -190,7 +190,7 @@ Returns a new array containing the data from another (array) object with a `__dl
         ```
 
 (function-full)=
-### full(shape, fill_value, /, *, dtype=None, device=None)
+### full(shape, fill_value, *, dtype=None, device=None)
 
 Returns a new array having a specified `shape` and filled with `fill_value`.
 
@@ -206,7 +206,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`.
 
 -   **dtype**: _Optional\[ &lt;dtype&gt; ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must 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 `fill_value`. If it's an `int`, the output array dtype must be the default integer dtype; if it's a `float`, then the output array dtype must be the default floating-point data type; if it's a `bool` then the output array must have boolean dtype. Default: `None`.
 
 -   **device**: _Optional\[ &lt;device&gt; ]_
 
@@ -219,7 +219,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`.
     -   an array where every element is equal to `fill_value`.
 
 (function-full_like)=
-### full_like(x, fill_value, /, *, dtype=None, device=None)
+### full_like(x, /, fill_value, *, dtype=None, device=None)
 
 Returns a new array filled with `fill_value` and having the same `shape` as an input array `x`.
 
@@ -235,7 +235,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i
 
 -   **dtype**: _Optional\[ &lt;dtype&gt; ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`.
+    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from `fill_value` (see {ref}`function-full`). Default: `None`.
 
 -   **device**: _Optional\[ &lt;device&gt; ]_
 
@@ -248,7 +248,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i
     -   an array having the same shape as `x` and where every element is equal to `fill_value`.
 
 (function-linspace)=
-### linspace(start, stop, num, /, *, dtype=None, device=None, endpoint=True)
+### linspace(start, stop, /, num, *, dtype=None, device=None, endpoint=True)
 
 Returns evenly spaced numbers over a specified interval.
 
@@ -321,7 +321,7 @@ Returns coordinate matrices from coordinate vectors.
         The returned arrays must have a numeric data type determined by {ref}`type-promotion`.
 
 (function-ones)=
-### ones(shape, /, *, dtype=None, device=None)
+### ones(shape, *, dtype=None, device=None)
 
 Returns a new array having a specified `shape` and filled with ones.
 
@@ -371,7 +371,7 @@ Returns a new array filled with ones and having the same `shape` as an input arr
     -   an array having the same shape as `x` and filled with ones.
 
 (function-zeros)=
-### zeros(shape, /, *, dtype=None, device=None)
+### zeros(shape, *, dtype=None, device=None)
 
 Returns a new array having a specified `shape` and filled with zeros.
 
diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md
@@ -25,7 +25,7 @@ Broadcasts one or more arrays against one another.
     -   a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array.
 
 (function-broadcast_to)=
-### broadcast_to(x, shape, /)
+### broadcast_to(x, /, shape)
 
 Broadcasts an array to a specified shape.
 
diff --git a/spec/API_specification/data_types.md b/spec/API_specification/data_types.md
@@ -6,10 +6,9 @@
 
 A conforming implementation of the array API standard must provide and support the following data types.
 
-A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`), as well as a default data type for an array index (either `int32` or `int64`).
+A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`), as well as a default integer data type (`int32` or `int64`). These default data types must be the same across platforms. The default integer data type may vary depending on whether Python is 32-bit or 64-bit.
 
 ```{note}
-
 The default floating-point and array index integer data types should be clearly defined in a conforming library's documentation.
 ```
 
diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md
@@ -39,7 +39,7 @@ Joins a sequence of arrays along an existing axis.
         ```
 
 (function-expand_dims)=
-### expand_dims(x, axis, /)
+### expand_dims(x, /, *, axis)
 
 Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by `axis`.
 
@@ -81,7 +81,7 @@ Reverses the order of elements in an array along the given axis. The shape of th
     -   an output array having the same data type and shape as `x` and whose elements, relative to `x`, are reordered.
 
 (function-reshape)=
-### reshape(x, shape, /)
+### reshape(x, /, shape)
 
 Reshapes an array without changing its data.
 
@@ -102,7 +102,7 @@ Reshapes an array without changing its data.
     -   an output array having the same data type, elements, and underlying element order as `x`.
 
 (function-roll)=
-### roll(x, shift, /, *, axis=None)
+### roll(x, /, shift, *, axis=None)
 
 Rolls array elements along a specified axis. Array elements that roll beyond the last position are re-introduced at the first position. Array elements that roll beyond the first position are re-introduced at the last position.
 
diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md
@@ -51,11 +51,11 @@ Returns the unique elements of an input array `x`.
 
         -   **indices**: _&lt;array&gt;_
 
-            -   an array containing the indices (first occurrences) of `x` that result in `unique`. The returned array must have the default array index data type.
+            -   an array containing the indices (first occurrences) of `x` that result in `unique`. The returned array must have the default integer data type.
 
         -   **inverse**: _&lt;array&gt;_
 
-            -   an array containing the indices of `unique` that reconstruct `x`. The returned array must have the default array index data type.
+            -   an array containing the indices of `unique` that reconstruct `x`. The returned array must have the default integer data type.
 
         -   **counts**: _&lt;array&gt;_
 
