Merge branch 'main' of https://github.com/data-apis/array-api into repeat

Author: kgryte

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/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

@@ -144,23 +144,22 @@ standard is shown in this diagram:
    _Rationale: execution is the domain of implementations. Attempting to specify
    execution behavior in a standard is likely to require much more fine-grained
    coordination between developers of implementations, and hence is likely to
-   become an obstable to adoption._
+   become an obstacle to adoption._
 
 3. Non-Python API standardization (e.g., Cython or NumPy C APIs)
 
    _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
+4. Standardization of these dtypes is out of scope: bfloat16, extended
    precision floating point, datetime, string, object and void dtypes.
 
    _Rationale: these dtypes aren't uniformly supported, and their inclusion at
    this point in time could put a significant implementation burden on
    libraries. It is expected that some of these dtypes - in particular
-   `bfloat16`, `complex64`, and `complex128` - will be included in a future
-   version of the standard._
+   `bfloat16` - will be included in a future version of the standard._
 
 5. The following topics are out of scope: I/O, polynomials, error handling,
    testing routines, building and packaging related functionality, methods of

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

@@ -7,7 +7,7 @@ Array object
 
 A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods.
 
-Furthermore, a conforming implementation of the array API standard must support array objects of arbitrary rank ``N`` (i.e., number of dimensions), where ``N`` is greater than or equal to zero.
+Furthermore, a conforming implementation of the array API standard must support, at minimum, array objects of rank (i.e., number of dimensions) ``0``, ``1``, ``2``, ``3``, and ``4`` and must explicitly document their maximum supported rank ``N``.
 
 .. note::
     Conforming implementations must support zero-dimensional arrays.

spec/draft/API_specification/elementwise_functions.rst

@@ -33,7 +33,9 @@ Objects in API
    bitwise_right_shift
    bitwise_xor
    ceil
+   clip
    conj
+   copysign
    cos
    cosh
    divide
@@ -59,6 +61,8 @@ Objects in API
    logical_not
    logical_or
    logical_xor
+   maximum
+   minimum
    multiply
    negative
    not_equal
@@ -68,6 +72,7 @@ Objects in API
    remainder
    round
    sign
+   signbit
    sin
    sinh
    square

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/indexing.rst

@@ -156,6 +156,9 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult
   .. note::
     Expanding dimensions can be equivalently achieved via repeated invocation of :func:`~array_api.expand_dims`.
 
+  .. note::
+    The constant ``newaxis`` is an alias of ``None`` and can thus be used in a similar manner as ``None``.
+
 - Except in the case of providing a single ellipsis (e.g., ``A[2:10, ...]`` or ``A[1:, ..., 2:5]``), the number of provided single-axis indexing expressions (excluding ``None``) should equal ``N``. For example, if ``A`` has rank ``2``, a single-axis indexing expression should be explicitly provided for both axes (e.g., ``A[2:10, :]``). An ``IndexError`` exception should be raised if the number of provided single-axis indexing expressions (excluding ``None``) is less than ``N``.
 
   .. note::

spec/draft/API_specification/manipulation_functions.rst

@@ -30,4 +30,5 @@ Objects in API
    roll
    squeeze
    stack
+   tile
    unstack

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/design_topics/index.rst

@@ -7,6 +7,7 @@ Design topics & constraints
 
    copies_views_and_mutation
    data_dependent_output_shapes
+   lazy_eager
    data_interchange
    device_support
    static_typing

spec/draft/design_topics/lazy_eager.rst

@@ -0,0 +1,43 @@
+.. _lazy-eager:
+
+Lazy vs. eager execution
+========================
+
+While the execution model for implementations is out of scope of this standard,
+there are a few aspects of lazy (or graph-based) execution as contrasted to
+eager execution that may have an impact on the prescribed semantics of
+individual APIs, and will therefore show up in the API specification.
+
+One important difference is data-dependent or value-dependent behavior, as
+described in :ref:`data-dependent-output-shapes`. Because such behavior is hard
+to implement, implementers may choose to omit such APIs from their library.
+
+Another difference is when the Python language itself prescribes that a
+specific type *must* be returned. For those cases, it is not possible to return
+a lazy/delayed kind of object to avoid computing a value. This is the case for
+five dunder methods: `__bool__`, `__int__`, `__float__`, `__complex__` and
+`__index__`. Each implementation has only two choices when one of these methods
+is called:
+
+1. Compute a value of the required type (a Python scalar of type `bool`, `int`,
+   `float` or `complex`), or
+2. Raise an exception.
+
+When an implementation is 100% lazy, for example when it serializes a
+computation graph, computing the value is not possible and hence such an
+implementation has no choice but to raise an exception. For a "mostly lazy"
+implementation, it may make sense to trigger execution instead - but it is not
+required to, both choices are valid.
+
+A common code construct where this happens is conditional logic, e.g.::
+
+    vals = compute_something()
+    if all(vals):
+        # The if-statement will make Python call the __bool__ method
+        # on the result of `all(vals)`.
+        do_something_else()
+
+Note that the API does not contain control flow constructs, as of now, that
+would allow avoiding the implicit `__bool__` call in the example above. The
+only control flow-like function is `where`, but there's no function like `cond`
+to replace an `if`-statement.

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

@@ -144,23 +144,22 @@ standard is shown in this diagram:
    _Rationale: execution is the domain of implementations. Attempting to specify
    execution behavior in a standard is likely to require much more fine-grained
    coordination between developers of implementations, and hence is likely to
-   become an obstable to adoption._
+   become an obstacle to adoption._
 
 3. Non-Python API standardization (e.g., Cython or NumPy C APIs)
 
    _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
+4. Standardization of these dtypes is out of scope: bfloat16, extended
    precision floating point, datetime, string, object and void dtypes.
 
    _Rationale: these dtypes aren't uniformly supported, and their inclusion at
    this point in time could put a significant implementation burden on
    libraries. It is expected that some of these dtypes - in particular
-   `bfloat16`, `complex64`, and `complex128` - will be included in a future
-   version of the standard._
+   `bfloat16` - will be included in a future version of the standard._
 
 5. The following topics are out of scope: I/O, polynomials, error handling,
    testing routines, building and packaging related functionality, methods of

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"),
 ]

src/array_api_stubs/_2021_12/array_object.py

@@ -453,7 +453,12 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array:
     def __getitem__(
         self: array,
         key: Union[
-            int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array
+            int,
+            slice,
+            ellipsis,
+            None,
+            Tuple[Union[int, slice, ellipsis, None], ...],
+            array,
         ],
         /,
     ) -> array:
@@ -464,7 +469,7 @@ def __getitem__(
         ----------
         self: array
             array instance.
-        key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], array]
+        key: Union[int, slice, ellipsis, None, Tuple[Union[int, slice, ellipsis, None], ...], array]
             index key.
 
         Returns