Merge branch 'main' of https://github.com/pydata-apis/array-api into add-real

Author: kgryte

.github/workflows/pages.yml

@@ -31,10 +31,6 @@ on:
     branches:
       - main
 
-  pull_request:
-    branches:
-      - "**"
-
 # Workflow jobs:
 jobs:
 
@@ -128,5 +124,5 @@ jobs:
       - name: 'Push changes'
         if: success()
         run: |
-          git push "https://$GITHUB_ACTOR:[email protected]/${{ github.repository }}.git"
+          git push origin gh-pages
         timeout-minutes: 10

.gitignore

@@ -30,3 +30,4 @@ node_modules/
 __pycache__/
 *.pyc
 spec/**/generated
+tmp/

requirements.txt

@@ -4,3 +4,4 @@ myst-parser
 sphinx_markdown_tables
 sphinx_copybutton
 docutils<0.18
+sphinx-math-dollar

spec/API_specification/array_api/__init__.py

@@ -0,0 +1,14 @@
+from .array_object import *
+from .constants import *
+from .creation_functions import *
+from .data_type_functions import *
+import array_api.data_types as dtype
+from .elementwise_functions import *
+from .linear_algebra_functions import *
+from .manipulation_functions import *
+from .searching_functions import *
+from .set_functions import *
+from .sorting_functions import *
+from .statistical_functions import *
+from .utility_functions import *
+from . import linalg

spec/API_specification/signatures/_types.py renamed to spec/API_specification/array_api/_types.py

