Merge branch 'main' into rfc_should_must

Author: ev-br

spec/draft/API_specification/type_promotion.rst

@@ -120,6 +120,9 @@ Notes
 .. note::
    Mixed integer and floating-point type promotion rules are not specified because behavior varies between implementations.
 
+
+.. _mixing-scalars-and-arrays:
+
 Mixing arrays with Python scalars
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/array_api_stubs/_2021_12/linalg.py

@@ -474,7 +474,7 @@ def trace(x: array, /, *, offset: int = 0) -> array:
     """
 
 
-def vecdot(x1: array, x2: array, /, *, axis: int = None) -> array:
+def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array:
     """
     Alias for :func:`~array_api.vecdot`.
     """

src/array_api_stubs/_2022_12/linalg.py

@@ -755,7 +755,7 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr
     """
 
 
-def vecdot(x1: array, x2: array, /, *, axis: int = None) -> array:
+def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array:
     """Alias for :func:`~array_api.vecdot`."""
 
 

src/array_api_stubs/_2023_12/linalg.py

@@ -781,7 +781,7 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr
     """
 
 
-def vecdot(x1: array, x2: array, /, *, axis: int = None) -> array:
+def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array:
     """Alias for :func:`~array_api.vecdot`."""
 
 

src/array_api_stubs/_draft/data_type_functions.py

@@ -209,20 +209,25 @@ def isdtype(
     """
 
 
-def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype:
+def result_type(
+    *arrays_and_dtypes: Union[array, int, float, complex, bool, dtype]
+) -> dtype:
     """
-    Returns the dtype that results from applying the type promotion rules (see :ref:`type-promotion`) to the arguments.
-
-    .. note::
-       If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific.
+    Returns the dtype that results from applying type promotion rules (see :ref:`type-promotion`) to the arguments.
 
     Parameters
     ----------
-    arrays_and_dtypes: Union[array, dtype]
-        an arbitrary number of input arrays and/or dtypes.
+    arrays_and_dtypes: Union[array, int, float, complex, bool, dtype]
+        an arbitrary number of input arrays, scalars, and/or dtypes.
 
     Returns
     -------
     out: dtype
-        the dtype resulting from an operation involving the input arrays and dtypes.
+        the dtype resulting from an operation involving the input arrays, scalars, and/or dtypes.
+
+    Notes
+    -----
+
+    -   At least one argument must be an array or a dtype.
+    -   If provided array and/or dtype arguments having mixed data type kinds (e.g., integer and floating-point), the returned dtype is unspecified and is implementation-dependent.
     """

src/array_api_stubs/_draft/indexing_functions.py

@@ -13,7 +13,7 @@ def take(x: array, indices: array, /, *, axis: Optional[int] = None) -> array:
     Parameters
     ----------
     x: array
-        input array.
+        input array. Should have one or more dimensions (axes).
     indices: array
         array indices. The array *must* be one-dimensional and have an integer data type.
 
@@ -33,6 +33,8 @@ def take(x: array, indices: array, /, *, axis: Optional[int] = None) -> array:
     Notes
     -----
 
+    -   When ``x`` is a zero-dimensional array, behavior is unspecified and thus implementation-defined.
+
     .. versionadded:: 2022.12
 
     .. versionchanged:: 2023.12

src/array_api_stubs/_draft/linalg.py

@@ -781,7 +781,7 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr
     """
 
 
-def vecdot(x1: array, x2: array, /, *, axis: int = None) -> array:
+def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array:
     """Alias for :func:`~array_api.vecdot`."""
 
 

src/array_api_stubs/_draft/searching_functions.py

@@ -168,21 +168,35 @@ def searchsorted(
     """
 
 
-def where(condition: array, x1: array, x2: array, /) -> array:
+def where(
+    condition: array,
+    x1: Union[array, int, float, complex, bool],
+    x2: Union[array, int, float, complex, bool],
+    /,
+) -> array:
     """
     Returns elements chosen from ``x1`` or ``x2`` depending on ``condition``.
 
     Parameters
     ----------
     condition: array
         when ``True``, yield ``x1_i``; otherwise, yield ``x2_i``. Should have a boolean data type. Must be compatible with ``x1`` and ``x2`` (see :ref:`broadcasting`).
-    x1: array
+    x1: Union[array, int, float, complex, bool]
         first input array. Must be compatible with ``condition`` and ``x2`` (see :ref:`broadcasting`).
-    x2: array
+    x2: Union[array, int, float, complex, bool]
         second input array. Must be compatible with ``condition`` and ``x1`` (see :ref:`broadcasting`).
 
     Returns
     -------
     out: array
         an array with elements from ``x1`` where ``condition`` is ``True``, and elements from ``x2`` elsewhere. The returned array *must* have a data type determined by :ref:`type-promotion` rules with the arrays ``x1`` and ``x2``.
+
+    Notes
+    -----
+
+    -   At least one of  ``x1`` and ``x2`` *must* be an array.
+    -   If either ``x1`` or ``x2`` is a scalar value, the returned array *must* have a data type determined according to :ref:`mixing-scalars-and-arrays`.
+
+    .. versionchanged:: 2024.12
+        Added support for scalar arguments.
     """