Clean up some wording in the fft extension

doc-requirements.txt

@@ -1,8 +1,7 @@
-sphinx==4.3.0
+sphinx==6.2.1
 sphinx-material==0.0.30
 myst-parser
 sphinx_markdown_tables
 sphinx_copybutton
 sphinx_favicon
-docutils<0.18
 sphinx-math-dollar

spec/2021.12/assumptions.md

@@ -26,7 +26,7 @@ of functions to be predictable from input dtypes only rather than input values.
 
 The only dependency that's assumed in this standard is that on Python itself.
 Python >= 3.8 is assumed, motivated by the use of positional-only parameters
-(see [function and method signatures](API_specification/function_and_method_signatures.md)).
+(see [function and method signatures](API_specification/function_and_method_signatures.rst)).
 
 Importantly, array libraries are not assumed to be aware of each other, or of
 a common array-specific layer. The [use cases](use_cases.md) do not require
@@ -39,7 +39,7 @@ for that is:
 
 Array libraries may know how to interoperate with each other, for example by
 constructing their own array type from that of another library or by shared
-memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)).
+memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.rst)).
 This can be done without a dependency though - only adherence to a protocol is
 enough.
 

spec/2021.12/purpose_and_scope.md

@@ -151,7 +151,7 @@ standard is shown in this diagram:
    _Rationale: this is an important topic for some array-consuming libraries,
    but there is no widely shared C/Cython API and hence it doesn't make sense at
    this point in time to standardize anything. See
-   the [C API section](design_topics/C_API.md) for more details._
+   the [C API section](design_topics/C_API.rst) for more details._
 
 4. Standardization of these dtypes is out of scope: bfloat16, complex, extended
    precision floating point, datetime, string, object and void dtypes.

spec/2021.12/use_cases.md

@@ -59,7 +59,7 @@ array implementation as a dependency.
 
 It's clear that SciPy functionality that relies on compiled extensions (C,
 C++, Cython, Fortran) directly can't easily be run on another array library
-than NumPy (see [C API](design_topics/C_API.md) for more details about this topic). Pure Python
+than NumPy (see [C API](design_topics/C_API.rst) for more details about this topic). Pure Python
 code can work though. There's two main possibilities:
 
 1. Testing with another package, manually or in CI, and simply provide a list

spec/2022.12/API_specification/array_object.rst

@@ -163,7 +163,8 @@ A conforming implementation of the array API standard must provide and support a
     -   `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__>`_
 
-Comparison operators should be defined for arrays having any data type.
+:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators should be defined for arrays having any data type.
+For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
 
 In-place Operators
 ~~~~~~~~~~~~~~~~~~

spec/2022.12/assumptions.md

@@ -26,7 +26,7 @@ of functions to be predictable from input dtypes only rather than input values.
 
 The only dependency that's assumed in this standard is that on Python itself.
 Python >= 3.8 is assumed, motivated by the use of positional-only parameters
-(see [function and method signatures](API_specification/function_and_method_signatures.md)).
+(see [function and method signatures](API_specification/function_and_method_signatures.rst)).
 
 Importantly, array libraries are not assumed to be aware of each other, or of
 a common array-specific layer. The [use cases](use_cases.md) do not require
@@ -39,7 +39,7 @@ for that is:
 
 Array libraries may know how to interoperate with each other, for example by
 constructing their own array type from that of another library or by shared
-memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)).
+memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.rst)).
 This can be done without a dependency though - only adherence to a protocol is
 enough.
 

spec/2022.12/purpose_and_scope.md

@@ -151,7 +151,7 @@ standard is shown in this diagram:
    _Rationale: this is an important topic for some array-consuming libraries,
    but there is no widely shared C/Cython API and hence it doesn't make sense at
    this point in time to standardize anything. See
-   the [C API section](design_topics/C_API.md) for more details._
+   the [C API section](design_topics/C_API.rst) for more details._
 
 4. Standardization of these dtypes is out of scope: bfloat16, extended
    precision floating point, datetime, string, object and void dtypes.

