Align casting methods with Python behaviour

spec/API_specification/array_api/array_object.py

@@ -224,19 +224,51 @@ def __array_namespace__(self: array, /, *, api_version: Optional[str] = None) ->
 
     def __bool__(self: array, /) -> bool:
         """
-        Converts a zero-dimensional boolean array to a Python ``bool`` object.
+        Converts a zero-dimensional array to a Python ``bool`` object.
+
+        **Special cases**
+
+        For real-valued floating-point operands,
+
+        - If ``self`` is ``NaN``, the result is ``True``.
+        - If ``self`` is either ``+infinity`` or ``-infinity``, the result is ``True``.
+        - If ``self`` is either ``+0`` or ``-0``, the result is ``False``.
+
+        For complex floating-point operands, special cases must be handled as if the operation is implemented as ``bool(real(self)) and bool(imag(self))``.
 
         Parameters
         ----------
         self: array
-            zero-dimensional array instance. Must have a boolean data type.
+            zero-dimensional array instance.
 
         Returns
         -------
         out: bool
             a Python ``bool`` object representing the single element of the array.
         """
 
+    def __complex__(self: array, /) -> complex:
+        """
+        Converts a zero-dimensional array to a Python ``complex`` object.
+
+        **Special cases**
+
+        For boolean operands,
+
+        - If ``self`` is ``True``, the result is ``1+0j``.
+        - If ``self`` is ``False``, the result is ``0+0j``.
+
+        Parameters
+        ----------
+        self: array
+            zero-dimensional array instance.
+
+        Returns
+        -------
+        out: complex
+            a Python ``complex`` object representing the single element of the array instance. If ``self`` has a real-valued or boolean data type, the real component of the return value must equal the element of ``self`` and the imaginary component must be ``0``.
+        """
+
     def __dlpack__(self: array, /, *, stream: Optional[Union[int, Any]] = None) -> PyCapsule:
         """
         Exports the array for consumption by :func:`~array_api.from_dlpack` as a DLPack capsule.
@@ -341,12 +373,22 @@ def __eq__(self: array, other: Union[int, float, bool, array], /) -> array:
 
     def __float__(self: array, /) -> float:
         """
-        Converts a zero-dimensional floating-point array to a Python ``float`` object.
+        Converts a zero-dimensional array to a Python ``float`` object.
+
+        .. note::
+           Casting integer values outside the representable bounds of Python's float type is not specified and is implementation-dependent.
+
+        **Special cases**
+
+        For boolean operands,
+
+        - If ``self`` is ``True``, the result is ``1``.
+        - If ``self`` is ``False``, the result is ``0``.
 
         Parameters
         ----------
         self: array
-            zero-dimensional array instance. Must have a real-valued floating-point data type.
+            zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function must raise a ``TypeError``.
 
         Returns
         -------
@@ -483,7 +525,7 @@ def __index__(self: array, /) -> int:
         Parameters
         ----------
         self: array
-            zero-dimensional array instance. Must have an integer data type.
+            zero-dimensional array instance. Should have an integer data type. If ``self`` has a floating-point data type, the function must raise a ``TypeError``.
 
         Returns
         -------
@@ -493,17 +535,37 @@ def __index__(self: array, /) -> int:
 
     def __int__(self: array, /) -> int:
         """
-        Converts a zero-dimensional integer array to a Python ``int`` object.
+        Converts a zero-dimensional array to a Python ``int`` object.
+
+        **Special cases**
+
+        For boolean operands,
+
+        - If ``self`` is ``True``, the result is ``1``.
+        - If ``self`` is ``False``, the result is ``0``.
+
+        For floating-point operands,
+
+        - If ``self`` is a finite number, the result is the integer part of ``self``.
+        - If ``self`` is ``-0``, the result is ``0``.
 
         Parameters
         ----------
         self: array
-            zero-dimensional array instance. Must have an integer data type.
+            zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function must raise a ``TypeError``.
 
         Returns
         -------
         out: int
             a Python ``int`` object representing the single element of the array instance.
+
+
+        **Raises**
+
+        For floating-point operands,
+
+        - If ``self`` is either ``+infinity`` or ``-infinity``, raise ``OverflowError``.
+        - If ``self`` is ``NaN``, raise ``ValueError``.
         """
 
     def __invert__(self: array, /) -> array:

spec/API_specification/array_object.rst

@@ -283,6 +283,7 @@ Methods
    array.__and__
    array.__array_namespace__
    array.__bool__
+   array.__complex__
    array.__dlpack__
    array.__dlpack_device__
    array.__eq__