feat: add broadcast_shapes to the specification

PR-URL: data-apis#983
Closes: data-apis#893
Reviewed-by: Ralf Gommers <ralf.gommers@gmail.com>
Reviewed-by: Lucas Colley
Reviewed-by: Evgeni Burovski

Author: kgryte

spec/draft/API_specification/manipulation_functions.rst

@@ -19,6 +19,7 @@ Objects in API
    :template: method.rst
 
    broadcast_arrays
+   broadcast_shapes
    broadcast_to
    concat
    expand_dims

src/array_api_stubs/_draft/manipulation_functions.py

@@ -1,5 +1,6 @@
 __all__ = [
     "broadcast_arrays",
+    "broadcast_shapes",
     "broadcast_to",
     "concat",
     "expand_dims",
@@ -35,6 +36,33 @@ def broadcast_arrays(*arrays: array) -> Tuple[array, ...]:
     """
 
 
+def broadcast_shapes(*shapes: Tuple[Optional[int], ...]) -> Tuple[Optional[int], ...]:
+    """
+    Broadcasts one or more shapes against one another.
+
+    Parameters
+    ----------
+    shapes: Tuple[Optional[int], ...]
+        an arbitrary number of to-be broadcasted shapes.
+
+    Returns
+    -------
+    out: Tuple[Optional[int], ...]
+        a single broadcasted shape obtained by applying broadcasting rules (see :ref:`broadcasting`) to each of the input shapes against one another.
+
+    Raises
+    ------
+    ValueError
+        If provided shapes which are not broadcast compatible (see :ref:`broadcasting`), a ``ValueError`` **should** be raised.
+
+    Notes
+    -----
+
+    -   If not provided one or more arguments, the function **must** return an empty tuple.
+    -   Array-conforming libraries which build computation graphs (e.g., ndonnx and Dask) and which need to provide a mechanism for indicating dimensions of unknown size **may** accept non-integer values (e.g., ``None``). For these libraries, dimensions of unknown size **must** be propagated to the returned shape.
+    """
+
+
 def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array:
     """
     Broadcasts an array to a specified shape.