@@ -14,7 +14,7 @@ def arange(start: Union[int, float], /, stop: Optional[Union[int, float]] = None
     step: Union[int, float]
         the distance between two adjacent elements (``out[i+1] - out[i]``). Must not be ``0``; may be negative, this results in an empty array if ``stop >= start``. Default: ``1``.
     dtype: Optional[dtype]
-        output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``start``, ``stop`` and ``step``. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type ``float``, then the output array dtype must be the default floating-point data type. Default: ``None``.
+        output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``start``, ``stop`` and ``step``. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type ``float``, then the output array dtype must be the default real-valued floating-point data type. Default: ``None``.
     device: Optional[device]
         device on which to place the created array. Default: ``None``.
 
@@ -28,13 +28,13 @@ def arange(start: Union[int, float], /, stop: Optional[Union[int, float]] = None
         a one-dimensional array containing evenly spaced values. The length of the output array must be ``ceil((stop-start)/step)`` if ``stop - start`` and ``step`` have the same sign, and length ``0`` otherwise.
     """
 
-def asarray(obj: Union[array, bool, int, float, NestedSequence, SupportsBufferProtocol], /, *, dtype: Optional[dtype] = None, device: Optional[device] = None, copy: Optional[bool] = None) -> array:
-    """
+def asarray(obj: Union[array, bool, int, float, complex, NestedSequence, SupportsBufferProtocol], /, *, dtype: Optional[dtype] = None, device: Optional[device] = None, copy: Optional[bool] = None) -> array:
+    r"""
     Convert the input to an array.
 
     Parameters
     ----------
-    obj: Union[array, bool, int, float, NestedSequence[bool | int | float], SupportsBufferProtocol]
+    obj: Union[array, bool, int, float, complex, NestedSequence[bool | int | float | complex], SupportsBufferProtocol]
         object to be converted to an array. May be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting the Python buffer protocol.
 
         .. admonition:: Tip
@@ -43,18 +43,19 @@ def asarray(obj: Union[array, bool, int, float, NestedSequence, SupportsBufferPr
            An object supporting the buffer protocol can be turned into a memoryview through ``memoryview(obj)``.
 
     dtype: Optional[dtype]
-        output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from the data type(s) in ``obj``. If all input values are Python scalars, then
+        output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from the data type(s) in ``obj``. If all input values are Python scalars, then, in order of precedence,
 
         -   if all values are of type ``bool``, the output data type must be ``bool``.
-        -   if the values are a mixture of ``bool``\s and ``int``, the output data type must be the default integer data type.
-        -   if one or more values are ``float``\s, the output data type must be the default floating-point data type.
+        -   if all values are of type ``int`` or are a mixture of ``bool`` and ``int``, the output data type must be the default integer data type.
+        -   if one or more values are ``complex`` numbers, the output data type must be the default complex floating-point data type.
+        -   if one or more values are ``float``\s, the output data type must be the default real-valued floating-point data type.
 
         Default: ``None``.
 
         .. admonition:: Note
            :class: note
 
-           If ``dtype`` is not ``None``, then array conversions should obey :ref:`type-promotion` rules. Conversions not specified according to :ref:`type-promotion` rules may or may not be permitted by a conforming array library. To perform an explicit cast, use :func:`signatures.data_type_functions.astype`.
+           If ``dtype`` is not ``None``, then array conversions should obey :ref:`type-promotion` rules. Conversions not specified according to :ref:`type-promotion` rules may or may not be permitted by a conforming array library. To perform an explicit cast, use :func:`array_api.astype`.
 
         .. note::
            If an input value exceeds the precision of the resolved output array data type, behavior is left unspecified and, thus, implementation-defined.
@@ -79,7 +80,7 @@ def empty(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None,
     shape: Union[int, Tuple[int, ...]]
         output array shape.
     dtype: Optional[dtype]
-        output array data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``.
+        output array data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``.
     device: Optional[device]
         device on which to place the created array. Default: ``None``.
 
@@ -112,6 +113,9 @@ def eye(n_rows: int, n_cols: Optional[int] = None, /, *, k: int = 0, dtype: Opti
     """
     Returns a two-dimensional array with ones on the ``k``\th diagonal and zeros elsewhere.
 
+    .. note::
+       An output array having a complex floating-point data type must have the value ``1 + 0j`` along the ``k``\th diagonal and ``0 + 0j`` elsewhere. 
+
     Parameters
     ----------
     n_rows: int
@@ -121,7 +125,7 @@ def eye(n_rows: int, n_cols: Optional[int] = None, /, *, k: int = 0, dtype: Opti
     k: int
         index of the diagonal. A positive value refers to an upper diagonal, a negative value to a lower diagonal, and ``0`` to the main diagonal. Default: ``0``.
     dtype: Optional[dtype]
-        output array data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``.
+        output array data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``.
     device: Optional[device]
         device on which to place the created array. Default: ``None``.
 
@@ -151,18 +155,23 @@ def from_dlpack(x: object, /) -> array:
            The returned array may be either a copy or a view. See :ref:`data-interchange` for details.
     """
 
-def full(shape: Union[int, Tuple[int, ...]], fill_value: Union[int, float], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array:
+def full(shape: Union[int, Tuple[int, ...]], fill_value: Union[bool, int, float, complex], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array:
     """
     Returns a new array having a specified ``shape`` and filled with ``fill_value``.
 
     Parameters
     ----------
     shape: Union[int, Tuple[int, ...]]
         output array shape.
-    fill_value: Union[int, float]
+    fill_value: Union[bool, int, float, complex]
         fill value.
     dtype: Optional[dtype]
-        output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``fill_value``. If the fill value is an ``int``, the output array data type must be the default integer data type. If the fill value is a ``float``, the output array data type must be the default floating-point data type. If the fill value is a ``bool``, the output array must have boolean data type. Default: ``None``.
+        output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``fill_value`` according to the following rules:
+
+        - If the fill value is an ``int``, the output array data type must be the default integer data type.
+        - If the fill value is a ``float``, the output array data type must be the default real-valued floating-point data type.
+        - If the fill value is a ``complex`` number, the output array data type must be the default complex floating-point data type.
+        - If the fill value is a ``bool``, the output array must have a boolean data type. Default: ``None``.
 
         .. note::
            If the ``fill_value`` exceeds the precision of the resolved default output array data type, behavior is left unspecified and, thus, implementation-defined.
@@ -176,15 +185,15 @@ def full(shape: Union[int, Tuple[int, ...]], fill_value: Union[int, float], *, d
         an array where every element is equal to ``fill_value``.
     """
 
-def full_like(x: array, /, fill_value: Union[int, float], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array:
+def full_like(x: array, /, fill_value: Union[bool, int, float, complex], *, dtype: Optional[dtype] = None, device: Optional[device] = None) -> array:
     """
     Returns a new array filled with ``fill_value`` and having the same ``shape`` as an input array ``x``.
 
     Parameters
     ----------
     x: array
         input array from which to derive the output array shape.
-    fill_value: Union[int, float]
+    fill_value: Union[bool, int, float, complex]
         fill value.
     dtype: Optional[dtype]
         output array data type. If ``dtype`` is ``None``, the output array data type must be inferred from ``x``. Default: ``None``.
@@ -193,7 +202,7 @@ def full_like(x: array, /, fill_value: Union[int, float], *, dtype: Optional[dty
            If the ``fill_value`` exceeds the precision of the resolved output array data type, behavior is unspecified and, thus, implementation-defined.
 
         .. note::
-           If the ``fill_value`` has a data type (``int`` or ``float``) which is not of the same data type kind as the resolved output array data type (see :ref:`type-promotion`), behavior is unspecified and, thus, implementation-defined.
+           If the ``fill_value`` has a data type which is not of the same data type kind (boolean, integer, or floating-point) as the resolved output array data type (see :ref:`type-promotion`), behavior is unspecified and, thus, implementation-defined.
 
     device: Optional[device]
         device on which to place the created array. If ``device`` is ``None``, the output array device must be inferred from ``x``. Default: ``None``.
@@ -221,7 +230,7 @@ def linspace(start: Union[int, float], stop: Union[int, float], /, num: int, *,
     num: int
         number of samples. Must be a non-negative integer value; otherwise, the function must raise an exception.
     dtype: Optional[dtype]
-        output array data type. Should be a floating-point data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``.
+        output array data type. Should be a real-valued floating-point data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``.
     device: Optional[device]
         device on which to place the created array. Default: ``None``.
     endpoint: bool
@@ -234,10 +243,10 @@ def linspace(start: Union[int, float], stop: Union[int, float], /, num: int, *,
 
 
     .. note::
-       While this specification recommends that this function only return arrays having a floating-point data type, specification-compliant array libraries may choose to support output arrays having an integer data type (e.g., due to backward compatibility concerns). However, function behavior when generating integer output arrays is unspecified and, thus, is implementation-defined. Accordingly, using this function to generate integer output arrays is not portable.
+       While this specification recommends that this function only return arrays having a real-valued floating-point data type, specification-compliant array libraries may choose to support output arrays having an integer data type (e.g., due to backward compatibility concerns). However, function behavior when generating integer output arrays is unspecified and, thus, is implementation-defined. Accordingly, using this function to generate integer output arrays is not portable.
 
     .. note::
-       As mixed data type promotion is implementation-defined, behavior when ``start`` or ``stop`` exceeds the maximum safe integer of an output floating-point data type is implementation-defined. An implementation may choose to overflow or raise an exception.
+       As mixed data type promotion is implementation-defined, behavior when ``start`` or ``stop`` exceeds the maximum safe integer of an output real-valued floating-point data type is implementation-defined. An implementation may choose to overflow or raise an exception.
     """
 
 def meshgrid(*arrays: array, indexing: str = 'xy') -> List[array]:
@@ -270,12 +279,15 @@ def ones(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None, d
     """
     Returns a new array having a specified ``shape`` and filled with ones.
 
+    .. note::
+       An output array having a complex floating-point data type must contain complex numbers having a real component equal to one and an imaginary component equal to zero (i.e., ``1 + 0j``).  
+
     Parameters
     ----------
     shape: Union[int, Tuple[int, ...]]
         output array shape.
     dtype: Optional[dtype]
-        output array data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``.
+        output array data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``.
     device: Optional[device]
         device on which to place the created array. Default: ``None``.
 
@@ -289,6 +301,9 @@ def ones_like(x: array, /, *, dtype: Optional[dtype] = None, device: Optional[de
     """
     Returns a new array filled with ones and having the same ``shape`` as an input array ``x``.
 
+    .. note::
+       An output array having a complex floating-point data type must contain complex numbers having a real component equal to one and an imaginary component equal to zero (i.e., ``1 + 0j``).  
+
     Parameters
     ----------
     x: array
@@ -359,7 +374,7 @@ def zeros(shape: Union[int, Tuple[int, ...]], *, dtype: Optional[dtype] = None,
     shape: Union[int, Tuple[int, ...]]
         output array shape.
     dtype: Optional[dtype]
-        output array data type. If ``dtype`` is ``None``, the output array data type must be the default floating-point data type. Default: ``None``.
+        output array data type. If ``dtype`` is ``None``, the output array data type must be the default real-valued floating-point data type. Default: ``None``.
     device: Optional[device]
         device on which to place the created array. Default: ``None``.
 

spec/API_specification/signatures/array_object.py renamed to spec/API_specification/array_api/array_object.py

@@ -1,4 +1,4 @@
-from ._types import List, Tuple, Union, array, dtype, finfo_object, iinfo_object
+from ._types import Union, array, dtype, finfo_object, iinfo_object
 
 def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array:
     """
@@ -8,9 +8,9 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array:
        Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent.
 
     .. note::
-       When casting a boolean input array to a numeric data type, a value of ``True`` must cast to a numeric value equal to ``1``, and a value of ``False`` must cast to a numeric value equal to ``0``.
+       When casting a boolean input array to a real-valued data type, a value of ``True`` must cast to a numeric value equal to ``1``, and a value of ``False`` must cast to a numeric value equal to ``0``.
 
-       When casting a numeric input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``.
+       When casting a real-valued input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``.
 
     Parameters
     ----------
@@ -27,38 +27,6 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array:
         an array having the specified data type. The returned array must have the same shape as ``x``.
     """
 
-def broadcast_arrays(*arrays: array) -> List[array]:
-    """
-    Broadcasts one or more arrays against one another.
-
-    Parameters
-    ----------
-    arrays: array
-        an arbitrary number of to-be broadcasted arrays.
-
-    Returns
-    -------
-    out: List[array]
-        a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array.
-    """
-
-def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array:
-    """
-    Broadcasts an array to a specified shape.
-
-    Parameters
-    ----------
-    x: array
-        array to broadcast.
-    shape: Tuple[int, ...]
-        array shape. Must be compatible with ``x`` (see :ref:`broadcasting`). If the array is incompatible with the specified shape, the function should raise an exception.
-
-    Returns
-    -------
-    out: array
-        an array having a specified shape. Must have the same data type as ``x``.
-    """
-
 def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool:
     """
     Determines if one data type can be cast to another data type according :ref:`type-promotion` rules.
@@ -78,17 +46,17 @@ def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool:
 
 def finfo(type: Union[dtype, array], /) -> finfo_object:
     """
-    Machine limits for floating-point data types.
+    Machine limits for real-valued floating-point data types.
 
     Parameters
     ----------
     type: Union[dtype, array]
-        the kind of floating-point data-type about which to get information.
+        the kind of real-valued floating-point data-type about which to get information.
 
     Returns
     -------
     out: finfo object
-        an object having the followng attributes:
+        an object having the following attributes:
 
         - **bits**: *int*
 
@@ -123,7 +91,7 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object:
     Returns
     -------
     out: iinfo object
-        a class with that encapsules the following attributes:
+        an object having the following attributes:
 
         - **bits**: *int*
 
@@ -156,4 +124,4 @@ def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype:
         the dtype resulting from an operation involving the input arrays and dtypes.
     """
 
-__all__ = ['astype', 'broadcast_arrays', 'broadcast_to', 'can_cast', 'finfo', 'iinfo', 'result_type']
+__all__ = ['astype', 'can_cast', 'finfo', 'iinfo', 'result_type']

spec/API_specification/signatures/constants.py renamed to spec/API_specification/array_api/constants.py

@@ -17,4 +17,4 @@ def __eq__(self: dtype, other: dtype, /) -> bool:
         a boolean indicating whether the data type objects are equal.
     """
 
-all = [__eq__]
+__all__ = ['__eq__']