From 30a317fac0036b90700109b2eb0b82569072fb8c Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Thu, 19 Aug 2021 16:50:42 -0500 Subject: [PATCH] Some improvements to type hints (#230) * Fix alphabetical function ordering in the linear algebra extension * Update some type hints in the spec These come from comments on the NumPy pull request https://github.com/numpy/numpy/pull/18585. * Clarify that the where() result type is only based on the last two arguments * Use Literal[] for the qr() mode argument type hint * Add bool and int to the asarray type hints * Fix a typo in the __setitem__ annotations --- spec/API_specification/array_object.md | 6 +++--- spec/API_specification/creation_functions.md | 2 +- spec/API_specification/manipulation_functions.md | 4 ++-- spec/API_specification/searching_functions.md | 6 +++--- spec/extensions/linear_algebra_functions.md | 14 +++++++------- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 93e806de3..dcf78228b 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -780,7 +780,7 @@ The `matmul` function must implement the same semantics as the built-in `@` oper - **self**: _<array>_ - - array instance. Should have a numeric data type. Must have at least one dimension. If `self` is one-dimensional having shape `(M)` and `other` has more than one dimension, `self` must be promoted to a two-dimensional array by prepending `1` to its dimensions (i.e., must have shape `(1, M)`). After matrix multiplication, the prepended dimensions in the returned array must be removed. If `self` has more than one dimension (including after vector-to-matrix promotion), `self` must be compatible with `other` (see {ref}`broadcasting`). If `self` has shape `(..., M, K)`, the innermost two dimensions form matrices on which to perform matrix multiplication. + - array instance. Should have a numeric data type. Must have at least one dimension. If `self` is one-dimensional having shape `(M)` and `other` has more than one dimension, `self` must be promoted to a two-dimensional array by prepending `1` to its dimensions (i.e., must have shape `(1, M)`). After matrix multiplication, the prepended dimensions in the returned array must be removed. If `self` has more than one dimension (including after vector-to-matrix promotion), `self` must be compatible with `other` (see {ref}`broadcasting`). If `self` has shape `(..., M, K)`, the innermost two dimensions form matrices on which to perform matrix multiplication. - **other**: _<array>_ @@ -809,7 +809,7 @@ The `matmul` function must implement the same semantics as the built-in `@` oper - if either `self` or `other` is a zero-dimensional array. - if `self` is a one-dimensional array having shape `(N)`, `other` is a one-dimensional array having shape `(M)`, and `N != M`. -- if `self` is an array having shape `(..., M, K)`, `other` is an array having shape `(..., L, N)`, and `K != L`. +- if `self` is an array having shape `(..., M, K)`, `other` is an array having shape `(..., L, N)`, and `K != L`. (method-__mod__)= ### \_\_mod\_\_(self, other, /) @@ -1066,7 +1066,7 @@ Sets `self[key]` to `value`. #### Parameters -- **self**: _<array;>_ +- **self**: _<array>_ - array instance. diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 8b1bec16e..da7b250b4 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -57,7 +57,7 @@ Convert the input to an array. #### Parameters -- **obj**: _Union\[ float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_ +- **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. diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index ae8499370..e1e0e98ea 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -19,7 +19,7 @@ Joins a sequence of arrays along an existing axis. #### Parameters -- **arrays**: _Tuple\[ <array>, ... ]_ +- **arrays**: _Union\[Tuple\[ <array>, ... ], List\[ <array> ] ]_ - input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`. @@ -154,7 +154,7 @@ Joins a sequence of arrays along a new axis. #### Parameters -- **arrays**: _Tuple\[ <array>, ... ]_ +- **arrays**: _Union\[Tuple\[ <array>, ... ], List\[ <array> ] ]_ - input arrays to join. Each array must have the same shape. diff --git a/spec/API_specification/searching_functions.md b/spec/API_specification/searching_functions.md index 3ad2ae8bb..f0311b8b7 100644 --- a/spec/API_specification/searching_functions.md +++ b/spec/API_specification/searching_functions.md @@ -27,7 +27,7 @@ Returns the indices of the maximum values along a specified axis. When the maxim - input array. -- **axis**: _int_ +- **axis**: _Optional\[ int ]_ - axis along which to search. If `None`, the function must return the index of the maximum value of the flattened array. Default: `None`. @@ -52,7 +52,7 @@ Returns the indices of the minimum values along a specified axis. When the minim - input array. -- **axis**: _int_ +- **axis**: _Optional\[ int ]_ - axis along which to search. If `None`, the function must return the index of the minimum value of the flattened array. Default: `None`. @@ -112,4 +112,4 @@ Returns elements chosen from `x1` or `x2` depending on `condition`. - **out**: _<array>_ - - an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. The returned array must have a data type determined by {ref}`type-promotion` rules. + - an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. The returned array must have a data type determined by {ref}`type-promotion` rules with the arrays `x1` and `x2`. diff --git a/spec/extensions/linear_algebra_functions.md b/spec/extensions/linear_algebra_functions.md index 3d51dca0d..b2f59082b 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -465,7 +465,7 @@ Computes the qr factorization of a matrix (or a stack of matrices), where `q` is - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type. -- **mode**: _str_ +- **mode**: _Literal\[ 'reduced', 'complete' ]_ - factorization mode. Should be one of the following modes: @@ -552,7 +552,7 @@ Computes the singular value decomposition `A = USVh` of a matrix (or a stack of #### Returns -- **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ +- **out**: _Tuple\[ <array>, <array>, <array> ]_ - a namedtuple `(u, s, vh)` whose @@ -562,11 +562,6 @@ Computes the singular value decomposition `A = USVh` of a matrix (or a stack of Each returned array must have the same floating-point data type as `x`. -(function-linalg-tensordot)= -### linalg.tensordot(x1, x2, /, *, axes=2) - -Alias for {ref}`function-tensordot`. - (function-linalg-svdvals)= ### linalg.svdvals(x, /) @@ -584,6 +579,11 @@ Computes the singular values of a matrix (or a stack of matrices) `x`. - an array with shape `(..., K)` that contains the vector(s) of singular values of length `K`. For each vector, the singular values must be sorted in descending order by magnitude, such that `s[..., 0]` is the largest value, `s[..., 1]` is the second largest value, et cetera. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`. The returned array must have the same floating-point data type as `x`. +(function-linalg-tensordot)= +### linalg.tensordot(x1, x2, /, *, axes=2) + +Alias for {ref}`function-tensordot`. + (function-linalg-trace)= ### linalg.trace(x, /, *, offset=0)