Interesting, mypy is fine with this approach but stubtest is not:

error: not checking stubs due to mypy build errors:
lib/matplotlib/figure.pyi:95: error: Overloaded function signatures 1 and 2 overlap with incompatible return types  [misc]
lib/matplotlib/pyplot.py:1566: error: Overloaded function signatures 1 and 2 overlap with incompatible return types  [misc]

Is it possible to say all integers except 1? If not, we may have to go back to partially dynamic typing as suggested in #27001 (comment).

Let's see if we can keep the .py code specific and only loosen the restrictions on the .pyi stubs.

I think we may be able to get by by simply changing only the "fallback" case from having a union return type to just being Any, but keeping the more specific versions to provide the benefits of having type hints when we can.

The truth is that the type hint is not wrong... it is, to the best of our ability within the type system, giving an accurate description of the return type, which we cannot say whether it will be a single Axes or an ndarray based on the type...

I specifically called out potentially wanting Any for this case to avoid union types on returns in #27001 (review)

I think we may be able to get by by simply changing only the "fallback" case from having a union return type to just being Any, but keeping the more specific versions to provide the benefits of having type hints when we can.

Thanks, I think this is a better solution than what I came up with.

The truth is that the type hint is not wrong...

This is where I disagree. It is true that the return type can be Axes or np.ndarray, but it is not correct to say that the return type is Axes | np.ndarray.

we cannot say whether it will be a single Axes or an ndarray based on the type...

This is referred to as dynamic typing. In Python Any is used "to indicate that a value is dynamically typed." Using a union as a return type implies that the return value can be of either type, and that all uses of that function must be able to handle both. Unions are almost never used in return types, only in parameter types.¹²

Is anyone able to review this? Would love to get this into 3.9.2.

I can confirm that this change fixes mypy error in my job's codebase.