From cc94c381bc3a3f98b90eeb06e7aefd389bb41871 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 23 Feb 2021 14:31:56 -0700 Subject: [PATCH 1/9] Small formatting fixes to make the spec parsable by the test suite scripts --- spec/API_specification/array_object.md | 4 ++-- spec/API_specification/data_type_functions.md | 10 +++++----- spec/API_specification/elementwise_functions.md | 4 ++-- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 66418395e..f699afea6 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -396,7 +396,7 @@ Converts a zero-dimensional boolean array to a Python `bool` object. (method-__dlpack__)= -### \_\_dlpack\_\_(/, *, stream=None) +### \_\_dlpack\_\_(*, stream=None) Exports the array as a DLPack capsule, for consumption by {ref}`function-from_dlpack`. @@ -562,7 +562,7 @@ Returns `x[key]`. #### Parameters -- **x**: _<array;>_ +- **x**: _<array>_ - array instance. diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 18269d2f1..f88a00b3f 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -8,7 +8,7 @@ A conforming implementation of the array API standard must provide and support t ## Objects in API -(finfo)= +(function-finfo)= ### finfo(type, /) Machine limits for floating-point data types. @@ -21,7 +21,7 @@ Machine limits for floating-point data types. #### Returns -- **out**: _<class>_ +- **out**: _<ffinfo>_ - an object having the following attributes: @@ -34,7 +34,7 @@ Machine limits for floating-point data types. - **min**: _float_ - smallest representable number. -(iinfo)= +(function-iinfo)= ### iinfo(type, /) Machine limits for integer data types. @@ -47,7 +47,7 @@ Machine limits for integer data types. #### Returns -- **out**: _<class>_ +- **out**: _<iinfo>_ - a class with that encapsules the following attributes: @@ -70,7 +70,7 @@ If provided mixed dtypes (e.g., integer and floating-point), the returned dtype #### Parameters -- **arrays_and_dtypes**: _Sequence\[ Union\[ <array>, <dtype> \] \];_ +- **arrays_and_dtypes**: _Sequence\[ Union\[ <array>, <dtype> \] \]_ - input arrays and dtypes. diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md index b0fe11c10..3dcf0dcf4 100644 --- a/spec/API_specification/elementwise_functions.md +++ b/spec/API_specification/elementwise_functions.md @@ -939,8 +939,8 @@ each element `x1_i` of the input array `x1` with the respective element `x2_i` o For floating-point operands, -- If `x1_i` or `x2_i` is `NaN`, the result is `NaN`. -- If `x1_i` or `x2_i` is `+infinity`, the result is `+infinity`. +- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. +- If either `x1_i` or `x2_i` is `+infinity`, the result is `+infinity`. #### Parameters From b028deb2353cf990f87cd6fde2b64ca37ac2f14c Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 23 Feb 2021 15:55:51 -0700 Subject: [PATCH 2/9] More formatting fixes --- spec/API_specification/data_type_functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index f88a00b3f..8e98d7465 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -15,13 +15,13 @@ Machine limits for floating-point data types. #### Parameters -- **type**: _Union\[ <dtype>, <array> ]_ +- **type**: _Union\[ <dtype>, <array> ]_ - the kind of floating-point data-type about which to get information. #### Returns -- **out**: _<ffinfo>_ +- **out**: _<finfo>_ - an object having the following attributes: @@ -41,7 +41,7 @@ Machine limits for integer data types. #### Parameters -- **type**: _Union\[ <dtype>, <array> ]_ +- **type**: _Union\[ <dtype>, <array> ]_ - the kind of integer data-type about which to get information. From 6b5f774d3ef8f792b7ce774a8213c87c6dd17465 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 23 Feb 2021 16:52:05 -0700 Subject: [PATCH 3/9] Fix in-place and reflected operator consistency __div__ is a relic from Python 2. It no longer does anything in Python 3. The reflected operators were missing __rmatmul__. Now they completely match the in-place operators. --- spec/API_specification/array_object.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index f699afea6..7dde76366 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -142,7 +142,7 @@ an array object supporting the following in-place Python operators: - `+=`. May be implemented via `__iadd__`. - `-=`. May be implemented via `__isub__`. - `*=`. May be implemented via `__imul__`. -- `/=`. May be implemented via `__idiv__`. +- `/=`. May be implemented via `__itruediv__`. - `//=`. May be implemented via `__ifloordiv__`. - `**=`. May be implemented via `__ipow__`. - `@=`. May be implemented via `__imatmul__`. @@ -166,10 +166,10 @@ an array object supporting the following reflected operators: - `__radd__` - `__rsub__` - `__rmul__` -- `__rdiv__` -- `__rfloordiv__` - `__rtruediv__` +- `__rfloordiv__` - `__rpow__` +- `__rmatmul__` - `__rmod__` - `__rand__` - `__ror__` From d11c21ea10d9b0c74a88175d4c3932433adbaae8 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 23 Feb 2021 17:36:36 -0700 Subject: [PATCH 4/9] Add self arguments for __dlpack__ and __dlpack_device__ --- spec/API_specification/array_object.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 7dde76366..eb50443d0 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -396,12 +396,16 @@ Converts a zero-dimensional boolean array to a Python `bool` object. (method-__dlpack__)= -### \_\_dlpack\_\_(*, stream=None) +### \_\_dlpack\_\_(x, *, stream=None) Exports the array as a DLPack capsule, for consumption by {ref}`function-from_dlpack`. #### Parameters +- **x**: _<array>_ + + - array instance. + - **stream**: _Optional\[int\]_ - An optional pointer to a stream, as a Python integer, provided by the consumer that the producer will use to make the array safe to operate on. The pointer is a positive integer. `-1` is a special value that may be used by the consumer to signal "producer must not do any synchronization". Device-specific notes: @@ -439,10 +443,16 @@ Exports the array as a DLPack capsule, for consumption by {ref}`function-from_dl (method-__dlpack_device__)= -### \_\_dlpack\_device\_\_() +### \_\_dlpack\_device\_\_(x, /) Returns device type and device ID in DLPack format. Meant for use within {ref}`function-from_dlpack`. +#### Parameters + +- **x**: _<array>_ + + - array instance. + #### Returns - **device**: _Tuple\[enum.IntEnum, int\]_ From 4edf370a6c363eb952a3dd1edf77e0c9d18256ea Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 23 Feb 2021 17:37:32 -0700 Subject: [PATCH 5/9] Make x positional only in __dlpack__() --- spec/API_specification/array_object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index eb50443d0..58c6f1d5a 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -396,7 +396,7 @@ Converts a zero-dimensional boolean array to a Python `bool` object. (method-__dlpack__)= -### \_\_dlpack\_\_(x, *, stream=None) +### \_\_dlpack\_\_(x, /, *, stream=None) Exports the array as a DLPack capsule, for consumption by {ref}`function-from_dlpack`. From d9d51aaa0eaf2824aed0517e379a507d04f4f048 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 5 Mar 2021 15:02:02 -0700 Subject: [PATCH 6/9] Remove an inconsistent rule about indexing The rule said that empty slices should work, but the note right below that says that they are optional. --- spec/API_specification/indexing.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/spec/API_specification/indexing.md b/spec/API_specification/indexing.md index ae9c5cedb..f219815d4 100644 --- a/spec/API_specification/indexing.md +++ b/spec/API_specification/indexing.md @@ -105,11 +105,6 @@ Slice syntax must have the following defaults. Let `n` be the axis (dimension) s - If `k` is greater than `0` and `j` is not provided (e.g., `0::2`), `j` must equal `n`. - If `k` is less than `0` and `i` is not provided (e.g., `:10:-2`), `i` must equal `n-1`. - If `k` is less than `0` and `j` is not provided (e.g., `0::-2`), `j` must equal `-n-1`. - -Using a slice to index a single array axis must adhere to the following rules. Let `n` be the axis (dimension) size. - -- If `i` equals `j`, a slice must return an empty array, whose axis (dimension) size along the indexed axis is `0`. - - Indexing via `:` and `::` must be equivalent and have defaults derived from the rules above. Both `:` and `::` indicate to select all elements along a single axis (dimension). ```{note} @@ -184,4 +179,4 @@ The result of an indexing operation (e.g., multi-axis indexing, boolean array in ```{note} The specified return value behavior includes indexing operations which return a single value (e.g., accessing a single element within a one-dimensional array). -``` \ No newline at end of file +``` From 0009a824522426dded3c9fdf11b47fc07d523d49 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 5 Mar 2021 15:21:29 -0700 Subject: [PATCH 7/9] Revert "Remove an inconsistent rule about indexing" This reverts commit d9d51aaa0eaf2824aed0517e379a507d04f4f048. --- spec/API_specification/indexing.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/indexing.md b/spec/API_specification/indexing.md index f219815d4..ae9c5cedb 100644 --- a/spec/API_specification/indexing.md +++ b/spec/API_specification/indexing.md @@ -105,6 +105,11 @@ Slice syntax must have the following defaults. Let `n` be the axis (dimension) s - If `k` is greater than `0` and `j` is not provided (e.g., `0::2`), `j` must equal `n`. - If `k` is less than `0` and `i` is not provided (e.g., `:10:-2`), `i` must equal `n-1`. - If `k` is less than `0` and `j` is not provided (e.g., `0::-2`), `j` must equal `-n-1`. + +Using a slice to index a single array axis must adhere to the following rules. Let `n` be the axis (dimension) size. + +- If `i` equals `j`, a slice must return an empty array, whose axis (dimension) size along the indexed axis is `0`. + - Indexing via `:` and `::` must be equivalent and have defaults derived from the rules above. Both `:` and `::` indicate to select all elements along a single axis (dimension). ```{note} @@ -179,4 +184,4 @@ The result of an indexing operation (e.g., multi-axis indexing, boolean array in ```{note} The specified return value behavior includes indexing operations which return a single value (e.g., accessing a single element within a one-dimensional array). -``` +``` \ No newline at end of file From 844c6f66f724c101ce3057ca990101ed8c670b92 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Wed, 31 Mar 2021 15:21:19 -0600 Subject: [PATCH 8/9] Clarify that Python integer overflow behavior is undefined --- spec/API_specification/type_promotion.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/type_promotion.md b/spec/API_specification/type_promotion.md index 6c694cbf4..d9862db88 100644 --- a/spec/API_specification/type_promotion.md +++ b/spec/API_specification/type_promotion.md @@ -9,7 +9,7 @@ diagram: ![Type promotion diagram](/_static/images/dtype_promotion_lattice.png) -_Type promotion diagram. Promotion between any two types is given by their join on this lattice. Only the types of participating arrays matter, not their values). Dashed lines indicate that behaviour for Python scalars is undefined on overflow. Boolean, integer and floating-point dtypes are not connected, indicating mixed-kind promotion is undefined._ +_Type promotion diagram. Promotion between any two types is given by their join on this lattice. Only the types of participating arrays matter, not their values. Dashed lines indicate that behavior for Python scalars is undefined on overflow. Boolean, integer and floating-point dtypes are not connected, indicating mixed-kind promotion is undefined._ ## Rules @@ -106,8 +106,7 @@ where `` is a built-in operator (see {ref}`operators` for operators supported by the array object) and `scalar` has a compatible type and value to the array dtype: - Python `bool` for a `bool` array dtype, -- a positive Python `int` for unsigned integer array dtypes, -- a Python `int` for integer array dtypes, +- a Python `int` within the [bounds](data-types) of the given dtype for integer array dtypes, - a Python `int` or `float` for floating-point array dtypes The expected behavior is then equivalent to: @@ -121,4 +120,7 @@ The expected behavior is then equivalent to: Behaviour is not specified when mixing a Python `float` and an array with an integer dtype; this may give `float32`, `float64`, or raise an exception - behavior of implementations will differ. + +The behavior is also not specified for integers outside of the bounds of a +given integer dtype. It may overflow, or result in an error. ``` From cbfb6f4da45fdaa756de128e1d776f8a3c6632a7 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 11 Apr 2021 18:21:37 +0200 Subject: [PATCH 9/9] One more x -> self update --- spec/API_specification/array_object.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 0516c9217..a8eb39104 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -466,13 +466,13 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap (method-__dlpack_device__)= -### \_\_dlpack\_device\_\_(x, /) +### \_\_dlpack\_device\_\_(self, /) Returns device type and device ID in DLPack format. Meant for use within {ref}`function-from_dlpack`. #### Parameters -- **x**: _<array>_ +- **self**: _<array>_ - array instance.