RFC: add API to query optional array library capabilities

[kgryte]

This RFC proposes to add an API to the standard for querying whether a conforming array library supports behavior which is consider optional in the standard.

Currently, downstream libraries have to use non-standardized workarounds to determine whether optional operations are possible, such as when wanting to use a boolean mask or invoke an API having a data-dependent output shape (e.g., nonzero, unique*, etc).

This RFC proposes to add an API which allows explicitly querying whether an optional operation is supported.

Prior art

As this is a behavior specific to the array API standard, no prior art exists.

Proposal

capabilities() -> dict[str, bool]
capabilities(capability: str) -> bool

If not provided an argument, the function would return a dictionary with the following keys:

• boolean_indexing: does an array library support boolean indexing?
• data_dependent_shapes: does an array library support data-dependent output shapes?

More keys could be added in the future, depending on evolution of the standard. The corresponding keys would be boolean values indicating whether the respective optional behavior is supported.

If provided an argument, the function would return a boolean indicating whether an array library supports a specific optional behavior. E.g.,

>>> b = xp.capabilities("boolean_indexing")

Notes

• Bikeshed: different name than capabilities?
• This RFC proposes a function for querying capabilities, rather than attributes, in order to minimize cluttering the main namespace. Additionally, the function can be more readily extended in the future should additional optional behaviors be added to the standard.
• The proposed function supports returning a dictionary for easier inspection in scripts, REPL envs, and when wanting to query support for multiple behaviors. The unary function behavior is a convenience API to avoid unnecessary dictionary creation.

Related

• ENH: Should we allow querying certain implementation details #499

[honno]

In yesterdays consortium meeting @seberg floated the idea of a single function(?) like capabilities() that could encapsulate everything, in the interest of limiting API bloat. This could include: devices, dtypes, library defaults, and indeed these optional capabilities.

[seberg]

I was actually thinking more of a namespace like namespace.__array_api_info__.<entrypoint>. capabilities might then also be a flag enum or so; that can't capture everything, but it would give you a place to encapsulate other things into a function without cluttering things up.

I don't mind a top-level function, but might be hard to convince if unless one of the two constraints is fullfilled:

• The function is limited to arr.__array_namespace__ for NumPy and nobody aims for it to be in numpy.<name> proper (I really don't mind those namespaces being different),
• or it is really useful for a wide audience (including end-users who would only ever use NumPy).

[kgryte]

This RFC has been superseded by #640.