DOC: Add information (maybe just release note) for typing regressions

@stefanv

It may be helpful to have a (likely very brief) section on how to deal with typing regressions, and I think it would be just fine to amend the 2.2 release notes (and maybe add a link to that for 2.2.1 and/or 2.2.2).

We should also add a "Static typing" section to the release notes, I think.

There were two (main?) regressions for users (whether they are just fixes doesn't matter):

The introduction of shape typing
The correct floating typing.

And while I know that we have the following options:

Add (more generic) type hints manually.
- For floating this is unfortunate and users should open an issue where necessary, because we can hopefully fix it.
- For shape typing, this is expected: Users must not do any manual shape types right now. If they (optimistically) did so, we are sorry, but you are out of luck.
User --allow-redefinition in mypy for unannotated code (with caveats).
Unfortunately, users may have to avoid mypy (I am not sure how feasible this was for @stefanv!)

So in the end, there is almost nothing here, but considering how long the discussion was, maybe it is helpful to do it even if it isn't too many users who need it in the end (I am honestly not sure).

Even better would be to improve the "how to type NumPy"/numpy.typing documentation, but that would seem like a lot of work. Although, adding a .. note:: to not type shapes seems very prudent?

The introduction of shape typing

It's more that we've made progress towards supporting shape typing; it hasn't been introduced yet.

The correct floating typing.

Do you mean that float64 and complex128 are correctly annotated as builtins.float and builtins.complex subtypes, respectively?

For floating this is unfortunate and users should open an issue where necessary, because we can hopefully fix it.

Yes, this shouldn't have happened. I aim to fix it within two weeks.

For shape typing, this is expected: Users must not do any manual shape types right now. If they (optimistically) did so, we are sorry, but you are out of luck.

True; we have never claimed that we support shape-typing, only that we're working towards it, and that it's difficult to achieve.

User --allow-redefinition in mypy for unannotated code (with caveats).

I'm not sure if this will help much, but it's worth a short, and it will be enabled by default in mypy 2.0 anyway.

Unfortunately, users may have to avoid mypy

https://github.com/erictraut/mypy_issues helps explain why

Even better would be to improve the "how to type NumPy"/numpy.typing documentation, but that would seem like a lot of work. Although, adding a .. note:: to not type shapes seems very prudent?

Maybe it's a good idea to add a note to the ndarray docs about the current state of shape-typing (i.e. it's a WIP, so use at your own risk).

@jorenham

@jorenham do you have time to write some (brief) guidance? We can even start here and then see how to integrate it into the 2.2 release notes or so.

About mypy, I think we should explicitly mention the redefinition thing and otherwise just note that we tend to see more issues with mypy so users who run into other issues should consider trying pyright or basedpyright as well.
(Otherwise, it may quickly morph into the discussion on whether mypy can/should be supported longer term, and it would be nice to avoid it.)

@jorenham

@jorenham do you have time to write some (brief) guidance?

At least not for the coming days. _{I need to release the next scipy-stubs before the upcoming scipy 1.15.0 release is published, and after that I plan to thoroughly fix the recent typing issues in numpy.}
And writing isn't really my strong point, which makes it a rather slow progress for me (writing this response already took me like ~40 minutes 😅).
Maybe some LLM could also help us with this, by e.g. feeding it this issue and the other related ones? At least it could give us a head-start 🤷🏻.
Either way, it'll be more efficient if there's an initial version that I could adjust or amend, then to write from scratch.

About mypy, I think we should explicitly mention the redefinition thing and otherwise just note that we tend to see more issues with mypy so users who run into other issues should consider trying pyright or basedpyright as well. (Otherwise, it may quickly morph into the discussion on whether mypy can/should be supported longer term, and it would be nice to avoid it.)

I don't think we can afford to ditch mypy ourselves, not while we still have a non-neglicable amount of users that still use it.
But given that we want the best "static typing experience" for our users, we should indeed recommend that they use the best tool for this. And we've seen that at the moment, that doesn't include mypy. _{But given the recent effort of the mypy team, this might change in the future, which IMO would be the best outcome.}

A little bird told me that there'll be some exciting big changes coming to numpy-typing in the near future, and that it'll be 100% opt-in.
So maybe it's an idea to combine the announcement of these (alleged) upcoming changes with these notes on the 2.2 typing issues? Because that way it'll be less likely to be (mis-)interpreted as

We messed up, so now you should change your type-checker.

and more like

We have heard you loud and clear, and we're doing everything within our power to make sure this won't happen again.

