Thanks! Can you also mention @seberg's caveat about using functions that expose or depend on CPython internals not exposed by the limited API isn't supported. AFAIK, for 99% of uses this doesn't matter, but it's worth mentioning there are possible caveats and our testing is definitely not exhaustive. See #27979 (comment).

Doc build fails with:

/home/circleci/repo/doc/source/dev/depending_on_numpy.rst:36: WARNING: undefined label: "cpython's ``abi3`"

You can build the docs locally with spin docs, assuming you have e.g. sphinx installed.

Since the stable API is about headers really, I am not really worried about there being caveats we are missing by only including headers as a test (unless Python changes their headers again).

The existing caveats are really very narrow: The internals from our scalar types is the only thing I know right now.

It may make sense to point out that you need to use NumPy 2+ (the issue with the object cast was fixed 2.0.1 so that seems irrelevant in practice).

I reworded a bit to point out that this is supported on 2.0+. I tried a few times to word something about the potential caveats but couldn't get it right. Feel free to push directly a change / addition if you want @seberg !

Nah, I think it's fine to not mention the caveats. They are extremely niche about direct access to a few scalars that happen to subclass from Python.

Thanks @larsoner!