Update documentation to reflect that bool is a subtype of int

[rvanlaar]

Bool is a subtype of int.

The goals of this issue is to document this in a good way in the mypy documentation.

A short example:

This can cause problems when a function is expected to return an int, but in reality returns a bool.
Take this code for example:

def example(x: int) -> int:
    if x := x > 0:
        return x
    return 0

The expectation is that this function will return only positive integers or 0.
What happens is that it will return bool for positive integers and 0 for non positive ints.

This is a weird edge case for python3. See also this blog:
https://medium.com/@timb07/python-bool-wat-ab0e28d879c7

As per: #8053

[orcutt989]

@rvanlaar @JukkaL Are we thinking it should go in https://github.com/python/mypy/blob/master/docs/source/dynamic_typing.rst ?

[JukkaL]

This should probably go somewhere in https://github.com/python/mypy/blob/master/docs/source/builtin_types.rst.

[sobolevn]

@JukkaL would you consider --strict-bool option to treat bool like not-an-int a good idea?

Sometimes I see code like:

def some(a: int): ...

some(x > 1)

And it drives me crazy! Currently AFAIK there's no way to find this issue with mypy.

[FooTaGe]

@sobolevn I don't see any runtime problems that can occur from from receiving a bool when expecting an int. Since bool is essentially an int.

only the opposite seems necessary

def some(a: bool): ...

some(x and 4)

Like Dict[str, int] is the correct type for Dict[Any, Any]

Also its seems python3 uses ints and bools interchangeably in the std functions:

Operations and built-in functions that have a Boolean result always return 0 or False for false and 1 or True for true, unless otherwise stated. (Important exception: the Boolean operations or and and always return one of their operands.)

from https://docs.python.org/3/library/stdtypes.html#typesnumeric

But it can force a more explicit form of writing. If for that reason it is still worth it? maybe.

First timer here, open for feedback-> PR #8346 decided to go with subclass

[rvanlaar]

@FooTaGe It doesn't break runtime, but returning an int, 0 or 1, when the expectation is an actual integer gives weird runtime problems.

I had written a function that accidentally returned the boolean value of an integer. Which did result in weird bugs. It was of course a programming error. However it was exactly the type of error I would expect a typing system to catch.

I sincerely hope that a --strict-bool option lands into MyPy.

[JelleZijlstra]

See psf/black#762 for a concrete example of a bug that the type checker didn't catch because bool is a subclass of int.

[sobolevn]

@JukkaL am I correct, that --strict-bool won't be happening? Do we need to still open a new issue for it?