special rules in typeshed pyi

[matthiaskramm]

Let's use this issue to track special stub rules that found their way into typeshed stubs. Since mypy is currently the only system used for testing typeshed, it's natural for some mypy logic to become reflected in the typeshed stubs.

So far I have:

• When something is declared as taking unicode (in the PY2 stubs) then it actually also takes str/bytes.
• When something is declared as taking only float, it also takes int. (EDIT: This is mentioned in PEP 484. See https://www.python.org/dev/peps/pep-0484/#the-numeric-tower)

(I'll add these to README.md once we have a complete list.)

[matthiaskramm]

• When something is declared as taking int (in the PY2 stubs), then it also takes long. (And the other way around)

[smontanaro]

Is int <-> long implicit, or does everywhere I have "int" need to be changed to "Union[int, long]"?

[matthiaskramm]

It's implicit. This whole thread is about things that are implicit. (And the int <-> long equivalence actually is useful, precisely so that you don't have to use Union[int, long])

[matthiaskramm]

• If a function is declared as taking bool, it also takes NoneType.

[JukkaL]

• int being compatible with float is mentioned in PEP 484, so it's not a mypy-specific thing (https://www.python.org/dev/peps/pep-0484/#the-numeric-tower).
• When using mypy with --strict-optional, None is no longer valid when bool is expected. Currently mypy considers None always valid for any type by default, not just for bool. Typeshed should use Optional[...] consistently. I think that providing None when bool is expected should generally be an error (except maybe if that turns out to generate a lot of false positives).

[matthiaskramm]

Thanks for the clarification! I'll edit the posts above.

I think that providing None when bool is expected should generally be an error.

That's what pytype used to do. But our internal users were complaining about it, so we now allow None, too. It seems "safe" enough. At least, it's not clear what a false negative would look like. (Maybe a function without a return?)

[JukkaL]

Here are some potential cases where None is not valid when expecting a bool:

• Value is encoded as JSON. False and None will be encoded differently.
• Value is serialized using some other format where False and None encode differently.
• Value is converted to string (str(None) vs. str(False)), perhaps as part of an error message.
• Comparisons like x == False (yes, they are bad style but they happen).

[JelleZijlstra]

Is it worth adding the unicode/str and int/long promotions for Python 2.7 to PEP 484? Does pytype behave differently from mypy?

[gvanrossum]

I like the idea of specifying promotions in PEP 484. We'd have to have consensus from PyCharm (@vlasovskikh) and pytype (@matthiaskramm).

[matthiaskramm]

+1
This should definitely be documented in a more prominent place, instead of in the depths of the typeshed issue tracker.
pytype does the same thing as mypy.