Skip to content

Commit cb5e528

Browse files
committed
Make axis keyword to squeeze() positional
As suggested by @shoyer in data-apis#97 (comment) This makes it possible to predict resulting rank of output array, which is otherwise undetermined (see discussion in data-apisgh-97). Using squeeze without specifying the axis in library code often results in unintuitive behaviour. For the common use case of extracting a scalar from a size-1 2-D array, this gets a little more verbose (e.g. `np.squeeze(np.array([[1]]), axis=(0, 1))`), but that's probably a price worth paying for the extra clarity. Also changes specified behaviour for a given axis not having size 1 to raising a `ValueError`, which is what NumPy does. This wasn't considered before, and the current description seems simply incorrect. Finally, this makes `squeeze` the exact inverse of `expand_dims`, which is probably a good thing.
1 parent 0015496 commit cb5e528

File tree

1 file changed

+3
-3
lines changed

1 file changed

+3
-3
lines changed

spec/API_specification/manipulation_functions.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ Rolls array elements along a specified axis. Array elements that roll beyond the
127127
- an output array having the same data type as `x` and whose elements, relative to `x`, are shifted.
128128
129129
(function-squeeze)=
130-
### squeeze(x, /, *, axis=None)
130+
### squeeze(x, /, axis)
131131
132132
Removes singleton dimensions (axes) from `x`.
133133
@@ -137,9 +137,9 @@ Removes singleton dimensions (axes) from `x`.
137137
138138
- input array.
139139
140-
- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_
140+
- **axis**: _Union\[ int, Tuple\[ int, ... ] ]_
141141
142-
- axis (or axes) to squeeze. If provided, only the specified axes must be squeezed. If `axis` is `None`, all singleton dimensions (axes) must be removed. If a specified axis has a size greater than one, the specified axis must be left unchanged. Default: `None`.
142+
- axis (or axes) to squeeze. If a specified axis has a size greater than one, a `ValueError` must be raised.
143143
144144
#### Returns
145145

0 commit comments

Comments
 (0)