Small formatting fixes to make the spec parsable by the test suite scripts (data-apis#133)

* Small formatting fixes to make the spec parsable by the test suite scripts

* More formatting fixes

* 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.

* Add self arguments for __dlpack__ and __dlpack_device__

* Make x positional only in __dlpack__()

* 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.

* Revert "Remove an inconsistent rule about indexing"

This reverts commit d9d51aa.

* Clarify that Python integer overflow behavior is undefined

* One more x -> self update

Co-authored-by: Ralf Gommers <[email protected]>

Author: asmeurer

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__`
@@ -425,6 +425,10 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap
 
 #### Parameters
 
+-   **self**: _<array>_
+
+    -   array instance.
+
 -   **stream**: _Optional\[ int ]_
 
     -   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:
@@ -462,10 +466,16 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap
 
 
 (method-__dlpack_device__)=
-### \_\_dlpack\_device\_\_()
+### \_\_dlpack\_device\_\_(self, /)
 
 Returns device type and device ID in DLPack format. Meant for use within {ref}`function-from_dlpack`.
 
+#### Parameters
+
+-   **self**: _<array>_
+
+    -   array instance.
+
 #### Returns
 
 -   **device**: _Tuple\[enum.IntEnum, int\]_

spec/API_specification/data_type_functions.md

@@ -8,14 +8,14 @@ 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.
 
 #### Parameters
 
--   **type**: _Union\[ <dtype&gt, <array> ]_
+-   **type**: _Union\[ <dtype>, <array> ]_
 
     -   the kind of floating-point data-type about which to get information.
 
@@ -34,14 +34,14 @@ Machine limits for floating-point data types.
         -   **min**: _float_
             -   smallest representable number.
 
-(iinfo)=
+(function-iinfo)=
 ### iinfo(type, /)
 
 Machine limits for integer data types.
 
 #### Parameters
 
--   **type**: _Union\[ <dtype&gt, <array> ]_
+-   **type**: _Union\[ <dtype>, <array> ]_
 
     -   the kind of integer data-type about which to get information.
 
@@ -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.
 

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
 

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 `<op>` 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.
 ```