DEP: deprecate broadcast_shapes, expand_dims

Author: lucascolley

pyproject.toml

@@ -142,6 +142,8 @@ reportUnusedParameter = false
 reportImportCycles = false
 # PyRight can't trace types in lambdas
 reportUnknownLambdaType = false
+# conflicts with https://docs.astral.sh/ruff/rules/explicit-string-concatenation/
+reportImplicitStringConcatenation = false
 
 executionEnvironments = [
   { root = "tests", reportPrivateUsage = false, reportUnknownArgumentType = false },

src/array_api_extra/_delegation.py

@@ -15,7 +15,7 @@
     is_torch_namespace,
 )
 from ._lib._utils._compat import device as get_device
-from ._lib._utils._helpers import asarrays, eager_shape
+from ._lib._utils._helpers import asarrays, deprecated, eager_shape
 from ._lib._utils._typing import Array, DType
 
 __all__ = [
@@ -83,19 +83,23 @@ def atleast_nd(x: Array, /, *, ndim: int, xp: ModuleType | None = None) -> Array
     return _funcs.atleast_nd(x, ndim=ndim, xp=xp)
 
 
+@deprecated(
+    "`xpx.broadcast_shapes` is deprecated and will be removed in v1.0.0. "
+    "`xp.broadcast_shapes` exists in the standard as of v2025.12."
+)
 def broadcast_shapes(
     *shapes: tuple[float | None, ...], xp: ModuleType | None = None
 ) -> tuple[int | None, ...]:
     """
     Compute the shape of the broadcasted arrays.
 
+    .. deprecated:: 0.11.0
+        :func:`broadcast_shapes` is deprecated and will be removed in v1.0.0.
+        :func:`array_api.broadcast_shapes` exists in the standard as of v2025.12.
+
     Duplicates :func:`numpy.broadcast_shapes`, with additional support for
     None and NaN sizes.
 
-    This is equivalent to ``xp.broadcast_arrays(arr1, arr2, ...)[0].shape``
-    without needing to worry about the backend potentially deep copying
-    the arrays.
-
     Parameters
     ----------
     *shapes : tuple[int | None, ...]
@@ -300,18 +304,25 @@ def create_diagonal(
     return _funcs.create_diagonal(x, offset=offset, xp=xp)
 
 
+@deprecated(
+    "`xpx.expand_dims` is deprecated and will be removed in v1.0.0. "
+    "`xp.expand_dims` with support for a tuple of ints in `axis` "
+    "exists in the standard as of v2025.12."
+)
 def expand_dims(
     a: Array, /, *, axis: int | tuple[int, ...] = (0,), xp: ModuleType | None = None
 ) -> Array:
     """
     Expand the shape of an array.
 
+    .. deprecated:: 0.11.0
+        :func:`expand_dims` is deprecated and will be removed in v1.0.0.
+        :func:`array_api.expand_dims` with support for a tuple of ints in `axis`
+        exists in the standard as of v2025.12.
+
     Insert (a) new axis/axes that will appear at the position(s) specified by
     `axis` in the expanded array shape.
 
-    This is ``xp.expand_dims`` for `axis` an int *or a tuple of ints*.
-    Roughly equivalent to ``numpy.expand_dims`` for NumPy arrays.
-
     Parameters
     ----------
     a : array
@@ -804,7 +815,7 @@ def searchsorted(
     Find the indices into a sorted array ``x1`` such that if the elements in ``x2``
     were inserted before the indices, the resulting array would remain sorted.
 
-    The behavior of this function is similar to that of `array_api.searchsorted`,
+    The behavior of this function is similar to that of :func:`array_api.searchsorted`,
     but it relaxes the requirement that `x1` must be one-dimensional.
     This function is vectorized, treating slices along the last axis
     as elements and preceding axes as batch (or "loop") dimensions.
@@ -1220,8 +1231,8 @@ def isin(
     """
     Determine whether each element in `a` is present in `b`.
 
-    Return a boolean array of the same shape as `a` that is True for elements
-    that are in `b` and False otherwise.
+    This is :func:`array_api.isin`, with additional `assume_unique`
+    and `kind` parameters.
 
     Parameters
     ----------

src/array_api_extra/_lib/_utils/_helpers.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import functools
 import io
 import math
 import pickle
 import types
+import warnings
 from collections.abc import Callable, Generator, Iterable, Iterator
 from functools import wraps
 from types import ModuleType
@@ -48,6 +50,7 @@ def override(func):
 __all__ = [
     "asarrays",
     "capabilities",
+    "deprecated",
     "eager_shape",
     "in1d",
     "is_python_scalar",
@@ -58,6 +61,26 @@ def override(func):
 ]
 
 
+def deprecated(
+    msg: str, stacklevel: int = 2
+) -> Callable[[Callable[P, T]], Callable[P, T]]:  # numpydoc ignore=PR01,RT01
+    """Deprecate a function by emitting a warning on use."""
+
+    def decorate(func: Callable[P, T]) -> Callable[P, T]:  # numpydoc ignore=GL08
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:  # numpydoc ignore=GL08
+            warnings.warn(
+                msg,
+                category=DeprecationWarning,
+                stacklevel=stacklevel,
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorate
+
+
 def in1d(
     x1: Array,
     x2: Array,

tests/test_funcs.py

@@ -488,6 +488,7 @@ def test_5D_values(self, xp: ModuleType):
         assert_equal(y, xp.asarray([[[[[[[[[3.0]], [[2.0]]]]]]]]]))
 
 
+@pytest.mark.filterwarnings("ignore:.*removed in v1.0.0.*:DeprecationWarning")
 class TestBroadcastShapes:
     def test_delegates_known_integer_shapes(self, monkeypatch: pytest.MonkeyPatch):
         calls = []
@@ -828,6 +829,7 @@ def test_torch(self, torch: ModuleType):
         assert default_dtype(xp, "complex floating") == xp.complex64
 
 
+@pytest.mark.filterwarnings(r"ignore:.*removed in v1.0.0.*:DeprecationWarning")
 class TestExpandDims:
     def test_single_axis(self, xp: ModuleType):
         """Trivial case where xpx.expand_dims doesn't add anything to xp.expand_dims"""