ENH: Add array API inspection functions#26572
Conversation
These are new functions defined by the array API 2023.12 standard to inspect details about the array API namespace. See https://data-apis.org/array-api/latest/API_specification/inspection.html for more details.
This is new in the unreleased 2024.12 standard, but I don't see an issue with including it now.
Unfortunately, I don't see an easy way to include these docstrings in Sphinx, other than __array_namespace_info__, because they are hidden behind a private namespace that is only accessible from np.__array_namespace_info__().
It's better to not include unreleased standard things in case they change.
mtsokol
left a comment
mtsokol
left a comment
There was a problem hiding this comment.
My comments:
- I would prefer
__array_namespace_info__to be a class with methods, as the standard allows it:In the namespace (or class) returned by array_namespace_info,
- We already have
numpy/lib/introspect.py, maybe we can move the implementation there? - In terms of testing: let's bump
array-api-testsCI job to the latestarray-api-testsversion:- Bump the hash in: to the latest commit that includes
numpy/.github/workflows/linux.yml
Line 231 in f2c93e2
2023.12standard. I think it's33f2d2ea2f3dd2b3ceeeb4519d55e08096184149? (does it test2023.12items?) - Let's bump the version to
2023.12inLine 292 in f2c93e2
- I think there might be needed some slight adjustments to the
array-api-skips.txtfile.
- Bump the hash in:
- I think returning dtype instances are fine.
- I think the default dtypes should be always the same.
realandcomplexare straightforward.integralandindexingare a bit tricky. Here's some discussion about it #24224. I think forintegralandindexingit should benp.intp.
numpy/lib/_info.py
Outdated
| "bool": bool, | ||
| "int8": int8, | ||
| "int16": int16, | ||
| "int32": int32, | ||
| "int64": int64, | ||
| "uint8": uint8, | ||
| "uint16": uint16, | ||
| "uint32": uint32, | ||
| "uint64": uint64, | ||
| "float32": float32, | ||
| "float64": float64, | ||
| "complex64": complex64, | ||
| "complex128": complex128, |
There was a problem hiding this comment.
Nitpick: maybe instead of repeating contents of these dicts, let's keep signed integer, unsigned integer, bool, real, complex dicts, and define the rest of them by merging existing ones: integral = signed_integer | unsigned_integer etc.
That doesn't sound quite right to me, both because that's a public namespace and because this inspection functionality will not be part of This should have dedicated tests, not only rely on
Agreed, that's more idiomatic.
That sounds right to me.
|
rgommers
added
the
40 - array API standard
Right, good point.
Sure - I think these new functions should have a separate test suite, but |
|
array-api-tests doesn't currently support the inspection APIs. I've added support for testing the signatures at data-apis/array-api-tests#262, but I still need to implement tests for the actual functionality. |
Better not do that until we have full 2023 support. There are still a few other things that need to be updated. |
This makes the functions on the namespace easier to access for things like Sphinx.
|
I've added the functions to Sphinx. Unfortunately, the pydata-sphinx-theme does not properly word wrap function names in several places: 
(see also scipy/scipy#20635). This will need to be fixed in the upstream theme. I am pretty sure some of my doctests are wrong, but I have no idea how to actually run them. The refcheck_guide script doesn't seem to run the doctests for these functions. |
|
I'm not sure about the typing stuff here. I mainly copied it from the spec, changing some generic types like |
|
Issues should be fixed. |
4 participants
These are new functions defined by the array API 2023.12 standard to inspect
details about the array API namespace. See
https://data-apis.org/array-api/latest/API_specification/inspection.html for
more details.
Even though these functions are pretty simple for NumPy, I have a few questions about the implementation:
numpy/lib/_info.pythe correct to put this?__array_namespace_info__. The issue is that these functions are accessed likenp.__array_namespace_info__().capabilities(), so it's not a normal dotted module name. I could add the private module to Sphinx. Is it possible to do this without referring to the private API? Another alternative I thought of is to make__array_namespace_info__a class so that the functions are just methods on the class (I would have rather preferred if the array API had defined__array_namespace_info__as a simple submodule rather than a function, but it may be too late to change that).