From 7d3eb75efc71f165340311e1c3425cf90f32ce9d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 8 Mar 2021 09:59:07 -0800 Subject: [PATCH 1/2] Use `self` and `other` in array object specs This is in conformance with PEP 8. --- spec/API_specification/array_object.md | 294 ++++++++++++------------- 1 file changed, 147 insertions(+), 147 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 66418395e..9879c3e0c 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -269,13 +269,13 @@ Transpose of the array. (method-__abs__)= -### \_\_abs\_\_(x, /) +### \_\_abs\_\_(self, /) -Calculates the absolute value for each element `x_i` of an array instance `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign). +Calculates the absolute value for each element of an array instance (i.e., the element-wise result has the same magnitude as the respective element but has positive sign). #### Special Cases -For floating-point operands, +For floating-point operands, let `self` equal `x`. - If `x_i` is `NaN`, the result is `NaN`. - If `x_i` is `-0`, the result is `+0`. @@ -283,7 +283,7 @@ For floating-point operands, #### Parameters -- **x**: _<array>_ +- **self**: _<array>_ - array instance. @@ -291,7 +291,7 @@ For floating-point operands, - **out**: _<array>_ - - an array containing the element-wise absolute value. The returned array must have the same data type as `x`. + - an array containing the element-wise absolute value. The returned array must have the same data type as `self`. ```{note} @@ -299,13 +299,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__add__)= -### \_\_add\_\_(x1, x2, /) +### \_\_add\_\_(self, other, /) -Calculates the sum for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Calculates the sum for each element of an array instance with the respective element of the array `other`. #### Special Cases -For floating-point operands, +For floating-point operands, let `self` equal `x1` and `other` equal `x2`. - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is `+infinity` and `x2_i` is `-infinity`, the result is `NaN`. @@ -332,13 +332,13 @@ Floating-point addition is a commutative operation, but not always associative. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance (augend array). -- **x2**: _<array>_ +- **other**: _<array>_ - - addend array. Must be compatible with `x1` (see {ref}`broadcasting`). + - addend array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -352,19 +352,19 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__and__)= -### \_\_and\_\_(x1, x2, /) +### \_\_and\_\_(self, other, /) -Evaluates `x1_i & x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `self_i & other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. Must have an integer or boolean data type. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have an integer or boolean data type. + - other array. Must be compatible with `self` (see {ref}`broadcasting`). Must have an integer or boolean data type. #### Returns @@ -378,13 +378,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__bool__)= -### \_\_bool\_\_(x, /) +### \_\_bool\_\_(self, /) Converts a zero-dimensional boolean array to a Python `bool` object. #### Parameters -- **x**: _<array>_ +- **self**: _<array>_ - zero-dimensional array instance. Must have a boolean data type. @@ -392,33 +392,33 @@ Converts a zero-dimensional boolean array to a Python `bool` object. - **out**: _<bool>_ - - a Python `bool` object representing the single element of the array `x`. + - a Python `bool` object representing the single element of the array. (method-__dlpack__)= -### \_\_dlpack\_\_(/, *, stream=None) +### \_\_dlpack\_\_(self, /, *, stream=None) -Exports the array as a DLPack capsule, for consumption by {ref}`function-from_dlpack`. +Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack capsule. #### Parameters -- **stream**: _Optional\[int\]_ +- **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: + - a Python integer representing a pointer to a stream. `stream` is provided by the consumer to the producer to instruct the producer to ensure that operations can safely be performed on the array. The pointer must be a positive integer or `-1`. If `stream` is `-1`, the value may be used by the consumer to signal "producer must not perform any synchronization". Device-specific notes: :::{admonition} CUDA - - `None`: producer must assume the legacy default stream (default), - - `1`: the legacy default stream, - - `2`: the per-thread default stream, - - `> 2`: stream number represented as a Python integer. + - `None`: producer must assume the legacy default stream (default). + - `1`: the legacy default stream. + - `2`: the per-thread default stream. + - `> 2`: stream number represented as a Python integer. - Note that `0` is disallowed (it's ambiguous, it could mean either `None`, `1` or `2`). + `0` is disallowed due to its ambiguity: `0` could mean either `None`, `1`, or `2`. ::: :::{admonition} ROCm - - `None`: producer must assume the legacy default stream (default), - - `0`: the default stream, - - `> 2`: stream number represented as a Python integer. + - `None`: producer must assume the legacy default stream (default). + - `0`: the default stream. + - `> 2`: stream number represented as a Python integer. Using `1` and `2` is not supported. ::: @@ -435,7 +435,7 @@ Exports the array as a DLPack capsule, for consumption by {ref}`function-from_dl - **capsule**: _<PyCapsule>_ - - A DLPack capsule for the array. See {ref}`data-interchange` for details. + - a DLPack capsule for the array. See {ref}`data-interchange` for details. (method-__dlpack_device__)= @@ -447,7 +447,7 @@ Returns device type and device ID in DLPack format. Meant for use within {ref}`f - **device**: _Tuple\[enum.IntEnum, int\]_ - - A tuple `(device_type, device_id)` in DLPack format. Valid device type enum members are: + - a tuple `(device_type, device_id)` in DLPack format. Valid device type enum members are: ``` CPU = 1 @@ -461,19 +461,19 @@ Returns device type and device ID in DLPack format. Meant for use within {ref}`f ``` (method-__eq__)= -### \_\_eq\_\_(x1, x2, /) +### \_\_eq\_\_(self, other, /) -Computes the truth value of `x1_i == x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Computes the truth value of `self_i == other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -487,13 +487,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__float__)= -### \_\_float\_\_(x, /) +### \_\_float\_\_(self, /) Converts a zero-dimensional floating-point array to a Python `float` object. #### Parameters -- **x**: _<array>_ +- **self**: _<array>_ - zero-dimensional array instance. Must have a floating-point data type. @@ -501,22 +501,22 @@ Converts a zero-dimensional floating-point array to a Python `float` object. - **out**: _<float>_ - - a Python `float` object representing the single element of the array `x`. + - a Python `float` object representing the single element of the array instance. (method-__floordiv__)= -### \_\_floordiv\_\_(x1, x2, /) +### \_\_floordiv\_\_(self, other, /) -Evaluates `x1_i // x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `self_i // other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -530,19 +530,19 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__ge__)= -### \_\_ge\_\_(x1, x2, /) +### \_\_ge\_\_(self, other, /) -Computes the truth value of `x1_i >= x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Computes the truth value of `self_i >= other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -556,13 +556,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__getitem__)= -### \_\_getitem\_\_(x, key, /) +### \_\_getitem\_\_(self, key, /) -Returns `x[key]`. +Returns `self[key]`. #### Parameters -- **x**: _<array;>_ +- **self**: _<array;>_ - array instance. @@ -574,22 +574,22 @@ Returns `x[key]`. - **out**: _<array>_ - - an array containing the accessed value(s). The returned array must have the same data type as `x`. + - an array containing the accessed value(s). The returned array must have the same data type as `self`. (method-__gt__)= -### \_\_gt\_\_(x1, x2, /) +### \_\_gt\_\_(self, other, /) -Computes the truth value of `x1_i > x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Computes the truth value of `self_i > other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -603,13 +603,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__int__)= -### \_\_int\_\_(x, /) +### \_\_int\_\_(self, /) Converts a zero-dimensional integer array to a Python `int` object. #### Parameters -- **x**: _<array>_ +- **self**: _<array>_ - zero-dimensional array instance. Must have an integer data type. @@ -617,16 +617,16 @@ Converts a zero-dimensional integer array to a Python `int` object. - **out**: _<int>_ - - a Python `int` object representing the single element of the array `x`. + - a Python `int` object representing the single element of the array instance. (method-__invert__)= -### \_\_invert\_\_(x, /) +### \_\_invert\_\_(self, /) -Evaluates `~x_i` for each element `x_i` of an array instance `x`. +Evaluates `~self_i` for each element of an array instance. #### Parameters -- **x**: _<array>_ +- **self**: _<array>_ - array instance. Must have an integer or boolean data type. @@ -634,7 +634,7 @@ Evaluates `~x_i` for each element `x_i` of an array instance `x`. - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have the same data type as `x`. + - an array containing the element-wise results. The returned array must have the same data type as `self`. ```{note} @@ -642,19 +642,19 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__le__)= -### \_\_le\_\_(x1, x2, /) +### \_\_le\_\_(self, other, /) -Computes the truth value of `x1_i <= x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Computes the truth value of `self_i <= other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -668,30 +668,30 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__len__)= -### \_\_len\_\_(x, /) +### \_\_len\_\_(self, /) _TODO: need to more carefully consider this in order to accommodate, e.g., graph tensors where a shape may be dynamic. Furthermore, not clear whether this should be implemented, as, e.g., NumPy's behavior of returning the size of the first dimension is not necessarily intuitive, as opposed to, say, the total number of elements._ (method-__lshift__)= -### \_\_lshift\_\_(x1, x2, /) +### \_\_lshift\_\_(self, other, /) -Evaluates `x1_i << x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `self_i << other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. Must have an integer data type. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have an integer data type. Each element must be greater than or equal to `0`. + - other array. Must be compatible with `self` (see {ref}`broadcasting`). Must have an integer data type. Each element must be greater than or equal to `0`. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have the same data type as `x1`. + - an array containing the element-wise results. The returned array must have the same data type as `self`. ```{note} @@ -699,19 +699,19 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__lt__)= -### \_\_lt\_\_(x1, x2, /) +### \_\_lt\_\_(self, other, /) -Computes the truth value of `x1_i < x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Computes the truth value of `self_i < other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -725,19 +725,19 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__matmul__)= -### \_\_matmul\_\_(x1, x2, /) +### \_\_matmul\_\_(self, other, /) _TODO: awaiting `matmul` functional equivalent._ #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -746,25 +746,25 @@ _TODO: awaiting `matmul` functional equivalent._ - _TODO_ (method-__mod__)= -### \_\_mod\_\_(x1, x2, /) +### \_\_mod\_\_(self, other, /) -Evaluates `x1_i % x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `self_i % other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns - **out**: _<array>_ - - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by {ref}`type-promotion`. + - an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `other_i`. The returned array must have a floating-point data type determined by {ref}`type-promotion`. ```{note} @@ -772,13 +772,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__mul__)= -### \_\_mul\_\_(x1, x2, /) +### \_\_mul\_\_(self, other, /) -Calculates the product for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Calculates the product for each element of an array instance with the respective element of the array `other`. #### Special Cases -For floating-point operands, +For floating-point operands, let `self` equal `x1` and `other` equal `x2`. - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+0` or `-0`, the result is `NaN`. @@ -797,13 +797,13 @@ Floating-point multiplication is not always associative due to finite precision. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -817,19 +817,19 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__ne__)= -### \_\_ne\_\_(x1, x2, /) +### \_\_ne\_\_(self, other, /) -Computes the truth value of `x1_i != x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Computes the truth value of `self_i != other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -843,13 +843,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__neg__)= -### \_\_neg\_\_(x, /) +### \_\_neg\_\_(self, /) -Evaluates `-x_i` for each element `x_i` of an array instance `x`. +Evaluates `-self_i` for each element of an array instance. #### Parameters -- **x**: _<array>_ +- **self**: _<array>_ - array instance. @@ -857,7 +857,7 @@ Evaluates `-x_i` for each element `x_i` of an array instance `x`. - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have a data type determined by {ref}`type-promotion`. + - an array containing the evaluated result for each element in `self`. The returned array must have a data type determined by {ref}`type-promotion`. ```{note} @@ -865,19 +865,19 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__or__)= -### \_\_or\_\_(x1, x2, /) +### \_\_or\_\_(self, other, /) -Evaluates `x1_i | x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `self_i | other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. Must have an integer or boolean data type. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have an integer or boolean data type. + - other array. Must be compatible with `self` (see {ref}`broadcasting`). Must have an integer or boolean data type. #### Returns @@ -891,13 +891,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__pos__)= -### \_\_pos\_\_(x, /) +### \_\_pos\_\_(self, /) -Evaluates `+x_i` for each element `x_i` of an array instance `x`. +Evaluates `+self_i` for each element of an array instance. #### Parameters -- **x**: _<array>_ +- **self**: _<array>_ - array instance. @@ -905,7 +905,7 @@ Evaluates `+x_i` for each element `x_i` of an array instance `x`. - **out**: _<array>_ - - an array containing the evaluated result for each element in `x`. The returned array must have the same data type as `x`. + - an array containing the evaluated result for each element. The returned array must have the same data type as `self`. ```{note} @@ -913,13 +913,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__pow__)= -### \_\_pow\_\_(x1, x2, /) +### \_\_pow\_\_(self, other, /) -Calculates an implementation-dependent approximation of exponentiation by raising each element `x1_i` (the base) of an array instance `x1` to the power of `x2_i` (the exponent), where `x2_i` is the corresponding element of the array `x2`. +Calculates an implementation-dependent approximation of exponentiation by raising each element (the base) of an array instance to the power of `other_i` (the exponent), where `other_i` is the corresponding element of the array `other`. #### Special Cases -For floating-point operands, +For floating-point operands, let `self` equal `x1` and `other` equal `x2`. - If `x1_i` is not equal to `1` and `x2_i` is `NaN`, the result is `NaN`. - If `x2_i` is `+0`, the result is `1`, even if `x1_i` is `NaN`. @@ -948,13 +948,13 @@ For floating-point operands, #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance whose elements correspond to the exponentiation base. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array whose elements correspond to the exponentiation exponent. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array whose elements correspond to the exponentiation exponent. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -968,25 +968,25 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__rshift__)= -### \_\_rshift\_\_(x1, x2, /) +### \_\_rshift\_\_(self, other, /) -Evaluates `x1_i >> x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `self_i >> other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. Must have an integer data type. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have an integer data type. Each element must be greater than or equal to `0`. + - other array. Must be compatible with `self` (see {ref}`broadcasting`). Must have an integer data type. Each element must be greater than or equal to `0`. #### Returns - **out**: _<array>_ - - an array containing the element-wise results. The returned array must have the same data type as `x1`. + - an array containing the element-wise results. The returned array must have the same data type as `self`. ```{note} @@ -994,24 +994,24 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__setitem__)= -### \_\_setitem\_\_(x, key, value, /) +### \_\_setitem\_\_(self, key, value, /) _TODO: dependent on the indexing specification._ (method-__sub__)= -### \_\_sub\_\_(x1, x2, /) +### \_\_sub\_\_(self, other, /) -Calculates the difference for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. The result of `x1_i - x2_i` must be the same as `x1_i + (-x2_i)` and must be governed by the same floating-point rules as addition (see [`__add__()`](#__add__x1-x2-)). +Calculates the difference for each element of an array instance with the respective element of the array `other`. The result of `self_i - other_i` must be the same as `self_i + (-other_i)` and must be governed by the same floating-point rules as addition (see [`__add__()`](#__add__x1-x2-)). #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance (minuend array). -- **x2**: _<array>_ +- **other**: _<array>_ - - subtrahend array. Must be compatible with `x1` (see {ref}`broadcasting`). + - subtrahend array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -1025,13 +1025,13 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__truediv__)= -### \_\_truediv\_\_(x1, x2, /) +### \_\_truediv\_\_(self, other, /) -Evaluates `x1_i / x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `self_i / other_i` for each element of an array instance with the respective element of the array `other`. #### Special Cases -For floating-point operands, +For floating-point operands, let `self` equal `x1` and `other` equal `x2`. - If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`. - If `x1_i` is either `+infinity` or `-infinity` and `x2_i` is either `+infinity` or `-infinity`, the result is `NaN`. @@ -1058,13 +1058,13 @@ For floating-point operands, #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). + - other array. Must be compatible with `self` (see {ref}`broadcasting`). #### Returns @@ -1078,19 +1078,19 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-__xor__)= -### \_\_xor\_\_(x1, x2, /) +### \_\_xor\_\_(self, other, /) -Evaluates `x1_i ^ x2_i` for each element `x1_i` of an array instance `x1` with the respective element `x2_i` of the array `x2`. +Evaluates `self_i ^ other_i` for each element of an array instance with the respective element of the array `other`. #### Parameters -- **x1**: _<array>_ +- **self**: _<array>_ - array instance. Must have an integer or boolean data type. -- **x2**: _<array>_ +- **other**: _<array>_ - - other array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have an integer or boolean data type. + - other array. Must be compatible with `self` (see {ref}`broadcasting`). Must have an integer or boolean data type. #### Returns From 8ff0536ae6b8a66d1d42e6c99f6e1f56bdbac9f8 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 11 Apr 2021 18:15:46 +0200 Subject: [PATCH 2/2] Fix build warnings because anchors include `x`/`self` --- spec/API_specification/array_object.md | 46 +++++++++++++------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index e3fee4abc..28d881ac5 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -21,114 +21,114 @@ A conforming implementation of the array API standard must provide and support a A conforming implementation of the array API standard must provide and support an array object supporting the following Python operators: -- `x1 < x2`: [`__lt__(x1, x2)`](#__lt__x1-x2-) +- `x1 < x2`: [`__lt__(x1, x2)`](#__lt__self-other-) - [`operator.lt(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.lt) - [`operator.__lt__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__lt__) -- `x1 <= x2`: [`__le__(x1, x2)`](#__le__x1-x2-) +- `x1 <= x2`: [`__le__(x1, x2)`](#__le__self-other-) - [`operator.le(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.le) - [`operator.__le__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__le__) -- `x1 > x2`: [`__gt__(x1, x2)`](#__gt__x1-x2-) +- `x1 > x2`: [`__gt__(x1, x2)`](#__gt__self-other-) - [`operator.gt(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.gt) - [`operator.__gt__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__gt__) -- `x1 >= x2`: [`__ge__(x1, x2)`](#__ge__x1-x2-) +- `x1 >= x2`: [`__ge__(x1, x2)`](#__ge__self-other-) - [`operator.ge(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.ge) - [`operator.__ge__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__ge__) -- `x1 == x2`: [`__eq__(x1, x2)`](#__eq__x1-x2-) +- `x1 == x2`: [`__eq__(x1, x2)`](#__eq__self-other-) - [`operator.eq(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.eq) - [`operator.__eq__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__eq__) -- `x1 != x2`: [`__ne__(x1, x2)`](#__ne__x1-x2-) +- `x1 != x2`: [`__ne__(x1, x2)`](#__ne__self-other-) - [`operator.ne(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.ne) - [`operator.__ne__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__ne__) -- `+x`: [`__pos__(x)`](#__pos__x-) +- `+x`: [`__pos__(x)`](#__pos__self-) - [`operator.pos(x)`](https://docs.python.org/3/library/operator.html#operator.pos) - [`operator.__pos__(x)`](https://docs.python.org/3/library/operator.html#operator.__pos__) -- `-x`: [`__neg__(x)`](#__neg__x-) +- `-x`: [`__neg__(x)`](#__neg__self-) - [`operator.neg(x)`](https://docs.python.org/3/library/operator.html#operator.neg) - [`operator.__neg__(x)`](https://docs.python.org/3/library/operator.html#operator.__neg__) -- `x1 + x2`: [`__add__(x1, x2)`](#__add__x1-x2-) +- `x1 + x2`: [`__add__(x1, x2)`](#__add__self-other-) - [`operator.add(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.add) - [`operator.__add__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__add__) -- `x1 - x2`: [`__sub__(x1, x2)`](#__sub__x1-x2-) +- `x1 - x2`: [`__sub__(x1, x2)`](#__sub__self-other-) - [`operator.sub(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.sub) - [`operator.__sub__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__sub__) -- `x1 * x2`: [`__mul__(x1, x2)`](#__mul__x1-x2-) +- `x1 * x2`: [`__mul__(x1, x2)`](#__mul__self-other-) - [`operator.mul(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.mul) - [`operator.__mul__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__mul__) -- `x1 / x2`: [`__truediv__(x1, x2)`](#__truediv__x1-x2-) +- `x1 / x2`: [`__truediv__(x1, x2)`](#__truediv__self-other-) - [`operator.truediv(x1,x2)`](https://docs.python.org/3/library/operator.html#operator.truediv) - [`operator.__truediv__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__truediv__) -- `x1 // x2`: [`__floordiv__(x1, x2)`](#__floordiv__x1-x2-) +- `x1 // x2`: [`__floordiv__(x1, x2)`](#__floordiv__self-other-) - [`operator.floordiv(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.floordiv) - [`operator.__floordiv__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__floordiv__) -- `x1 % x2`: [`__mod__(x1, x2)`](#__mod__x1-x2-) +- `x1 % x2`: [`__mod__(x1, x2)`](#__mod__self-other-) - [`operator.mod(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.mod) - [`operator.__mod__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__mod__) -- `x1 ** x2`: [`__pow__(x1, x2)`](#__pow__x1-x2-) +- `x1 ** x2`: [`__pow__(x1, x2)`](#__pow__self-other-) - [`operator.pow(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.pow) - [`operator.__pow__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__pow__) -- `x1 @ x2`: [`__matmul__(x1, x2)`](#__matmul__x1-x2-) +- `x1 @ x2`: [`__matmul__(x1, x2)`](#__matmul__self-other-) - [`operator.matmul(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.matmul) - [`operator.__matmul__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__matmul__) -- `~x`: [`__invert__(x)`](#__invert__x-) +- `~x`: [`__invert__(x)`](#__invert__self-) - [`operator.inv(x)`](https://docs.python.org/3/library/operator.html#operator.inv) - [`operator.invert(x)`](https://docs.python.org/3/library/operator.html#operator.invert) - [`operator.__inv__(x)`](https://docs.python.org/3/library/operator.html#operator.__inv__) - [`operator.__invert__(x)`](https://docs.python.org/3/library/operator.html#operator.__invert__) -- `x1 & x2`: [`__and__(x1, x2)`](#__and__x1-x2-) +- `x1 & x2`: [`__and__(x1, x2)`](#__and__self-other-) - [`operator.and(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.and) - [`operator.__and__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__and__) -- `x1 | x2`: [`__or__(x1, x2)`](#__or__x1-x2-) +- `x1 | x2`: [`__or__(x1, x2)`](#__or__self-other-) - [`operator.or(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.or) - [`operator.__or__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__or__) -- `x1 ^ x2`: [`__xor__(x1, x2)`](#__xor__x1-x2-) +- `x1 ^ x2`: [`__xor__(x1, x2)`](#__xor__self-other-) - [`operator.xor(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.xor) - [`operator.__xor__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__xor__) -- `x1 << x2`: [`__lshift__(x1, x2)`](#__lshift__x1-x2-) +- `x1 << x2`: [`__lshift__(x1, x2)`](#__lshift__self-other-) - [`operator.lshift(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.lshift) - [`operator.__lshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__lshift__) -- `x1 >> x2`: [`__rshift__(x1, x2)`](#__rshift__x1-x2-) +- `x1 >> x2`: [`__rshift__(x1, x2)`](#__rshift__self-other-) - [`operator.rshift(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.rshift) - [`operator.__rshift__(x1, x2)`](https://docs.python.org/3/library/operator.html#operator.__rshift__) @@ -1024,7 +1024,7 @@ _TODO: dependent on the indexing specification._ (method-__sub__)= ### \_\_sub\_\_(self, other, /) -Calculates the difference for each element of an array instance with the respective element of the array `other`. The result of `self_i - other_i` must be the same as `self_i + (-other_i)` and must be governed by the same floating-point rules as addition (see [`__add__()`](#__add__x1-x2-)). +Calculates the difference for each element of an array instance with the respective element of the array `other`. The result of `self_i - other_i` must be the same as `self_i + (-other_i)` and must be governed by the same floating-point rules as addition (see [`__add__()`](#__add__self-other-)). #### Parameters