Add admonitions for new and changed APIs in 2022 version (#585)

- Add version changed to functions that were modified for complex support in 2022
- Add version added to functions created in 2022

Co-authored-by: Ralf Gommers <[email protected]>

Author: steff456

src/array_api_stubs/_draft/array_object.py

@@ -136,9 +136,14 @@ def __abs__(self: array, /) -> array:
         out: array
             an array containing the element-wise absolute value. If ``self`` has a real-valued data type, the returned array must have the same data type as ``self``. If ``self`` has a complex floating-point data type, the returned arrayed must have a real-valued floating-point data type whose precision matches the precision of ``self`` (e.g., if ``self`` is ``complex128``, then the returned array must have a ``float64`` data type).
 
+        Notes
+        -----
 
         .. note::
            Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.abs`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __add__(self: array, other: Union[int, float, array], /) -> array:
@@ -157,9 +162,14 @@ def __add__(self: array, other: Union[int, float, array], /) -> array:
         out: array
             an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`.
 
+        Notes
+        -----
 
         .. note::
            Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.add`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __and__(self: array, other: Union[int, bool, array], /) -> array:
@@ -228,6 +238,9 @@ def __bool__(self: array, /) -> bool:
         - 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 the logical AND of ``bool(real(self))`` and ``bool(imag(self))``.
+
+        .. versionchanged:: 2022.12
+            Added boolean and complex data type support.
         """
 
     def __complex__(self: array, /) -> complex:
@@ -260,6 +273,8 @@ def __complex__(self: array, /) -> complex:
         - If ``self`` is ``+infinity``, the result is ``+infinity + 0j``.
         - If ``self`` is ``-infinity``, the result is ``-infinity + 0j``.
         - If ``self`` is a finite number, the result is ``self + 0j``.
+
+        .. versionadded:: 2022.12
         """
 
     def __dlpack__(
@@ -326,6 +341,11 @@ def __dlpack__(
             errors are raised when export fails for other reasons (e.g., incorrect
             arguments passed or out of memory).
 
+        Notes
+        -----
+
+        .. versionchanged:: 2022.12
+            Added BufferError.
         """
 
     def __dlpack_device__(self: array, /) -> Tuple[Enum, int]:
@@ -401,6 +421,9 @@ def __float__(self: array, /) -> float:
 
         - If ``self`` is ``True``, the result is ``1``.
         - If ``self`` is ``False``, the result is ``0``.
+
+        .. versionchanged:: 2022.12
+            Added boolean and complex data type support.
         """
 
     def __floordiv__(self: array, other: Union[int, float, array], /) -> array:
@@ -551,6 +574,9 @@ def __int__(self: array, /) -> int:
 
         - If ``self`` is either ``+infinity`` or ``-infinity``, raise ``OverflowError``.
         - If ``self`` is ``NaN``, raise ``ValueError``.
+
+        .. versionchanged:: 2022.12
+            Added boolean and complex data type support.
         """
 
     def __invert__(self: array, /) -> array:
@@ -671,6 +697,8 @@ def __matmul__(self: array, other: array, /) -> array:
             -   if either ``self`` or ``other`` has more than two dimensions, an array having a shape determined by :ref:`broadcasting` ``shape(self)[:-2]`` against ``shape(other)[:-2]`` and containing the `conventional matrix product <https://en.wikipedia.org/wiki/Matrix_multiplication>`_ for each stacked matrix.
             -   The returned array must have a data type determined by :ref:`type-promotion`.
 
+        Notes
+        -----
 
         .. note::
            Results must equal the results returned by the equivalent function :func:`~array_api.matmul`.
@@ -682,6 +710,9 @@ def __matmul__(self: array, other: array, /) -> array:
         - if ``self`` is a one-dimensional array having shape ``(K,)``, ``other`` is an array having shape ``(..., L, N)``, and ``K != L``.
         - if ``self`` is an array having shape ``(..., M, K)``, ``other`` is a one-dimensional array having shape ``(L,)``, and ``K != L``.
         - if ``self`` is an array having shape ``(..., M, K)``, ``other`` is an array having shape ``(..., L, N)``, and ``K != L``.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __mod__(self: array, other: Union[int, float, array], /) -> array:
@@ -727,9 +758,14 @@ def __mul__(self: array, other: Union[int, float, array], /) -> array:
         out: array
             an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`.
 
+        Notes
+        -----
 
         .. note::
            Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.multiply`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __ne__(self: array, other: Union[int, float, bool, array], /) -> array:
@@ -749,8 +785,14 @@ def __ne__(self: array, other: Union[int, float, bool, array], /) -> array:
             an array containing the element-wise results. The returned array must have a data type of ``bool`` (i.e., must be a boolean array).
 
 
+        Notes
+        -----
+
         .. note::
            Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.not_equal`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __neg__(self: array, /) -> array:
@@ -773,9 +815,14 @@ def __neg__(self: array, /) -> array:
         out: array
             an array containing the evaluated result for each element in ``self``. The returned array must have a data type determined by :ref:`type-promotion`.
 
+        Notes
+        -----
 
         .. note::
            Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.negative`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __or__(self: array, other: Union[int, bool, array], /) -> array:
@@ -813,9 +860,14 @@ def __pos__(self: array, /) -> array:
         out: array
             an array containing the evaluated result for each element. The returned array must have the same data type as ``self``.
 
+        Notes
+        -----
 
         .. note::
            Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.positive`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __pow__(self: array, other: Union[int, float, array], /) -> array:
@@ -839,9 +891,14 @@ def __pow__(self: array, other: Union[int, float, array], /) -> array:
         out: array
             an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`.
 
+        Notes
+        -----
 
         .. note::
            Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.pow`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __rshift__(self: array, other: Union[int, array], /) -> array:
@@ -913,9 +970,14 @@ def __sub__(self: array, other: Union[int, float, array], /) -> array:
         out: array
             an array containing the element-wise differences. The returned array must have a data type determined by :ref:`type-promotion`.
 
+        Notes
+        -----
 
         .. note::
            Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.subtract`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __truediv__(self: array, other: Union[int, float, array], /) -> array:
@@ -939,9 +1001,14 @@ def __truediv__(self: array, other: Union[int, float, array], /) -> array:
         out: array
             an array containing the element-wise results. The returned array should have a floating-point data type determined by :ref:`type-promotion`.
 
+        Notes
+        -----
 
         .. note::
            Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.divide`.
+
+        .. versionchanged:: 2022.12
+            Added complex data type support.
         """
 
     def __xor__(self: array, other: Union[int, bool, array], /) -> array:

src/array_api_stubs/_draft/creation_functions.py

@@ -97,6 +97,12 @@ def asarray(
     -------
     out: array
         an array containing the data from ``obj``.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -179,6 +185,12 @@ def eye(
     -------
     out: array
         an array where all elements are equal to zero, except for the ``k``\th diagonal, whose values are equal to one.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -237,6 +249,12 @@ def full(
     -------
     out: array
         an array where every element is equal to ``fill_value``.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -273,6 +291,12 @@ def full_like(
     -------
     out: array
         an array having the same shape as ``x`` and where every element is equal to ``fill_value``.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -334,12 +358,17 @@ def linspace(
     out: array
         a one-dimensional array containing evenly spaced values.
 
+    Notes
+    -----
 
     .. 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.
 
     .. 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.
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -367,6 +396,12 @@ def meshgrid(*arrays: array, indexing: str = "xy") -> List[array]:
         Similarly, for the three-dimensional case with input one-dimensional arrays of length ``M``, ``N``, and ``P``, if matrix indexing ``ij``, then each returned array must have shape ``(M, N, P)``, and, if Cartesian indexing ``xy``, then each returned array must have shape ``(N, M, P)``.
 
         Each returned array should have the same data type as the input arrays.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -395,6 +430,12 @@ def ones(
     -------
     out: array
         an array containing ones.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -420,6 +461,12 @@ def ones_like(
     -------
     out: array
         an array having the same shape as ``x`` and filled with ones.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 

src/array_api_stubs/_draft/data_type_functions.py

@@ -36,6 +36,12 @@ def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array:
     -------
     out: array
         an array having the specified data type. The returned array must have the same shape as ``x``.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -97,6 +103,14 @@ def finfo(type: Union[dtype, array], /) -> finfo_object:
         - **dtype**: dtype
 
           real-valued floating-point data type.
+
+          .. versionadded:: 2022.12
+
+    Notes
+    -----
+
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """
 
 
@@ -129,6 +143,8 @@ def iinfo(type: Union[dtype, array], /) -> iinfo_object:
         - **dtype**: dtype
 
           integer data type.
+
+          .. versionadded:: 2022.12
     """
 
 
@@ -167,6 +183,11 @@ def isdtype(
     -------
     out: bool
         boolean indicating whether a provided dtype is of a specified data type kind.
+
+    Notes
+    -----
+
+    .. versionadded:: 2022.12
     """