At the moment I can't really say when exactly that (alleged) change will come, but the little bird told me that a certain someone will work on it once that certain someone as fixed set of certain numpy issues.
But I see no harm in announcing it before it can actually be used. That could perhaps also help get the community involved in its (alleged) development early on _{and I think that that's a good thing_.}

Just brainstorming:

When updating to NumPy 2.2, users may unfortunately experience typing regressions largely due to improved typing information.
Some of these are regressions that are expected to be fixed in bug-fix releases (issues welcome), but there are some known patterns that unfortunately require user action.

The biggest change is seeing errors such as:

Example for a shape mismatch

which can happen for two reasons:

You explicitly type a shape using np.ndarray[tuple[int], ...] to mark a 1-D array. This was previously ignored and you should, unfortunately, remove the shape typing. Shape typing is necessarily incomplete and cannot be used without the risk of regressions until it is fully developed.
mypy users are likely to see this when reassigning a variable:
```
a = np.zeros(10, dtype=np.float64)
a = a + a
```
The shape information will often be lost making such re-assignments fail. There are a few possible solutions:
- Use --allow-redefinition (will be default in mypy 2.0) will avoid some, but maybe not all of these.
- You could opt to explicitly type a.
- You can try a different type checker such as pyright or basedpyright.

A second change seen more commonly is a newly reported typing mismatch for floating and float64. These are expected to be fixed in future bug-fix releases, so please don't hesitate to open an issue.

In general, we have experienced more issues with mypy than with alternatives such as pyright or basedpyright. So if you are experiencing typing problems/regressions we hope that these may provide an alternative solution.

Something about future work... dunno what.

The main point is, I can't say if this is complete and is actually the information. We can hint about that future work and note that this is necessary to make future work happen.
But, I would prefer not to bunch up announcements. As of now, I am not clear how much of a problem this is, but this is about helping users to apply hot fixes.
If there is a clear solution to this problem on the short-term horizon here, that is worthwhile to note (because sitting things out may be an option), if not... It would be here just to end on a positive note, IMO.

I would make it clear to the user what their expectation can be, and what we are doing. E.g., something like:

Unannotated code involving NumPy should not fail type-checking.
Code that uses our new shape-typing [and give an example]: this is under constant improvement, so expect breakage along the way
Correctly annotated code that fails type checking: unfortunately, we do not control type-checking tooling. We recommend pyright as the most robust type checker, but since mypy is commonly used we recommend the following configuration [provide flags].
Future: we plan to separate NumPy type stubs into a package: numpy-typing, similar to scipy-typing, at which point type annotation will become opt-in (via installation of that package).

Let's figure out the list of items we want to discuss; that's a lower bar to meet, and I'd be happy to take that list and expand it into full sentences.

Widen Array1D to fix changes to numpy shape

Widen Array1D to fix changes to numpy shape (#736)

Any update on the current recommendation for shape typed code when updating to Numpy 2.2?

If I understood the conversation so far, this concerns situations where we started using shape types for better documenting array dimensions like this:

Array1D = np.ndarray[tuple[int], np.dtype[np.uint8]]
Array2D = np.ndarray[tuple[int, int], np.dtype[np.uint8]]

def test(data_2d: Array2D) -> Array1D:
    # Mypy + Numpy 2.2: Incompatible return value type
    # (got "ndarray[tuple[int, ...], ...]", expected "ndarray[tuple[int], ...]")
    return data_2d[:, 0]

The current recommendation is to remove the shape types on our end?

It's a bit sad because being able to communicate how array structures look like is a big win, even without having checks for it. There isn't by any chance a way to make type checkers opt out of checking shape types again? Like, making the Numpy-Mypy-Plugin override shape types to Any?

The current recommendation is to remove the shape types on our end?

For now that's indeed for the best.

It's a bit sad because being able to communicate how array structures look like is a big win, even without having checks for it.

I completely agree. That's why we're currently working hard so that you'd be able to do something similar like this in the future.

But since there's a good that the api will be different from your example, it might not be compatible with the shape-typing approach from your example.

In case you're interested in the details, the shape-typing progress can be followed at https://github.com/numpy/numtype. But note that there's no official release, and not a lot of documentation yet, as it's all a bit experimental at the moment.

Like, making the Numpy-Mypy-Plugin override shape types to Any?

In NumPy 2.3 the mypy plugin will actually be deprecated. There are many reasons for that, but one of the most important one is because we aim to support multiple type-checkers, such as pyright. That requires minimizing the differences in behavior between different type-checkers.

On a related note, the upcoming NumPy 2.3 will make the shape-type of numpy.typing.NDArray default to tuple[Any, ...] instead of tuple[int, ...], which I'm guessing will resolve the error in your example. See #28982 for the juicy deets.

@pwuertz

Should #28982 be released in the next patch? I might be misunderstanding, but it seems like this will fix the shape typing "regression" mentioned by @pwuertz, and annotations that pass checking in 2.2 won't fail after the patch?

Should #28982 be released in the next patch? I might be misunderstanding, but it seems like this will fix the shape typing "regression" mentioned by @pwuertz, and annotations that pass checking in 2.2 won't fail after the patch?

As you can see at #28982 (comment), this change can lead to some typing errors in downstream libraries. So including it in a patch release would be too risky, as far as I'm concerned.

This doesn't seem to be relevant anymore, so I'm closing this.

Navigation Menu

Repository navigation

DOC: Add information (maybe just release note) for typing regressions #28077

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

DOC: Add information (maybe just release note) for typing regressions #28077

Description

Activity

jorenham commented on Dec 31, 2024

seberg commented on Dec 31, 2024

jorenham commented on Dec 31, 2024

seberg commented on Dec 31, 2024

stefanv commented on Jan 10, 2025

pwuertz commented on May 22, 2025

jorenham commented on May 22, 2025

jack-mcivor commented on May 22, 2025

jorenham commented on May 22, 2025

jorenham commented on Oct 3, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions