Change utils. Add docstrings

Author: roaffix

arrayfire/array_api/array_object.py

@@ -10,6 +10,7 @@
 from arrayfire.algorithm import count  # TODO refactor
 from arrayfire.array import _get_indices, _in_display_dims_limit  # TODO refactor
 
+from .device import PointerSource
 from .dtypes import CShape, Dtype
 from .dtypes import bool as af_bool
 from .dtypes import c_dim_t
@@ -20,7 +21,6 @@
 from .dtypes import int64 as af_int64
 from .dtypes import supported_dtypes
 from .dtypes import uint64 as af_uint64
-from .utils import PointerSource, to_str
 
 ShapeType = tuple[int, ...]
 _bcast_var = False  # HACK, TODO replace for actual bcast_var after refactoring
@@ -632,7 +632,7 @@ def _array_as_str(array: Array) -> str:
     arr_str = ctypes.c_char_p(0)
     # FIXME add description to passed arguments
     safe_call(backend.get().af_array_to_string(ctypes.pointer(arr_str), "", array.arr, 4, True))
-    py_str = to_str(arr_str)
+    py_str = _to_str(arr_str)
     safe_call(backend.get().af_free_host(arr_str))
     return py_str
 
@@ -662,6 +662,10 @@ def _c_api_value_to_dtype(value: int) -> Dtype:
     raise TypeError("There is no supported dtype that matches passed dtype C API value.")
 
 
+def _to_str(c_str: ctypes.c_char_p) -> str:
+    return str(c_str.value.decode("utf-8"))  # type: ignore[union-attr]
+
+
 def _str_to_dtype(value: int) -> Dtype:
     for dtype in supported_dtypes:
         if value == dtype.typecode or value == dtype.typename:

arrayfire/array_api/device.py

@@ -0,0 +1,10 @@
+import enum
+
+
+class PointerSource(enum.Enum):
+    """
+    Source of the pointer.
+    """
+    # FIXME
+    device = 0
+    host = 1

arrayfire/array_api/dtype_functions.py

@@ -0,0 +1,138 @@
+from .array_object import Array
+from .dtypes import Dtype
+
+# TODO implement functions
+
+
+def astype(x: Array, dtype: Dtype, /, *, copy: bool = True) -> Array:
+    """
+    Copies an array to a specified data type irrespective of Type Promotion Rules rules.
+
+    Parameters
+    ----------
+    x : Array
+        Array to cast.
+    dtype: Dtype
+        Desired data type.
+    copy: bool, optional
+        Specifies whether to copy an array when the specified dtype matches the data type of the input array x.
+        If True, a newly allocated array must always be returned. If False and the specified dtype matches the data
+        type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned.
+        Default: True.
+
+    Returns
+    -------
+    out : Array
+        An array having the specified data type. The returned array must have the same shape as x.
+
+    Note
+    ----
+    - Casting floating-point NaN and infinity values to integral data types is not specified and is
+    implementation-dependent.
+    - Casting a complex floating-point array to a real-valued data type should not be permitted.
+    Historically, when casting a complex floating-point array to a real-valued data type, libraries such as NumPy have
+    discarded imaginary components such that, for a complex floating-point array x, astype(x) equals astype(real(x))).
+    This behavior is considered problematic as the choice to discard the imaginary component is arbitrary and
+    introduces more than one way to achieve the same outcome (i.e., for a complex floating-point array x, astype(x) and
+    astype(real(x)) versus only astype(imag(x))). Instead, in order to avoid ambiguity and to promote clarity, this
+    specification requires that array API consumers explicitly express which component should be cast to a specified
+    real-valued data type.
+    - When casting a boolean input array to a real-valued data type, a value of True must cast to a real-valued number
+    equal to 1, and a value of False must cast to a real-valued number equal to 0.
+    When casting a boolean input array to a complex floating-point data type, a value of True must cast to a complex
+    number equal to 1 + 0j, and a value of False must cast to a complex number equal to 0 + 0j.
+    - 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.
+    When casting a complex floating-point array to bool, a value of 0 + 0j must cast to False, and all other values
+    must cast to True.
+    """
+    return NotImplemented
+
+
+def can_cast(from_: Dtype | Array, to: Dtype, /) -> bool:
+    """
+    Determines if one data type can be cast to another data type according Type Promotion Rules rules.
+
+    Parameters
+    ----------
+    from_ : Dtype | Array
+        Input data type or array from which to cast.
+    to : Dtype
+        Desired data type.
+
+    Returns
+    -------
+    out : bool
+        True if the cast can occur according to Type Promotion Rules rules; otherwise, False.
+    """
+    return NotImplemented
+
+
+def finfo(type: Dtype | Array, /):  # type: ignore[no-untyped-def]
+    # TODO add docstring, implementation and return type -> finfo_object
+    return NotImplemented
+
+
+def iinfo(type: Dtype | Array, /):  # type: ignore[no-untyped-def]
+    # TODO add docstring, implementation and return type -> iinfo_object
+    return NotImplemented
+
+
+def isdtype(dtype: Dtype, kind: Dtype | str | tuple[Dtype | str, ...]) -> bool:
+    """
+    Returns a boolean indicating whether a provided dtype is of a specified data type “kind”.
+
+    Parameters
+    ----------
+    dtype : Dtype
+        The input dtype.
+    kind : Dtype | str | tuple[Dtype | str, ...]
+        Data type kind.
+        - If kind is a dtype, the function must return a boolean indicating whether the input dtype is equal to the
+        dtype specified by kind.
+        - If kind is a string, the function must return a boolean indicating whether the input dtype is of a specified
+        data type kind. The following dtype kinds must be supported:
+            - bool: boolean data types (e.g., bool).
+            - signed integer: signed integer data types (e.g., int8, int16, int32, int64).
+            - unsigned integer: unsigned integer data types (e.g., uint8, uint16, uint32, uint64).
+            - integral: integer data types. Shorthand for ('signed integer', 'unsigned integer').
+            - real floating: real-valued floating-point data types (e.g., float32, float64).
+            - complex floating: complex floating-point data types (e.g., complex64, complex128).
+            - numeric: numeric data types. Shorthand for ('integral', 'real floating', 'complex floating').
+        - If kind is a tuple, the tuple specifies a union of dtypes and/or kinds, and the function must return a
+        boolean indicating whether the input dtype is either equal to a specified dtype or belongs to at least one
+        specified data type kind.
+
+    Returns
+    -------
+    out : bool
+        Boolean indicating whether a provided dtype is of a specified data type kind.
+
+    Note
+    ----
+    - A conforming implementation of the array API standard is not limited to only including the dtypes described in
+    this specification in the required data type kinds. For example, implementations supporting float16 and bfloat16
+    can include float16 and bfloat16 in the real floating data type kind. Similarly, implementations supporting int128
+    can include int128 in the signed integer data type kind.
+    In short, conforming implementations may extend data type kinds; however, data type kinds must remain consistent
+    (e.g., only integer dtypes may belong to integer data type kinds and only floating-point dtypes may belong to
+    floating-point data type kinds), and extensions must be clearly documented as such in library documentation.
+    """
+    return NotImplemented
+
+
+def result_type(*arrays_and_dtypes: Dtype | Array) -> Dtype:
+    """
+    Returns the dtype that results from applying the type promotion rules (see Type Promotion Rules) to the arguments.
+
+    Parameters
+    ----------
+    arrays_and_dtypes: Dtype | Array
+        An arbitrary number of input arrays and/or dtypes.
+
+    Returns
+    -------
+    out : Dtype
+        The dtype resulting from an operation involving the input arrays and dtypes.
+    """
+    return NotImplemented