spec/2022.12/use_cases.md

@@ -59,7 +59,7 @@ array implementation as a dependency.
 
 It's clear that SciPy functionality that relies on compiled extensions (C,
 C++, Cython, Fortran) directly can't easily be run on another array library
-than NumPy (see [C API](design_topics/C_API.md) for more details about this topic). Pure Python
+than NumPy (see [C API](design_topics/C_API.rst) for more details about this topic). Pure Python
 code can work though. There's two main possibilities:
 
 1. Testing with another package, manually or in CI, and simply provide a list

spec/draft/API_specification/array_object.rst

@@ -163,7 +163,8 @@ A conforming implementation of the array API standard must provide and support a
     -   `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__>`_
 
-Comparison operators should be defined for arrays having any data type.
+:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators should be defined for arrays having any data type.
+For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
 
 In-place Operators
 ~~~~~~~~~~~~~~~~~~

spec/draft/API_specification/elementwise_functions.rst

@@ -33,6 +33,7 @@ Objects in API
    bitwise_right_shift
    bitwise_xor
    ceil
+   clip
    conj
    copysign
    cos
@@ -60,6 +61,8 @@ Objects in API
    logical_not
    logical_or
    logical_xor
+   maximum
+   minimum
    multiply
    negative
    not_equal

spec/draft/API_specification/function_and_method_signatures.rst

@@ -5,7 +5,7 @@ Function and method signatures
 
 Function signatures in this standard adhere to the following:
 
-1. Positional parameters must be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ parameters.
+1. Positional parameters should be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ parameters.
    Positional-only parameters have no externally-usable name. When a function
    accepting positional-only parameters is called, positional arguments are
    mapped to these parameters based solely on their order.
@@ -20,7 +20,7 @@ Function signatures in this standard adhere to the following:
     namespace >= 3.8. Alternatively, they can add guidance to their users in the
     documentation to use the functions as if they were positional-only.
 
-2. Optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
+2. Optional parameters should be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
 
    *Rationale: this leads to more readable code, and it makes it easier to
    evolve an API over time by adding keywords without having to worry about
@@ -30,8 +30,8 @@ Function signatures in this standard adhere to the following:
    is called ``x``. For functions that have multiple array parameters, those
    parameters are called ``xi`` with ``i = 1, 2, ...`` (i.e., ``x1``, ``x2``).
 
-4. Type annotations are left out of the signatures themselves for readability; however,
-   they are added to individual parameter descriptions. For code which aims to
+4. Signatures include type annotations. The type annotations are also added to
+   individual parameter and return value descriptions. For code which aims to
    adhere to the standard, adding type annotations is strongly recommended.
 
 A function signature and description will look like:
@@ -57,3 +57,7 @@ A function signature and description will look like:
 
 
 Method signatures will follow the same conventions modulo the addition of ``self``.
+
+Note that there are a few exceptions to rules (1) and (2), in cases where
+it enhances readability or use of the non-default form of the parameter in
+question is commonly used in code written for existing array libraries.

spec/draft/API_specification/searching_functions.rst

@@ -23,4 +23,5 @@ Objects in API
    argmax
    argmin
    nonzero
+   searchsorted
    where

spec/draft/API_specification/statistical_functions.rst

@@ -18,6 +18,7 @@ Objects in API
    :toctree: generated
    :template: method.rst
 
+   cumulative_sum
    max
    mean
    min

spec/draft/assumptions.md

@@ -26,7 +26,7 @@ of functions to be predictable from input dtypes only rather than input values.
 
 The only dependency that's assumed in this standard is that on Python itself.
 Python >= 3.8 is assumed, motivated by the use of positional-only parameters
-(see [function and method signatures](API_specification/function_and_method_signatures.md)).
+(see [function and method signatures](API_specification/function_and_method_signatures.rst)).
 
 Importantly, array libraries are not assumed to be aware of each other, or of
 a common array-specific layer. The [use cases](use_cases.md) do not require
