NumPy 2.2 had a lot of typing improvements, but that also means some regressions (at least and maybe especially for mypy users).

So maybe this exercise is mainly useful to me to make sense of the mega-issue in gh-27957.

My own take-away is that we need the user documentation (gh-28077), not just for users, but also to understand better who and why people have to change their typing. That is to understand the two points:

1. How many users and what kind of users are affected:
   • Early "shaping users" of unsupported shapes may be few?
   • mypy users of unannotated code are maybe quite many.
2. And what do they need to do:
   • Removing shape types seems easy (if unfortunate).
   • Adding --allow-redefinition is easy, avoiding mypy may be more work (maybe unavoidable).
   • Are there other work-around? Maybe scipy-lectures is "special" or could hide generic types outside the code users see...

One other thing that I would really like to see is also the "alternatives". Maybe there are none, but I would at least like to spell it out, as in:
Due to ... only thing that we might be able to avoid these regression is to hide it away as from numpy.typing_future import ndarray and that is impractical/impossible because...

CC @jorenham although it is probably boring to you, also please feel free to amend or expand.

Issues that require user action

User issues due to (necessarily) incomplete typing

There are two things that came up where NumPy used to have less precise or wrong typing, but correcting it making it more precise (while also necessarily incomplete as it may require a new PEP) means that type checking can fail:

• floating is now used as a supertype of float64 (rather than identity) meaning it (correctly) matches float32, float, etc.
  • Incomplete typing means functions may return floating rather than float64 even when they clearly return float64.
  • (N.B.: NumPy runtime is slightly fuzzy about this, since np.dtype(np.floating) gives float64, but with a warning because it is not a good meaning.)
• There is now some support for shape typing
  • Previously, users could add shapes, but these were ignored.
    • E.g. https://github.com/search?q=ndarray%5Btuple&type=code although 1800 files doesn't seem that much.
  • Shape typing should not be used currently, because most functions will return shape-generic results, meaning that even correct shapes types will typically just type checking.
    (Users could choose to use this, but probably would need to cast explicitly often.)

There is a mypy specific angle in gh-27957 to both of these, because mypy defaults (but always runs into it) to infer the type at the first assignment. This assignment is likely (e.g. creation) to include the correct shape and float64 type, but later re-assignments will fail.

• mypy has --allow-redefinition although it doesn't fix it fully at least for nested scopes in for-loops, mypy may improve this.

The user impact is that:

• At least mypy fails even for unannotated code.
• Users have to avoid even correct float64 and shape types due to imprecise NumPy type stubs. These previously passed, whether intentional or not.
  • For float64 passing previously was arguably a bug, but is still a regression.
  • For shapes, this means explicitly broaden correct shapes (not necessary previously)

(I, @seberg, cannot tell how problematic these are, or what options we have to try to make this easier on downstream, short of reverting or including reverting.)

Simple regressions fixed or fixable in NumPy

• TYP: False positives in ndarray.__setitem__ with object_ dtype in NumPy 2.2 #27964
• The floating change has at least that seems very much fixable with follow-ups, see TYP: inconsistent static typing of float64 addition #28071 (e.g. numpy.zeros(2, dtype=numpy.float64) + numpy.float64(1.0) is clearly float64).
• TYP: ndarray.item never typechecks #27977
• TYP: np.ndarray.tolist return type seems broken in numpy 2.2.0 #27944
• TYP: excessively vague return types from np.dtype and np.ndarray.dtype in numpy 2.2.0 #27945

Type-checkers issues that may impact NumPy

• MyPy has already a few new fixed related to issues found in NumPy (not sure all are 2.2 related): Issues related to numpy python/mypy#18343