feat: add broadcast_shapes to the specification

[kgryte]

This PR

• resolves RFC: add broadcast_shapes to the specification #893 by adding support for broadcast_shapes to the specification.
• follows NumPy et al in supporting an arbitrary number of input shapes to be broadcasted.
• specifies that only shapes which contain integers are explicitly supported. For shapes containing sentinel values such as None for a dimension of unknown size, behavior is left unspecified and thus implementation-defined.

[rgommers]

Thanks @kgryte! Overall LGTM and seems good to add this function to the standard. A few comments with the "unknown shape" one the key thing to discuss.

[lucascolley]

the array-api-extra docs just say

https://data-apis.org/array-api-extra/generated/array_api_extra.broadcast_shapes.html

[ev-br]

One small suggestion about the unknown dimensions, LGTM otherwise.

[lucascolley]

Is this deliberately less strict than https://data-apis.org/array-api/draft/API_specification/generated/array_api.array.shape.html#shape, which seems to imply that None is the only acceptable non-integer value in a shape (at least where that value is supposed to represent an unknown dimension)?

E.g. this appears to be accommodating Dask's math.nan, suggesting that it should propagate that math.nan? That would differ from the existing behaviour in https://data-apis.org/array-api-extra/generated/array_api_extra.broadcast_shapes.html which replaces that non-standard math.nan with a None.

Suggested change

- An array-conforming library **may** accept a non-integer value (e.g., ``None``) for one or more dimensions. This is common for array libraries which build computation graphs (e.g., ndonnx and Dask) and which need to provide a mechanism for indicating dimensions of unknown size. Array-conforming libraries which accept non-integer values for dimensions of unknown size **must** propagate such values (e.g., if a shape contains a dimension size of ``None``, the returned broadcasted shape **must** also have a corresponding dimension having a size equal to ``None``); otherwise, an array-conforming library **must** raise a ``ValueError``.

- An array-conforming library **may** accept a ``None`` value for one or more shape dimensions. This is common for array libraries which build computation graphs (e.g., ndonnx and Dask) and which need to provide a mechanism for indicating dimensions of unknown size. Array-conforming libraries which accept ``None`` values for dimensions of unknown size **must** propagate those values (i.e., if a shape contains a dimension size of ``None``, the returned broadcasted shape **must** also have a corresponding dimension having a size equal to ``None``); otherwise, an array-conforming library **must** raise a ``ValueError``.

[kgryte]

@lucascolley I think it depends on how you define "non-standard". Is there a reason to prohibit the use of non-none sentinel values?

[kgryte]

Or stated differently, in what scenario do consumers need to rely on a standardized sentinel value (e.g., checking for None vs checking whether a value simply isn't an integer)?

[lucascolley]

Is there a reason to prohibit the use of non-none sentinel values?

Not that I can think of! But for consistency, if you want to go ahead with this PR as is, I think the $\iff$ at

array-api/src/array_api_stubs/_draft/array_object.py

Line 77 in 3a801d3

array dimensions. An array dimension must be ``None`` if and only if a dimension is unknown.

needs to be relaxed.

[kgryte]

Thanks for pointing that out. Will raise during the workgroup meeting today.

[lucascolley]

An issue should be opened regarding deprecation of https://data-apis.org/array-api-extra/generated/array_api_extra.broadcast_shapes.html.

[lucascolley]

Suggested change

	def broadcast_shapes(*shapes: Tuple[int, ...]) -> Tuple[int, ...]:
	def broadcast_shapes(*shapes: Tuple[int | None, ...]) -> Tuple[int | None, ...]:

to match https://data-apis.org/array-api/draft/API_specification/generated/array_api.array.shape.html#array_api.array.shape

[lucascolley]

Suggested change

	shapes: Tuple[int, ...]
	shapes: Tuple[int | None, ...]

[lucascolley]

Suggested change

	out: Tuple[int, ...]
	out: Tuple[int | None, ...]