diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 90fe0dfda..71491fe24 100644 --- 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 (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\[ <dtype> ]_ - - 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\[ <device> ]_ @@ -47,7 +47,7 @@ This function cannot guarantee that the interval does not include the `stop` val - **out**: _<array>_ - - 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\[ <dtype> ]_ - - 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\[ <device> ]_ @@ -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\[ <dtype> ]_ - - 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\[ <device> ]_ @@ -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\[ <dtype> ]_ - - 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\[ <device> ]_ @@ -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 index 9f517dcf5..0b76b386b 100644 --- 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 index b1c83b4d5..3788d8494 100644 --- 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 index 29fca5a29..edb116139 100644 --- 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 index 73d8338cc..c8d04cffa 100644 --- 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**: _<array>_ - - 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**: _<array>_ - - 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**: _<array>_