From a cursory look, it seems the problem also exists in numpy 2.2.

The difference between np.float64 and np.double is semi-intentional. As you correctly spotted, np.double is currently a broader type than np.float64, so float64 can be assigned to double, but not the other way around. And even though it's not documented anywhere (and it shouldn't), this difference be exploited to work around the now-deprecated mess that's caused by numpy.typing.NBitBase:

import numpy as np
import numpy.typing as npt

def pos_naive(x: np.float64) -> np.float64:
    return +x

def pos_workaround(x: np.double) -> np.float64:
    return +x  # probably needs a cast or type: ignore

def pos_evil_dont_use_this_pls[T: npt.NBitBase](x: floating[T]) -> floating[T]:
    return +x


y = pos_evil_dont_use_this_pls(np.float64(42))
reveal_type(y)  # floating[_64Bit] 
                # ^-- yikes

pos_naive(y)       # STOP! You've violated the law! Pay the court a fine or serve your sentence.
pos_workaround(y)  # Everything's in order.

So np.double is a bit of a double-edged sword: It can be useful in certain situations when used defensively (i.e. in input positions), but could lead to issues if you use it offensively (in output positions), in which case you should always use np.float64 instead.

So in a perfect word, np.double would be exactly equivalent to np.float64. But until that time, there are still use-cases for it.

But to be honest, I'm a bit worried that the cure is worse than the disease, since its leaflet probably isn't obvious to someone that isn't a full-time stub developer. So what do you think we should do here?

So what do you think we should do here?

Personally, just from my very limited and perhaps naive perspective, I would prefer eventual consistency across all these aliases, i.e. having np.double and np.float64 be perfectly equivalent. Firstly, because then all scalar types neatly behave the same way and the old special treatment for np.float64 is finally ancient history. And secondly, I find this compelling since the documentation already claims that these two are mere aliases of one another. The fact that they then do not behave as such is confusing. The role that np.double currently fills would then perhaps best be filled by a new/different scalar type - if at all! As you say:

And even though it's not documented anywhere (and it shouldn't), this difference be exploited to work around the now-deprecated mess that's caused by numpy.typing.NBitBase

I take it you mean that this kind of workaround is not officially encouraged. So I don't see much reason for a wider np.double to exist purely for this purpose. For example, in the code you show, to build an equivalent signature for pos_evil_dont_use_this_pls without NBitBase, I would opt for a solution using overloads - which I believe you also suggest in the docs. That is future-proof, more explicit, and perfectly equivalent. So the continued existence of a slightly wider np.double for this kind of purpose seems superfluous to me, and inviting use in ways that are not encouraged.

However, I also understand that this could be considered quite an impactful change, and that it will probably break some people's existing code (https://xkcd.com/1172/). My opinion here is very much informed by preferentially using very explicit scalar types and doing so on small projects that are easily adapted to changes. I recognize not everyone has that luxury.

All that is to say, I would prefer one of two options (or both, one after the other):

1. Document the discrepancy in some careful way so no one is surprised when assigning np.double to np.float64 does not work, but no one gets any funny ideas either.
2. Make np.double and np.float64 equivalent (eventually).

However, I also understand that this could be considered quite an impactful change, and that it will probably break some people's existing code (xkcd.com/1172)

I'll create a quick PR for this, so we can see what mypy_primer has to see about it.

Oh and for what it's worth, in numtype they're already bidirectionally equivalent mutual aliases of each other in both ways (and vice-versa).