DOC: Comparing dtypes

[timhoffm]

Issue with current documentation:

Dtype comparisons are somewhat tricky. One may be tempted to assume

a = np.array([1, 2], dtype=np.int64)
a.dtype is np.int64

But that's not the case. It seems like dtype comparisons are supposed to be made via equal comparision

a.dtype == np.int64

Idea or request for content:

This should be documented at https://numpy.org/doc/stable/reference/arrays.dtypes.html

I would be willing to make a PR, but I do not fully understand the dtype system. Is it enough to say "compare dtypes using ==" or is there more to it?

[ngoldbaum]

Using “is” comparison with dtypes is definitely problematic, as you saw, and the docs should discourage doing that. The problem is that sometimes it does sort of make sense - there is logically only one kind of Int8 dtype. But it can’t make sense in general and the dtype system at best does a piecemeal attempt to actually enforce that these sorts of dtypes are true singletons.

If you want equality comparison, == should
work. Note however that the rules here are a little weird, and things like this are true:

>>> import numpy as np
>>> print(np.float64 == np.dtype(np.float64))
True
>>> print(type(np.float64))
<class ‘type’>
>>> print(type(np.dtype(np.float64)))
<class ‘numpy.dtype.Float64DType’>

the logic here is that the dtype and scalar type are in some sense interchangeable and it lets users be a little loose with the distinction between a dtype and the type of a scalar element of an array.

Hope there’s something in there to be included in the docs! Thanks for helping to improve it!!