feat: add broadcast_shapes to the specification

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,35 @@ def broadcast_arrays(*arrays: array) -> List[array]:
     """
 
 
+def broadcast_shapes(*shapes: Tuple[int, ...]) -> Tuple[int, ...]:
+    """
+    Broadcasts one or more shapes against one another.
+
+    Parameters
+    ----------
+    shapes: Tuple[int, ...]
+        an arbitrary number of to-be broadcasted shapes.
+
+    Returns
+    -------
+    out: Tuple[int, ...]
+        a broadcasted shape.
+
+    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.
+
+    .. note::
+       Array libraries which build computation graphs (e.g., ndonnx and Dask) commonly support shapes having dimensions of unknown size. If a shape contains a value other than an integer (e.g., ``None`` for a dimension of unknown size), behavior is unspecified and thus implementation-defined. Array-conforming libraries **may** choose to propagate such values (e.g., if a shape contains a dimension size of ``None``, the returned broadcasted shape also has a corresponding dimension having a size equal to ``None``) or raise an exception.
+    """
+
+
 def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array:
     """
     Broadcasts an array to a specified shape.