Add Array API inspection utilities

[kgryte]

This PR

• resolves ENH: Should we allow querying certain implementation details #499 and resolves RFC: add a unified inspection API namespace #640 by adding a unified API for inspecting the Array API capabilities for specification-conforming array libraries. The principle details of this implementation were proposed and discussed in the referenced RFC.

[rgommers]

This looks pretty good to me overall, thanks @kgryte.

[kgryte]

I've updated this PR to use a protocol instead of a data class. I believe this PR should be ready for final review.

[rgommers]

The way this PR is written and without looking at the linked discussions, it's not quite clear to me whether __array_namespace_info__ is an array method or a function in the namespace returned by array.__array_namespace__.

In addition, it could be useful to clarify in the __array_namespace_info__ docs that the returned object from that function/method may be either a namespace or a class; as long as the user can do this:

info = __array_namespace_info__()
info.capabilities()
info.devices()
info.dtypes()
info.default_dtypes()

[rgommers]

The rendered docs look fine, maybe some explanation under Inspection APIs and right above the table of function/method names will help?

[rgommers]

IIRC there were a few more things discussed for inclusion in the inspection API:

• the max number of dimensions: RFC: add inspection support for querying the maximum number of supported dimensions #694
• whether or not read-only arrays are supported
• eager/lazy (maybe, not sure)

[kgryte]

IIRC there were a few more things discussed for inclusion in the inspection API

I was planning on submitting follow-up PR(s) to avoid potential bikesheds and avoid piggybacking on this PR, but I can include some of the aforementioned additional capabilities in this PR. I don't have a strong opinion, except wanting to get this in sooner rather than later.

[kgryte]

@rgommers The updated inspection.rst file now renders as

[kgryte]

@rgommers @leofang I believe I have addressed your most recent review comments, and this PR should be ready for another round of review.

[leofang]

LGTM from my perspective. I'm keen to see this PR merged so that we can start addressing follow-up works (ex: #689 (comment)).

Ping @oleksandr-pavlyk for review, due to its relevance 🙂

[rgommers]

LGTM too now, modulo the one typo.

[oleksandr-pavlyk]

LGTM!

[leofang]

Two nits on formatting, but content-wise we're good to go!

[kgryte]

Thanks, @leofang! Made the updates.

@rgommers I think we are good to go here.

[leofang]

Thanks to Athan for driving this and all for help!