@@ -39,7 +39,7 @@ for that is:
 
 Array libraries may know how to interoperate with each other, for example by
 constructing their own array type from that of another library or by shared
-memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)).
+memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.rst)).
 This can be done without a dependency though - only adherence to a protocol is
 enough.
 

spec/draft/design_topics/data_interchange.rst

@@ -84,3 +84,22 @@ page gives a high-level specification for data exchange in Python using DLPack.
    are recommended to do so using the same syntax and semantics as outlined
    below. They are not required to return an array object from ``from_dlpack``
    which conforms to this standard.
+
+Non-supported use cases
+-----------------------
+
+Use of DLPack requires that the data can be represented by a strided, in-memory
+layout on a single device. This covers usage by a large range of, but not all,
+known and possible array libraries. Use cases that are not supported by DLPack
+include:
+
+- Distributed arrays, i.e., the data residing on multiple nodes or devices,
+- Sparse arrays, i.e., sparse representations where a data value (typically
+  zero) is implicit.
+
+There may be other reasons why it is not possible or desirable for an
+implementation to materialize the array as strided data in memory. In such
+cases, the implementation may raise a `BufferError` in the `__dlpack__` or
+`__dlpack_device__` method. In case an implementation is never able to export
+its array data via DLPack, it may omit `__dlpack__` and `__dlpack_device__`
+completely, and hence `from_dlpack` may raise an `AttributeError`.

spec/draft/extensions/index.rst

@@ -24,11 +24,10 @@ the implementer, e.g. via a regular submodule that is imported under the
 The functions in an extension must adhere to the same conventions as those in
 the array API standard. See :ref:`api-specification`.
 
-
-Extensions
-----------
+------------------------------------------------------------------------------
 
 .. toctree::
+   :caption: Extension modules:
    :maxdepth: 1
 
    fourier_transform_functions

spec/draft/purpose_and_scope.md

@@ -151,7 +151,7 @@ standard is shown in this diagram:
    _Rationale: this is an important topic for some array-consuming libraries,
    but there is no widely shared C/Cython API and hence it doesn't make sense at
    this point in time to standardize anything. See
-   the [C API section](design_topics/C_API.md) for more details._
+   the [C API section](design_topics/C_API.rst) for more details._
 
 4. Standardization of these dtypes is out of scope: bfloat16, extended
    precision floating point, datetime, string, object and void dtypes.

spec/draft/use_cases.md

@@ -59,7 +59,7 @@ array implementation as a dependency.
 
 It's clear that SciPy functionality that relies on compiled extensions (C,
 C++, Cython, Fortran) directly can't easily be run on another array library
-than NumPy (see [C API](design_topics/C_API.md) for more details about this topic). Pure Python
+than NumPy (see [C API](design_topics/C_API.rst) for more details about this topic). Pure Python
 code can work though. There's two main possibilities:
 
 1. Testing with another package, manually or in CI, and simply provide a list

src/_array_api_conf.py

@@ -52,12 +52,14 @@
 nitpick_ignore = [
     ("py:class", "collections.abc.Sequence"),
     ("py:class", "Optional[Union[int, float, Literal[inf, - inf, 'fro', 'nuc']]]"),
+    ("py:class", "int | float | ~typing.Literal[inf, -inf, 'fro', 'nuc'] | None"),
     ("py:class", "Union[int, float, Literal[inf, - inf]]"),
     (
         "py:obj",
         "typing.Optional[typing.Union[int, float, typing.Literal[inf, - inf, 'fro', 'nuc']]]",
     ),
     ("py:obj", "typing.Union[int, float, typing.Literal[inf, - inf]]"),
+    ("py:class", "int | float | ~typing.Literal[inf, -inf]"),
     ("py:class", "enum.Enum"),
     ("py:class", "ellipsis"),
 ]