-
Notifications
You must be signed in to change notification settings - Fork 52
Description
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.
Activity
honno commentedon Jun 2, 2023
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 commentedon Jun 2, 2023
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
ifunless one of the two constraints is fullfilled:arr.__array_namespace__
for NumPy and nobody aims for it to be innumpy.<name>
proper (I really don't mind those namespaces being different),kgryte commentedon Jun 29, 2023
This RFC has been superseded by #640.