diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5d69bbc23..0919472d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,172 @@
This changelog is organized by specification version and notes all changes with respect to the previous version. Within the section for a specific version (e.g., v2022.12), separate sections are used for (a) changes to existing APIs and requirements, (b) new APIs and new requirements, and (c) errata.
+## v2024.12
+
+### Updates
+
+> Updates to existing APIs and requirements.
+
+#### Normative
+
+- Clarify that conforming implementations may support additional arguments beyond those described in the Array API specification ([gh-870](https://github.com/data-apis/array-api/pull/870))
+- Clarify accuracy requirements for operations involving complex numbers ([gh-882](https://github.com/data-apis/array-api/pull/882))
+- Clarify expected results for in-place operations in conforming array libraries which do not support array mutation ([gh-895](https://github.com/data-apis/array-api/pull/895))
+
+#### APIs
+
+- `__dlpack__`: clarify the expected behavior of the `copy` keyword argument when `copy=True` ([gh-906](https://github.com/data-apis/array-api/pull/906))
+- `__eq__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `__ge__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `__getitem__`: clarify that iteration is defined for one-dimensional arrays ([gh-821](https://github.com/data-apis/array-api/pull/821))
+- `__gt__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `__le__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `__lt__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `__ne__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `asarray`: clarify the expected behavior of the `copy` keyword argument when `copy=True` ([gh-906](https://github.com/data-apis/array-api/pull/906))
+- `astype`: clarify the expected behavior of the `copy` keyword argument when `copy=True` ([gh-906](https://github.com/data-apis/array-api/pull/906))
+- `clip`: specify behavior when one of the operands is `NaN` ([gh-813](https://github.com/data-apis/array-api/pull/813); backported to v2023.12 revision of the Array API specification)
+- `clip`: clarify behavior when arguments have different data types ([gh-896](https://github.com/data-apis/array-api/pull/896))
+- `conj`: add support for real-valued arrays ([gh-884](https://github.com/data-apis/array-api/pull/884))
+- `cumulative_sum`: clarify that behavior when providing a zero-dimensional array is unspecified ([gh-851](https://github.com/data-apis/array-api/pull/851))
+- `equal`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `greater`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `greater_equal`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `less`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `less_equal`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `mean`: add support for complex floating-point data types ([gh-850](https://github.com/data-apis/array-api/pull/850))
+- `not_equal`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
+- `real`: add support for real-valued arrays ([gh-884](https://github.com/data-apis/array-api/pull/884))
+- `reshape`: clarify the expected behavior of the `copy` keyword argument when `copy=True` ([gh-906](https://github.com/data-apis/array-api/pull/906))
+- `sqrt`: clarify that results must be correctly rounded according to IEEE 754 ([gh-882](https://github.com/data-apis/array-api/pull/882))
+- `take`: clarify that behavior when provided a zero-dimensional input array is unspecified ([gh-876](https://github.com/data-apis/array-api/pull/876))
+- `take`: clarify support for negative indices ([gh-894](https://github.com/data-apis/array-api/pull/894))
+
+##### Scalar Argument Support
+
+The following APIs were updated to support both scalar and array arguments for one or more arguments:
+
+- `add` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `atan2` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `bitwise_and` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `bitwise_left_shift` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `bitwise_or` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `bitwise_right_shift` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `bitwise_xor` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `copysign` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `divide` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `equal` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `floor_divide` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `greater` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `greater_equal` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `hypot` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `less` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `less_equal` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `logaddexp` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `logical_and` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `logical_or` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `logical_xor` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `maximum` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `minimum` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `multiply` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `nextafter` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `not_equal` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `pow` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `remainder` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `result_type` ([gh-873](https://github.com/data-apis/array-api/pull/873))
+- `subtract` ([gh-862](https://github.com/data-apis/array-api/pull/862))
+- `where` ([gh-860](https://github.com/data-apis/array-api/pull/860))
+
+#### Extensions
+
+> Updates to APIs and requirements included as part of specification extensions.
+
+- `fft.fftfreq`: add `dtype` keyword argument ([gh-885](https://github.com/data-apis/array-api/pull/885))
+- `fft.rfftfreq`: add `dtype` keyword argument ([gh-885](https://github.com/data-apis/array-api/pull/885))
+
+* * *
+
+### Additions
+
+> New APIs and requirements added to the specification.
+
+#### Normative
+
+- Add support for integer array indexing ([gh-900](https://github.com/data-apis/array-api/pull/900))
+
+#### APIs
+
+The following APIs were added to the specification:
+
+- `count_nonzero`: count the number of array elements which are non-zero ([gh-803](https://github.com/data-apis/array-api/pull/803))
+- `cumulative_prod`: calculate the cumulative product ([gh-793](https://github.com/data-apis/array-api/pull/793))
+- `diff`: calculate the n-th discrete forward difference along a specified axis ([gh-791](https://github.com/data-apis/array-api/pull/791), [gh-881](https://github.com/data-apis/array-api/pull/881))
+- `nextafter`: return the next representable floating-point value for each element in an array ([gh-792](https://github.com/data-apis/array-api/pull/792))
+- `reciprocal`: return the reciprocal for each element in an array ([gh-802](https://github.com/data-apis/array-api/pull/802))
+- `take_along_axis`: return elements from an array at locations specified by one-dimensional indices along an axis ([gh-816](https://github.com/data-apis/array-api/pull/816))
+
+#### Inspection APIs
+
+The following inspection APIs were added to the specification:
+
+- `max dimensions`: return the maximum number of supported dimensions ([gh-763](https://github.com/data-apis/array-api/pull/763) and [gh-809](https://github.com/data-apis/array-api/pull/809))
+
+* * *
+
+### Breaking Changes
+
+The following is a list of breaking changes relative to the previous version of the specification:
+
+#### Normative
+
+- An operation involving a Python `complex` scalar and a real-valued floating-point arrays must be equivalent to an operation involving a zero-dimensional array having a complex floating-point data type and a real-valued floating-point array ([gh-871](https://github.com/data-apis/array-api/pull/871))
+
+#### APIs
+
+- `can_cast`: application of type promotion rules must account for device context ([gh-889](https://github.com/data-apis/array-api/pull/889))
+- `result_type`: application of type promotion rules must account for device context ([gh-889](https://github.com/data-apis/array-api/pull/889))
+
+* * *
+
+### Errata
+
+The following is a list of fixes and points of clarification with regard to the previous version of the specification:
+
+- `__add__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
+- `__bool__`: fix typo in special case notes ([gh-785](https://github.com/data-apis/array-api/pull/785))
+- `__dlpack__`: resolve conflicting exception guidance ([gh-887](https://github.com/data-apis/array-api/pull/887))
+- `__eq__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
+- `__getitem__`: clarify required indexing semantics ([gh-821](https://github.com/data-apis/array-api/pull/821))
+- `__mul__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
+- `__ne__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
+- `__pow__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
+- `__setitem__`: clarify required indexing semantics ([gh-821](https://github.com/data-apis/array-api/pull/821))
+- `__setitem__`: fix typing for `value` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
+- `__sub__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
+- `__truediv__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
+- `broadcast_to`: clarify broadcast behavior ([gh-888](https://github.com/data-apis/array-api/pull/888))
+- `broadcast_to`: clarify required exception behavior ([gh-897](https://github.com/data-apis/array-api/pull/897))
+- `clip`: clarify that the operation is only defined when elements in `min` and `max` are inside the bounds of the input array data type ([gh-814](https://github.com/data-apis/array-api/pull/814))
+- `clip`: fix typo in parameter description ([gh-896](https://github.com/data-apis/array-api/pull/896))
+- `copysign`: fix formatting of special cases ([gh-806](https://github.com/data-apis/array-api/pull/806))
+- `fft.fft`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
+- `fft.ifft`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
+- `fft.fftn`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
+- `fft.ifftn`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
+- `fft.irfft`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
+- `fft.irfftn`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
+- `fft.hfft`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
+- `linalg.solve`: clarify broadcasting semantics and output shape ([gh-810](https://github.com/data-apis/array-api/pull/810))
+- `nonzero`: fix return type ([gh-803](https://github.com/data-apis/array-api/pull/803) and [gh-https://github.com/data-apis/array-api/pull/904](https://github.com/data-apis/array-api/pull/904))
+- `searchsorted`: fix incorrect boundary conditions ([gh-898](https://github.com/data-apis/array-api/pull/898))
+- `sign`: fix equation in function description ([gh-844](https://github.com/data-apis/array-api/pull/844))
+- `tile`: fix missing return type ([gh-798](https://github.com/data-apis/array-api/pull/798))
+- `unstack`: fix typo in function description ([gh-810](https://github.com/data-apis/array-api/pull/810))
+- `vecdot`: fix regression in default value for `axis` keyword argument ([gh-880](https://github.com/data-apis/array-api/pull/880))
+- `where`: clarify that the `condition` argument should have a boolean data type ([gh-868](https://github.com/data-apis/array-api/pull/868))
+
+* * *
+
## v2023.12
### Updates
diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py
index ba5f99851..c91bba33d 100644
--- a/src/array_api_stubs/_draft/array_object.py
+++ b/src/array_api_stubs/_draft/array_object.py
@@ -460,10 +460,13 @@ def __dlpack__(
Added BufferError.
.. versionchanged:: 2023.12
- Added the ``max_version``, ``dl_device``, and ``copy`` keywords.
+ Added the ``max_version``, ``dl_device``, and ``copy`` keyword arguments.
.. versionchanged:: 2023.12
Added recommendation for handling read-only arrays.
+
+ .. versionchanged:: 2024.12
+ Resolved conflicting exception guidance.
"""
def __dlpack_device__(self: array, /) -> Tuple[Enum, int]:
@@ -518,6 +521,9 @@ def __eq__(self: array, other: Union[int, float, complex, bool, array], /) -> ar
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
"""
def __float__(self: array, /) -> float:
@@ -604,6 +610,9 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array:
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater_equal`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
"""
def __getitem__(
@@ -639,6 +648,8 @@ def __getitem__(
- See :ref:`indexing` for details on supported indexing semantics.
- When ``__getitem__`` is defined on an object, Python will automatically define iteration (i.e., the behavior from ``iter(x)``) as ``x[0]``, ``x[1]``, ..., ``x[N-1]``. This can also be implemented directly by defining ``__iter__``. Therefore, for a one-dimensional array ``x``, iteration should produce a sequence of zero-dimensional arrays ``x[0]``, ``x[1]``, ..., ``x[N-1]``, where ``N`` is the number of elements in the array. Iteration behavior for arrays having zero dimensions or more than one dimension is unspecified and thus implementation-defined.
+ .. versionchanged:: 2024.12
+ Clarified that iteration is defined for one-dimensional arrays.
"""
def __gt__(self: array, other: Union[int, float, array], /) -> array:
@@ -663,6 +674,9 @@ def __gt__(self: array, other: Union[int, float, array], /) -> array:
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
"""
def __index__(self: array, /) -> int:
@@ -784,6 +798,9 @@ def __le__(self: array, other: Union[int, float, array], /) -> array:
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less_equal`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
"""
def __lshift__(self: array, other: Union[int, array], /) -> array:
@@ -830,6 +847,9 @@ def __lt__(self: array, other: Union[int, float, array], /) -> array:
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
"""
def __matmul__(self: array, other: array, /) -> array:
@@ -955,6 +975,9 @@ def __ne__(self: array, other: Union[int, float, complex, bool, array], /) -> ar
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
"""
def __neg__(self: array, /) -> array:
diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py
index db793c16e..87b026b8e 100644
--- a/src/array_api_stubs/_draft/data_type_functions.py
+++ b/src/array_api_stubs/_draft/data_type_functions.py
@@ -84,6 +84,9 @@ def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool:
- When ``from_`` is a data type, the function must determine whether the data type can be cast to another data type according to the complete type promotion rules (see :ref:`type-promotion`) described in this specification, irrespective of whether a conforming array library supports devices which do not have full data type support.
- When ``from_`` is an array, the function must determine whether the data type of the array can be cast to the desired data type according to the type promotion graph of the array device. As not all devices can support all data types, full support for type promotion rules (see :ref:`type-promotion`) may not be possible. Accordingly, the output of ``can_cast(array, dtype)`` may differ from ``can_cast(array.dtype, dtype)``.
+
+ .. versionchanged:: 2024.12
+ Required that the application of type promotion rules must account for device context.
"""
@@ -238,4 +241,10 @@ def result_type(
- If provided array and/or dtype arguments having mixed data type kinds (e.g., integer and floating-point), the returned dtype is unspecified and thus implementation-dependent.
- If at least one argument is an array, the function must determine the resulting dtype according to the type promotion graph of the array device which is shared among all array arguments. As not all devices can support all data types, full support for type promotion rules (see :ref:`type-promotion`) may not be possible. Accordingly, the returned dtype may differ from that determined from the complete type promotion graph defined in this specification (see :ref:`type-promotion`).
- If two or more arguments are arrays belonging to different devices, behavior is unspecified and thus implementation-dependent. Conforming implementations may choose to ignore device attributes, raise an exception, or some other behavior.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
+
+ .. versionchanged:: 2024.12
+ Required that the application of type promotion rules must account for device context.
"""
diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py
index a35c04db5..2f0cfc8c3 100644
--- a/src/array_api_stubs/_draft/elementwise_functions.py
+++ b/src/array_api_stubs/_draft/elementwise_functions.py
@@ -341,6 +341,9 @@ def add(
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -573,6 +576,9 @@ def atan2(x1: Union[array, int, float], x2: Union[array, int, float], /) -> arra
- If ``x1_i`` is ``+infinity`` and ``x2_i`` is ``-infinity``, the result is an implementation-dependent approximation to ``+3π/4``.
- If ``x1_i`` is ``-infinity`` and ``x2_i`` is ``+infinity``, the result is an implementation-dependent approximation to ``-π/4``.
- If ``x1_i`` is ``-infinity`` and ``x2_i`` is ``-infinity``, the result is an implementation-dependent approximation to ``-3π/4``.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -665,6 +671,9 @@ def bitwise_and(x1: Union[array, int, bool], x2: Union[array, int, bool], /) ->
-----
- At least one of ``x1`` or ``x2`` must be an array.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -688,6 +697,9 @@ def bitwise_left_shift(x1: Union[array, int], x2: Union[array, int], /) -> array
-----
- At least one of ``x1`` or ``x2`` must be an array.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -727,6 +739,9 @@ def bitwise_or(x1: Union[array, int, bool], x2: Union[array, int, bool], /) -> a
-----
- At least one of ``x1`` or ``x2`` must be an array.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -753,6 +768,9 @@ def bitwise_right_shift(x1: Union[array, int], x2: Union[array, int], /) -> arra
-----
- At least one of ``x1`` or ``x2`` must be an array.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -776,6 +794,9 @@ def bitwise_xor(x1: Union[array, int, bool], x2: Union[array, int, bool], /) ->
-----
- At least one of ``x1`` or ``x2`` must be an array.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -850,6 +871,15 @@ def clip(
- If ``max_i`` is ``NaN``, the result is ``NaN``.
.. versionadded:: 2023.12
+
+ .. versionchanged:: 2024.12
+ Added special case behavior when one of the operands is ``NaN``.
+
+ .. versionchanged:: 2024.12
+ Clarified that behavior is only defined when ``x``, ``min``, and ``max`` resolve to arrays having the same data type.
+
+ .. versionchanged:: 2024.12
+ Clarified that behavior is only defined when elements of ``min`` and ``max`` are inside the bounds of the input array data type.
"""
@@ -885,6 +915,9 @@ def conj(x: array, /) -> array:
- Whether the returned array and the input array share the same underlying memory is unspecified and thus implementation-defined.
.. versionadded:: 2022.12
+
+ .. versionchanged:: 2024.12
+ Added support for real-valued arrays.
"""
@@ -928,6 +961,9 @@ def copysign(x1: Union[array, int, float], x2: Union[array, int, float], /) -> a
- If ``x1_i`` is ``NaN`` and ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``0``, the result is ``NaN`` with a sign bit of ``0``.
.. versionadded:: 2023.12
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1124,6 +1160,9 @@ def divide(
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1177,6 +1216,12 @@ def equal(
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1385,6 +1430,9 @@ def floor_divide(
- If ``x1_i`` and ``x2_i`` have the same mathematical sign and are both nonzero finite numbers, the result has a positive mathematical sign.
- If ``x1_i`` and ``x2_i`` have different mathematical signs and are both nonzero finite numbers, the result has a negative mathematical sign.
- In the remaining cases, where neither ``-infinity``, ``+0``, ``-0``, nor ``NaN`` is involved, the quotient must be computed and rounded to the greatest (i.e., closest to `+infinity`) representable integer-value number that is not greater than the division result. If the magnitude is too large to represent, the operation overflows and the result is an ``infinity`` of appropriate mathematical sign. If the magnitude is too small to represent, the operation underflows and the result is a zero of appropriate mathematical sign.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1411,6 +1459,11 @@ def greater(x1: Union[array, int, float], x2: Union[array, int, float], /) -> ar
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1438,6 +1491,12 @@ def greater_equal(
- At least one of ``x1`` or ``x2`` must be an array.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1486,6 +1545,9 @@ def hypot(x1: Union[array, int, float], x2: Union[array, int, float], /) -> arra
Accordingly, conforming implementations may vary in their support for subnormal numbers.
.. versionadded:: 2023.12
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1638,6 +1700,12 @@ def less(x1: Union[array, int, float], x2: Union[array, int, float], /) -> array
- At least one of ``x1`` or ``x2`` must be an array.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1663,6 +1731,12 @@ def less_equal(x1: Union[array, int, float], x2: Union[array, int, float], /) ->
- At least one of ``x1`` or ``x2`` must be an array.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1902,6 +1976,9 @@ def logaddexp(x1: Union[array, int, float], x2: Union[array, int, float], /) ->
- If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``.
- If ``x1_i`` is ``+infinity`` and ``x2_i`` is not ``NaN``, the result is ``+infinity``.
- If ``x1_i`` is not ``NaN`` and ``x2_i`` is ``+infinity``, the result is ``+infinity``.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1928,6 +2005,9 @@ def logical_and(x1: Union[array, bool], x2: Union[array, bool], /) -> array:
-----
- At least one of ``x1`` or ``x2`` must be an array.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1973,6 +2053,9 @@ def logical_or(x1: Union[array, bool], x2: Union[array, bool], /) -> array:
-----
- At least one of ``x1`` or ``x2`` must be an array.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -1999,6 +2082,9 @@ def logical_xor(x1: Union[array, bool], x2: Union[array, bool], /) -> array:
-----
- At least one of ``x1`` or ``x2`` must be an array.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -2032,6 +2118,9 @@ def maximum(x1: Union[array, int, float], x2: Union[array, int, float], /) -> ar
- If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``.
.. versionadded:: 2023.12
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -2065,6 +2154,9 @@ def minimum(x1: Union[array, int, float], x2: Union[array, int, float], /) -> ar
- If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``.
.. versionadded:: 2023.12
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -2137,6 +2229,9 @@ def multiply(
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -2196,6 +2291,8 @@ def nextafter(x1: Union[array, int, float], x2: Union[array, int, float], /) ->
- If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``.
- If ``x1_i`` is ``-0`` and ``x2_i`` is ``+0``, the result is ``+0``.
- If ``x1_i`` is ``+0`` and ``x2_i`` is ``-0``, the result is ``-0``.
+
+ .. versionadded:: 2024.12
"""
@@ -2247,6 +2344,12 @@ def not_equal(
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Cross-kind comparisons are explicitly left unspecified.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -2341,6 +2444,9 @@ def pow(
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -2364,6 +2470,9 @@ def real(x: array, /) -> array:
- Whether the returned array and the input array share the same underlying memory is unspecified and thus implementation-defined.
.. versionadded:: 2022.12
+
+ .. versionchanged:: 2024.12
+ Added support for real-valued arrays.
"""
@@ -2387,6 +2496,8 @@ def reciprocal(x: array, /) -> array:
**Special cases**
For floating-point operands, special cases must be handled as if the operation is implemented as ``1.0 / x`` (see :func:`~array_api.divide`).
+
+ .. versionadded:: 2024.12
"""
@@ -2442,6 +2553,9 @@ def remainder(x1: Union[array, int, float], x2: Union[array, int, float], /) ->
- If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``+infinity``, the result is ``x2_i``. (**note**: this results matches Python behavior.)
- If ``x1_i`` is a negative (i.e., less than ``0``) finite number and ``x2_i`` is ``-infinity``, the result is ``x1_i``. (**note**: this result matches Python behavior.)
- In the remaining cases, the result must match that of the Python ``%`` operator.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
@@ -2796,6 +2910,9 @@ def subtract(
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Added scalar argument support.
"""
diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py
index 3d1f4d9c7..0924b2f9c 100644
--- a/src/array_api_stubs/_draft/fft.py
+++ b/src/array_api_stubs/_draft/fft.py
@@ -592,6 +592,9 @@ def fftfreq(
.. versionchanged:: 2023.12
Required the output array have the default real-valued floating-point data type.
+
+ .. versionchanged:: 2024.12
+ Added ``dtype`` keyword argument support.
"""
@@ -638,6 +641,9 @@ def rfftfreq(
.. versionchanged:: 2023.12
Required the output array have the default real-valued floating-point data type.
+
+ .. versionchanged:: 2024.12
+ Added ``dtype`` keyword argument support.
"""
diff --git a/src/array_api_stubs/_draft/indexing_functions.py b/src/array_api_stubs/_draft/indexing_functions.py
index 8be7cc00e..8e4fae25f 100644
--- a/src/array_api_stubs/_draft/indexing_functions.py
+++ b/src/array_api_stubs/_draft/indexing_functions.py
@@ -34,6 +34,12 @@ def take(x: array, indices: array, /, *, axis: Optional[int] = None) -> array:
.. versionchanged:: 2023.12
Out-of-bounds behavior is explicitly left unspecified.
+
+ .. versionchanged:: 2024.12
+ Behavior when provided a zero-dimensional input array is explicitly left unspecified.
+
+ .. versionchanged:: 2024.12
+ Clarified support for negative indices.
"""
@@ -59,4 +65,6 @@ def take_along_axis(x: array, indices: array, /, *, axis: int = -1) -> array:
-----
- This specification does not require bounds checking. The behavior for out-of-bounds indices is left unspecified.
+
+ .. versionadded:: 2024.12
"""
diff --git a/src/array_api_stubs/_draft/info.py b/src/array_api_stubs/_draft/info.py
index 6177fb12f..fc8b302a8 100644
--- a/src/array_api_stubs/_draft/info.py
+++ b/src/array_api_stubs/_draft/info.py
@@ -69,6 +69,9 @@ def capabilities() -> Capabilities:
-----
.. versionadded: 2023.12
+
+ .. versionchanged:: 2024.12
+ Added support for querying the maximum number of supported dimensions.
"""
diff --git a/src/array_api_stubs/_draft/linalg.py b/src/array_api_stubs/_draft/linalg.py
index a43dc8dcf..4086c333e 100644
--- a/src/array_api_stubs/_draft/linalg.py
+++ b/src/array_api_stubs/_draft/linalg.py
@@ -635,6 +635,9 @@ def solve(x1: array, x2: array, /) -> array:
.. versionchanged:: 2022.12
Added complex data type support.
+
+ .. versionchanged:: 2024.12
+ Clarified broadcasting semantics and the shape of the output array.
"""
diff --git a/src/array_api_stubs/_draft/manipulation_functions.py b/src/array_api_stubs/_draft/manipulation_functions.py
index 7e94cbc27..45d1a8bfd 100644
--- a/src/array_api_stubs/_draft/manipulation_functions.py
+++ b/src/array_api_stubs/_draft/manipulation_functions.py
@@ -50,6 +50,9 @@ def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array:
-------
out: array
an array having the specified shape. Must have the same data type as ``x``.
+
+ .. versionchanged:: 2024.12
+ Clarified broadcast behavior.
"""
diff --git a/src/array_api_stubs/_draft/searching_functions.py b/src/array_api_stubs/_draft/searching_functions.py
index d8676b68b..2478cda11 100644
--- a/src/array_api_stubs/_draft/searching_functions.py
+++ b/src/array_api_stubs/_draft/searching_functions.py
@@ -83,6 +83,8 @@ def count_nonzero(
- If ``x`` has a complex floating-point data type, non-zero elements are those elements having at least one component (real or imaginary) which is non-zero.
- If ``x`` has a boolean data type, non-zero elements are those elements which are equal to ``True``.
+
+ .. versionadded:: 2024.12
"""
@@ -162,6 +164,9 @@ def searchsorted(
While behavior for arrays containing NaNs and signed zeros is implementation-dependent, specification-conforming libraries should, however, ensure consistency with ``sort`` and ``argsort`` (i.e., if a value in ``x2`` is inserted into ``x1`` according to the corresponding index in the output array and ``sort`` is invoked on the resultant array, the sorted result should be an array in the same order).
.. versionadded:: 2023.12
+
+ .. versionchanged:: 2024.12
+ Fixed incorrect boundary conditions.
"""
@@ -195,5 +200,8 @@ def where(
- 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.
+ Added scalar argument support.
+
+ .. versionchanged:: 2024.12
+ Clarified that the ``condition`` argument should have a boolean data type.
"""
diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py
index 92ffe60c5..d318f6d2a 100644
--- a/src/array_api_stubs/_draft/statistical_functions.py
+++ b/src/array_api_stubs/_draft/statistical_functions.py
@@ -63,6 +63,8 @@ def cumulative_prod(
**Special Cases**
For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.multiply`.
+
+ .. versionadded:: 2024.12
"""
@@ -117,6 +119,9 @@ def cumulative_sum(
For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`.
.. versionadded:: 2023.12
+
+ .. versionchanged:: 2024.12
+ Behavior when providing a zero-dimensional array is explicitly left unspecified.
"""
@@ -209,6 +214,9 @@ def mean(
.. note::
Array libraries, such as NumPy, PyTorch, and JAX, currently deviate from this specification in their handling of components which are ``NaN`` when computing the arithmetic mean. In general, consumers of array libraries implementing this specification should use :func:`~array_api.isnan` to test whether the result of computing the arithmetic mean over an array have a complex floating-point data type is ``NaN``, rather than relying on ``NaN`` propagation of individual components.
+
+ .. versionchanged:: 2024.12
+ Added complex data type support.
"""
diff --git a/src/array_api_stubs/_draft/utility_functions.py b/src/array_api_stubs/_draft/utility_functions.py
index 7a234efbb..539833356 100644
--- a/src/array_api_stubs/_draft/utility_functions.py
+++ b/src/array_api_stubs/_draft/utility_functions.py
@@ -126,4 +126,6 @@ def diff(
- The first-order differences are given by ``out[i] = x[i+1] - x[i]`` along a specified axis. Higher-order differences must be calculated recursively (e.g., by calling ``diff(out, axis=axis, n=n-1)``).
- If a conforming implementation chooses to support ``prepend`` and ``append`` arrays which have a different data type than ``x``, behavior is unspecified and thus implementation-defined. Implementations may choose to type promote (:ref:`type-promotion`), cast ``prepend`` and/or ``append`` to the same data type as ``x``, or raise an exception.
+
+ .. versionadded:: 2024.12
"""