arrayfire/array_api/utils.py

@@ -1,15 +1,79 @@
-import ctypes
-import enum
+from .array_object import Array
 
+# TODO implement functions
 
-class PointerSource(enum.Enum):
+
+def all(x: Array, /, *, axis: None | int | tuple[int, ...] = None, keepdims: bool = False) -> Array:
     """
-    Source of the pointer
+    Tests whether all input array elements evaluate to True along a specified axis.
+
+    Parameters
+    ----------
+    x : Array
+        Input array.
+    axis :  None | int | tuple[int, ...], optional
+        Axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction must be
+        performed over the entire array. If a tuple of integers, logical AND reductions must be performed over
+        multiple axes. A valid axis must be an integer on the interval [-N, N), where N is the rank (number of
+        dimensions) of x. If an axis is specified as a negative integer, the function must determine the axis along
+        which to perform a reduction by counting backward from the last dimension (where -1 refers to the last
+        dimension). If provided an invalid axis, the function must raise an exception. Default: None.
+    keepdims : bool, optional
+        If True, the reduced axes (dimensions) must be included in the result as singleton dimensions, and,
+        accordingly, the result must be compatible with the input array (see Broadcasting). Otherwise, if False,
+        the reduced axes (dimensions) must not be included in the result. Default: False.
+
+    Returns
+    -------
+    out : Array
+        If a logical AND reduction was performed over the entire array, the returned array must be a zero-dimensional
+        array containing the test result; otherwise, the returned array must be a non-zero-dimensional array
+        containing the test results. The returned array must have a data type of bool.
+
+    Note
+    ----
+    - Positive infinity, negative infinity, and NaN must evaluate to True.
+    - If x has a complex floating-point data type, elements having a non-zero component (real or imaginary) must
+    evaluate to True.
+    - If x is an empty array or the size of the axis (dimension) along which to evaluate elements is zero, the test
+    result must be True.
     """
-    # FIXME
-    device = 0
-    host = 1
+    return NotImplemented
 
 
-def to_str(c_str: ctypes.c_char_p) -> str:
-    return str(c_str.value.decode("utf-8"))  # type: ignore[union-attr]
+def any(x: Array, /, *, axis: None | int | tuple[int, ...] = None, keepdims: bool = False) -> Array:
+    """
+    Tests whether any input array element evaluates to True along a specified axis.
+
+    Parameters
+    ----------
+    x : Array
+        Input array.
+    axis :  None | int | tuple[int, ...], optional
+        Axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction must be
+        performed over the entire array. If a tuple of integers, logical OR reductions must be performed over
+        multiple axes. A valid axis must be an integer on the interval [-N, N), where N is the rank (number of
+        dimensions) of x. If an axis is specified as a negative integer, the function must determine the axis along
+        which to perform a reduction by counting backward from the last dimension (where -1 refers to the last
+        dimension). If provided an invalid axis, the function must raise an exception. Default: None.
+    keepdims : bool, optional
+        If True, the reduced axes (dimensions) must be included in the result as singleton dimensions, and,
+        accordingly, the result must be compatible with the input array (see Broadcasting). Otherwise, if False,
+        the reduced axes (dimensions) must not be included in the result. Default: False.
+
+    Returns
+    -------
+    out : Array
+        If a logical OR reduction was performed over the entire array, the returned array must be a zero-dimensional
+        array containing the test result; otherwise, the returned array must be a non-zero-dimensional array
+        containing the test results. The returned array must have a data type of bool.
+
+    Note
+    ----
+    - Positive infinity, negative infinity, and NaN must evaluate to True.
+    - If x has a complex floating-point data type, elements having a non-zero component (real or imaginary) must
+    evaluate to True.
+    - If x is an empty array or the size of the axis (dimension) along which to evaluate elements is zero, the test
+    result must be False.
+    """
+    return NotImplemented