From ed2b114265d455ca1fe18cb9696c734d14c88e47 Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 22:16:23 -0700 Subject: [PATCH 1/3] docs: move notes below the fold and highlight RFC 2119 keywords Ref: https://github.com/data-apis/array-api/issues/397 --- .../_draft/manipulation_functions.py | 121 +++++++++--------- 1 file changed, 62 insertions(+), 59 deletions(-) diff --git a/src/array_api_stubs/_draft/manipulation_functions.py b/src/array_api_stubs/_draft/manipulation_functions.py index dd8d4cd69..5cc26933a 100644 --- a/src/array_api_stubs/_draft/manipulation_functions.py +++ b/src/array_api_stubs/_draft/manipulation_functions.py @@ -31,7 +31,7 @@ def broadcast_arrays(*arrays: array) -> List[array]: Returns ------- out: List[array] - a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array. + a list of broadcasted arrays. Each array **must** have the same shape. Each array **must** have the same dtype as its corresponding input array. """ @@ -42,14 +42,14 @@ def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: Parameters ---------- x: array - array to broadcast. Must be capable of being broadcast to the specified ``shape`` (see :ref:`broadcasting`). If the array is incompatible with the specified shape, the function must raise an exception. + array to broadcast. **Must** be capable of being broadcast to the specified ``shape`` (see :ref:`broadcasting`). If the array is incompatible with the specified shape, the function **must** raise an exception. shape: Tuple[int, ...] array shape. Returns ------- out: array - an array having the specified shape. Must have the same data type as ``x``. + an array having the specified shape. **Must** have the same data type as ``x``. .. versionchanged:: 2024.12 Clarified broadcast behavior. @@ -65,58 +65,58 @@ def concat( Parameters ---------- arrays: Union[Tuple[array, ...], List[array]] - input arrays to join. The arrays must have the same shape, except in the dimension specified by ``axis``. + input arrays to join. The arrays **must** have the same shape, except in the dimension specified by ``axis``. axis: Optional[int] - axis along which the arrays will be joined. If ``axis`` is ``None``, arrays must be flattened before concatenation. If ``axis`` is negative, the function must determine the axis along which to join by counting from the last dimension. Default: ``0``. + axis along which to join the arrays. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in each array. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. If ``axis`` is ``None``, arrays **must** be flattened before concatenation. Default: ``0``. Returns ------- out: array - an output array containing the concatenated values. If the input arrays have different data types, normal :ref:`type-promotion` must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. + an output array containing the concatenated values. If the input arrays have different data types, normal :ref:`type-promotion` **must** apply. If the input arrays have the same data type, the output array **must** have the same data type as the input arrays. .. note:: - This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified. + This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified and thus implementation-defined. """ def expand_dims(x: array, /, *, axis: int = 0) -> array: """ - Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by ``axis``. + Expands the shape of an array by inserting a new axis of size one at the position specified by ``axis``. Parameters ---------- x: array input array. axis: int - axis position (zero-based). If ``x`` has rank (i.e, number of dimensions) ``N``, a valid ``axis`` must reside on the closed-interval ``[-N-1, N]``. If provided a negative ``axis``, the axis position at which to insert a singleton dimension must be computed as ``N + axis + 1``. Hence, if provided ``-1``, the resolved axis position must be ``N`` (i.e., a singleton dimension must be appended to the input array ``x``). If provided ``-N-1``, the resolved axis position must be ``0`` (i.e., a singleton dimension must be prepended to the input array ``x``). + axis position (zero-based). A valid ``axis`` **must** reside on the closed-interval ``[-N-1, N]``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the axis position at which to insert a singleton dimension **must** be computed as ``N + axis + 1``. Hence, if provided ``-1``, the resolved axis position **must** be ``N`` (i.e., a singleton dimension **must** be appended to the input array ``x``). If provided ``-N-1``, the resolved axis position **must** be ``0`` (i.e., a singleton dimension **must** be prepended to the input array ``x``). If provided an invalid axis, the function **must** raise an exception. Default: ``0``. Returns ------- out: array - an expanded output array having the same data type as ``x``. + an expanded output array. **Must** have the same data type as ``x``. Raises ------ IndexError - If provided an invalid ``axis`` position, an ``IndexError`` should be raised. + If provided an invalid ``axis``, an ``IndexError`` **should** be raised. """ def flip(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> array: """ - Reverses the order of elements in an array along the given axis. The shape of the array must be preserved. + Reverses the order of elements in an array along the given axis. Parameters ---------- x: array input array. axis: Optional[Union[int, Tuple[int, ...]]] - axis (or axes) along which to flip. If ``axis`` is ``None``, the function must flip all input array axes. If ``axis`` is negative, the function must count from the last dimension. If provided more than one axis, the function must flip only the specified axes. Default: ``None``. + axis (or axes) along which to reverse elements. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. If ``axis`` is ``None``, the function **must** flip all input array axes. If provided more than one axis, the function **must** flip only the specified axes. Default: ``None``. Returns ------- out: array - an output array having the same data type and shape as ``x`` and whose elements, relative to ``x``, are reordered. + an output array. The returned array **must** have the same data type and shape as ``x`` and whose elements, relative to ``x``, are reordered. """ @@ -127,21 +127,21 @@ def moveaxis( /, ) -> array: """ - Moves array axes (dimensions) to new positions, while leaving other axes in their original positions. + Moves array axes to new positions, while leaving other axes in their original positions. Parameters ---------- x: array input array. source: Union[int, Tuple[int, ...]] - Axes to move. Provided axes must be unique. If ``x`` has rank (i.e, number of dimensions) ``N``, a valid axis must reside on the half-open interval ``[-N, N)``. + axis (or axes) to move. Provided source axes **must** be unique. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. destination: Union[int, Tuple[int, ...]] - indices defining the desired positions for each respective ``source`` axis index. Provided indices must be unique. If ``x`` has rank (i.e, number of dimensions) ``N``, a valid axis must reside on the half-open interval ``[-N, N)``. + axis (or axes) defining the desired position(s) for each respective ``source`` axis index. Provided destination axes **must** be unique. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. Returns ------- out: array - an array containing reordered axes. The returned array must have the same data type as ``x``. + an array containing reordered axes. The returned array **must** have the same data type as ``x``. Notes ----- @@ -152,19 +152,19 @@ def moveaxis( def permute_dims(x: array, /, axes: Tuple[int, ...]) -> array: """ - Permutes the axes (dimensions) of an array ``x``. + Permutes the axes of an array ``x``. Parameters ---------- x: array input array. axes: Tuple[int, ...] - tuple containing a permutation of ``(0, 1, ..., N-1)`` where ``N`` is the number of axes (dimensions) of ``x``. + tuple containing a permutation of ``(0, 1, ..., N-1)`` where ``N`` is the number of axes in ``x``. Returns ------- out: array - an array containing the axes permutation. The returned array must have the same data type as ``x``. + an array containing the axes permutation. The returned array **must** have the same data type as ``x``. """ @@ -181,7 +181,7 @@ def repeat( .. admonition:: Data-dependent output shape :class: important - When ``repeats`` is an array, the shape of the output array for this function depends on the data values in the ``repeats`` array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing the values in ``repeats``. Accordingly, such libraries may choose to omit support for ``repeats`` arrays; however, conforming implementations must support providing a literal ``int``. See :ref:`data-dependent-output-shapes` section for more details. + When ``repeats`` is an array, the shape of the output array for this function depends on the data values in the ``repeats`` array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) can find this function difficult to implement without knowing the values in ``repeats``. Accordingly, such libraries **may** choose to omit support for ``repeats`` arrays; however, conforming implementations **must** support providing a literal ``int``. See :ref:`data-dependent-output-shapes` section for more details. Parameters ---------- @@ -190,32 +190,31 @@ def repeat( repeats: Union[int, array] the number of repetitions for each element. - If ``axis`` is ``None``, let ``N = prod(x.shape)`` and + If ``axis`` is ``None``, let ``M = prod(x.shape)`` and - - if ``repeats`` is an array, ``repeats`` must be broadcast compatible with the shape ``(N,)`` (i.e., be a one-dimensional array having shape ``(1,)`` or ``(N,)``). - - if ``repeats`` is an integer, ``repeats`` must be broadcasted to the shape `(N,)`. + - if ``repeats`` is an array, ``repeats`` **must** be broadcast compatible with the shape ``(M,)`` (i.e., be a one-dimensional array having shape ``(1,)`` or ``(M,)``). + - if ``repeats`` is an integer, ``repeats`` **must** be broadcasted to the shape `(M,)`. - If ``axis`` is not ``None``, let ``M = x.shape[axis]`` and + If ``axis`` is not ``None``, let ``S = x.shape[axis]`` and - - if ``repeats`` is an array, ``repeats`` must be broadcast compatible with the shape ``(M,)`` (i.e., be a one-dimensional array having shape ``(1,)`` or ``(M,)``). - - if ``repeats`` is an integer, ``repeats`` must be broadcasted to the shape ``(M,)``. + - if ``repeats`` is an array, ``repeats`` **must** be broadcast compatible with the shape ``(S,)`` (i.e., be a one-dimensional array having shape ``(1,)`` or ``(S,)``). + - if ``repeats`` is an integer, ``repeats`` **must** be broadcasted to the shape ``(S,)``. - If ``repeats`` is an array, the array must have an integer data type. - - .. note:: - For specification-conforming array libraries supporting hardware acceleration, providing an array for ``repeats`` may cause device synchronization due to an unknown output shape. For those array libraries where synchronization concerns are applicable, conforming array libraries are advised to include a warning in their documentation regarding potential performance degradation when ``repeats`` is an array. + If ``repeats`` is an array, the array **must** have an integer data type. axis: Optional[int] - the axis (dimension) along which to repeat elements. If ``axis`` is `None`, the function must flatten the input array ``x`` and then repeat elements of the flattened input array and return the result as a one-dimensional output array. A flattened input array must be flattened in row-major, C-style order. Default: ``None``. + the axis along which to repeat elements. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. If ``axis`` is `None`, the function **must** flatten the input array ``x`` and then repeat elements of the flattened input array and return the result as a one-dimensional output array. A flattened input array **must** be flattened in row-major, C-style order. Default: ``None``. Returns ------- out: array - an output array containing repeated elements. The returned array must have the same data type as ``x``. If ``axis`` is ``None``, the returned array must be a one-dimensional array; otherwise, the returned array must have the same shape as ``x``, except for the axis (dimension) along which elements were repeated. + an output array containing repeated elements. The returned array **must** have the same data type as ``x``. If ``axis`` is ``None``, the returned array **must** be a one-dimensional array; otherwise, the returned array **must** have the same shape as ``x``, except for the axis along which elements were repeated. Notes ----- + - For specification-conforming array libraries supporting hardware acceleration, providing an array for ``repeats`` can cause device synchronization due to an unknown output shape. For those array libraries where synchronization concerns are applicable, conforming array libraries **should** include a warning in their documentation regarding potential performance degradation when ``repeats`` is an array. + .. versionadded:: 2023.12 """ @@ -231,20 +230,19 @@ def reshape( x: array input array to reshape. shape: Tuple[int, ...] - a new shape compatible with the original shape. One shape dimension is allowed to be ``-1``. When a shape dimension is ``-1``, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions. + a new shape compatible with the original shape. Only one shape dimension **may** be allowed to be ``-1``. When a shape dimension is ``-1``, the corresponding output array shape dimension **must** be inferred from the length of the array and the remaining dimensions. copy: Optional[bool] - whether or not to copy the input array. If ``True``, the function must always copy (see :ref:`copy-keyword-argument`). If ``False``, the function must never copy. If ``None``, the function must avoid copying, if possible, and may copy otherwise. Default: ``None``. + whether or not to copy the input array. If ``True``, the function **must** always copy (see :ref:`copy-keyword-argument`). If ``False``, the function **must** never copy. If ``None``, the function **must** avoid copying, if possible, and **may** copy otherwise. Default: ``None``. Returns ------- out: array - an output array having the same data type and elements as ``x``. + an output array. The returned array **must** have the same data type and the same elements as ``x``. Raises ------ ValueError - If ``copy=False`` and a copy would be necessary, a ``ValueError`` - should be raised. + If ``copy=False`` and a copy would be necessary, a ``ValueError`` **should** be raised. """ @@ -256,45 +254,48 @@ def roll( axis: Optional[Union[int, Tuple[int, ...]]] = None, ) -> array: """ - 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. + 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. Parameters ---------- x: array input array. shift: Union[int, Tuple[int, ...]] - number of places by which the elements are shifted. If ``shift`` is a tuple, then ``axis`` must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element in ``shift``. If ``shift`` is an ``int`` and ``axis`` a tuple, then the same ``shift`` must be used for all specified axes. If a shift is positive, then array elements must be shifted positively (toward larger indices) along the dimension of ``axis``. If a shift is negative, then array elements must be shifted negatively (toward smaller indices) along the dimension of ``axis``. + number of places by which the elements are shifted. If ``shift`` is a tuple, then ``axis`` **must** be a tuple of the same size, and each of the given axes **must** be shifted by the corresponding element in ``shift``. If ``shift`` is an ``int`` and ``axis`` a tuple, then the same ``shift`` **must** be used for all specified axes. If a shift is positive, then array elements **must** be shifted positively (toward larger indices) along the dimension of ``axis``. If a shift is negative, then array elements **must** be shifted negatively (toward smaller indices) along the dimension of ``axis``. axis: Optional[Union[int, Tuple[int, ...]]] - axis (or axes) along which elements to shift. If ``axis`` is ``None``, the array must be flattened, shifted, and then restored to its original shape. Default: ``None``. + axis (or axes) along which elements to shift. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. If ``axis`` is ``None``, the array **must** be flattened, shifted, and then restored to its original shape. Default: ``None``. Returns ------- out: array - an output array having the same data type as ``x`` and whose elements, relative to ``x``, are shifted. + an output array. The returned array **must** have the same data type as ``x`` and the same elements as ``x``, but which are shifted relative to ``x``. """ def squeeze(x: array, /, axis: Union[int, Tuple[int, ...]]) -> array: """ - Removes singleton dimensions (axes) from ``x``. + Removes singleton axes from ``x``. Parameters ---------- x: array input array. axis: Union[int, Tuple[int, ...]] - axis (or axes) to squeeze. + axis (or axes) to squeeze. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. Returns ------- out: array - an output array having the same data type and elements as ``x``. + an output array. The returned array **must** have the same data type and the same elements as ``x``. Raises ------ ValueError - If a specified axis has a size greater than one (i.e., it is not a - singleton dimension), a ``ValueError`` should be raised. + If a specified axis has a size greater than one (i.e., it is not a singleton axis), a ``ValueError`` **should** be raised. """ @@ -305,17 +306,19 @@ def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) -> Parameters ---------- arrays: Union[Tuple[array, ...], List[array]] - input arrays to join. Each array must have the same shape. + input arrays to join. Each array **must** have the same shape. axis: int - axis along which the arrays will be joined. Providing an ``axis`` specifies the index of the new axis in the dimensions of the result. For example, if ``axis`` is ``0``, the new axis will be the first dimension and the output array will have shape ``(N, A, B, C)``; if ``axis`` is ``1``, the new axis will be the second dimension and the output array will have shape ``(A, N, B, C)``; and, if ``axis`` is ``-1``, the new axis will be the last dimension and the output array will have shape ``(A, B, C, N)``. A valid ``axis`` must be on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If provided an ``axis`` outside of the required interval, the function must raise an exception. Default: ``0``. + axis along which to join the arrays. Providing an ``axis`` specifies the index of the new axis in the shape of the result. For example, if ``axis`` is ``0``, the new axis **must** be the first dimension and the output array **must** have shape ``(N, A, B, C)``; if ``axis`` is ``1``, the new axis will be the second dimension and the output array will have shape ``(A, N, B, C)``; and, if ``axis`` is ``-1``, the new axis will be the last dimension and the output array will have shape ``(A, B, C, N)``. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. Default: ``0``. Returns ------- out: array - an output array having rank ``N+1``, where ``N`` is the rank (number of dimensions) of ``x``. If the input arrays have different data types, normal :ref:`type-promotion` must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. + an output array. The returned array **must** have ``N+1`` axes, where ``N`` is the number of axes in ``x``. If the input arrays have different data types, normal :ref:`type-promotion` **must** apply. If the input arrays have the same data type, the output array **must** have the same data type as the input arrays. - .. note:: - This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified. + Notes + ----- + + - This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified and thus implementation-defined. """ @@ -328,18 +331,18 @@ def tile(x: array, repetitions: Tuple[int, ...], /) -> array: x: array input array. repetitions: Tuple[int, ...] - number of repetitions along each axis (dimension). + number of repetitions along each axis. Let ``N = len(x.shape)`` and ``M = len(repetitions)``. - If ``N > M``, the function must prepend ones until all axes (dimensions) are specified (e.g., if ``x`` has shape ``(8,6,4,2)`` and ``repetitions`` is the tuple ``(3,3)``, then ``repetitions`` must be treated as ``(1,1,3,3)``). + If ``N > M``, the function **must** prepend ones until all axes are specified (e.g., if ``x`` has shape ``(8,6,4,2)`` and ``repetitions`` is the tuple ``(3,3)``, then ``repetitions`` **must** be treated as ``(1,1,3,3)``). - If ``N < M``, the function must prepend singleton axes (dimensions) to ``x`` until ``x`` has as many axes (dimensions) as ``repetitions`` specifies (e.g., if ``x`` has shape ``(4,2)`` and ``repetitions`` is the tuple ``(3,3,3,3)``, then ``x`` must be treated as if it has shape ``(1,1,4,2)``). + If ``N < M``, the function **must** prepend singleton axes to ``x`` until ``x`` has as many axes as ``repetitions`` specifies (e.g., if ``x`` has shape ``(4,2)`` and ``repetitions`` is the tuple ``(3,3,3,3)``, then ``x`` **must** be treated as if it has shape ``(1,1,4,2)``). Returns ------- out: array - a tiled output array. The returned array must have the same data type as ``x`` and must have a rank (i.e., number of dimensions) equal to ``max(N, M)``. If ``S`` is the shape of the tiled array after prepending singleton dimensions (if necessary) and ``r`` is the tuple of repetitions after prepending ones (if necessary), then the number of elements along each axis (dimension) must satisfy ``S[i]*r[i]``, where ``i`` refers to the ``i`` th axis (dimension). + a tiled output array. The returned array **must** have the same data type as ``x`` and **must** have a number of axes equal to ``max(N, M)``. If ``S`` is the shape of the tiled array after prepending singleton dimensions (if necessary) and ``r`` is the tuple of repetitions after prepending ones (if necessary), then the number of elements along each axis **must** satisfy ``S[i]*r[i]``, where ``i`` refers to the ``i`` th axis. Notes ----- @@ -357,12 +360,12 @@ def unstack(x: array, /, *, axis: int = 0) -> Tuple[array, ...]: x: array input array. axis: int - axis along which the array will be split. A valid ``axis`` must be on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If provided an ``axis`` outside of the required interval, the function must raise an exception. Default: ``0``. + axis along which to split an array. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. Default: ``0``. Returns ------- out: Tuple[array, ...] - tuple of slices along the given dimension. All the arrays have the same shape. + tuple of slices along the given dimension. Each returned array **must** have the same shape. Notes ----- From e9f5110101b11c16be065581cf5519bdd34b5ae5 Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 22:21:18 -0700 Subject: [PATCH 2/3] docs: update copy --- src/array_api_stubs/_draft/manipulation_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/array_api_stubs/_draft/manipulation_functions.py b/src/array_api_stubs/_draft/manipulation_functions.py index 5cc26933a..8d67b5ff4 100644 --- a/src/array_api_stubs/_draft/manipulation_functions.py +++ b/src/array_api_stubs/_draft/manipulation_functions.py @@ -116,7 +116,7 @@ def flip(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> Returns ------- out: array - an output array. The returned array **must** have the same data type and shape as ``x`` and whose elements, relative to ``x``, are reordered. + an output array. The returned array **must** have the same data type and shape as ``x``. The returned array must have the same elements as ``x``, but which are reordered relative to ``x``. """ @@ -272,7 +272,7 @@ def roll( Returns ------- out: array - an output array. The returned array **must** have the same data type as ``x`` and the same elements as ``x``, but which are shifted relative to ``x``. + an output array. The returned array **must** have the same data type as ``x``. The returned array **must** have the same elements as ``x``, but which are shifted relative to ``x``. """ From 20d541cb00cf078b3a02f9afb84190153a7cebfd Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 22:22:42 -0700 Subject: [PATCH 3/3] docs: update copy --- src/array_api_stubs/_draft/manipulation_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/manipulation_functions.py b/src/array_api_stubs/_draft/manipulation_functions.py index 8d67b5ff4..3ea0975e7 100644 --- a/src/array_api_stubs/_draft/manipulation_functions.py +++ b/src/array_api_stubs/_draft/manipulation_functions.py @@ -230,7 +230,7 @@ def reshape( x: array input array to reshape. shape: Tuple[int, ...] - a new shape compatible with the original shape. Only one shape dimension **may** be allowed to be ``-1``. When a shape dimension is ``-1``, the corresponding output array shape dimension **must** be inferred from the length of the array and the remaining dimensions. + a new shape compatible with the original shape. Only one shape dimension **must** be allowed to be ``-1``. When a shape dimension is ``-1``, the corresponding output array shape dimension **must** be inferred from the length of the array and the remaining dimensions. copy: Optional[bool] whether or not to copy the input array. If ``True``, the function **must** always copy (see :ref:`copy-keyword-argument`). If ``False``, the function **must** never copy. If ``None``, the function **must** avoid copying, if possible, and **may** copy otherwise. Default: ``None``.