mypy doesn't distinguish between a `bool` and an `int`?

[PedanticHacker]

I have encountered a strange mypy error.

My function is defined like this:

def load_settings(table_name: str, key_name: str) -> bool | int:
    """Loads a setting value by the given table_name and key_name."""
    with open(constants.SETTINGS_FILE_PATH, "rb") as settings_file:
        settings = tomllib.load(settings_file)
    return settings[table_name][key_name]

And my variable is defined like this:

is_engine_black: bool = utilities.load_settings("engine", "black")  # Returns: True (so, a bool type)

But the error mypy outputs is this:

mypy: error
assignment - Incompatible types in assignment (expression has type "int", variable has type "bool")

The version of mypy used is 0.991. The operating system used is Windows 11 64-bit (updated to the latest version possible), running on Python 3.11. This error appears in Sublime Text 4 (its latest version of 4143) with the mentioned version of mypy and also in VSCode (also updated to the latest version possible and also updated its mypy extension to the latest version of 0.991 [at the time of writing this]).

So, tell me guys: WTF is going on here?

[hauntsaninja]

You've annotated your function as returning bool | int, so mypy is right to complain. The expression could be int, but your variable is bool.

If your question is why mypy says just int instead of bool | int, that's because bool is a subclass of int at runtime, so bool | int is basically equivalent to int

[PedanticHacker]

So, how should I annotate the return type(s) of my load_settings() function then?

My function can, indeed, return an int if a setting holds an integer value, or it can return a bool if a setting has a value of either True or False. It all depends on what is passed as the table_name and key_name arguments to it.

I know that the bool type is just a subtype of the int type. But annotating only int as a return type of my load_settings() function would be confusing.

What do you suggest?

[hauntsaninja]

Personally, I'd return Any. If you want to be type safe, you could also return a Union like currently, but add asserts. If your names are constants, overloads involving literals can achieve type safety without asserts.
#1693

[PedanticHacker]

overloads involving literals can achieve type safety without asserts

Can you please provide an example what you mean by this?

[gandhis1]

@overload
def load_settings(table_name: Literal["engine"], key_name: Literal["black"]) -> bool: ...

Obviously this doesn't scale well if you have many of these, which is why something like this I'd probably consider returning an object somewhere. Polymorphic return types are a trap in the annotations world.

[PedanticHacker]

Are you saying I should better just annotate the return type of my function as -> int?

def load_settings(table_name: str, key_name: str) -> int: ...

[erictraut]

Here are some alternatives that can help make your code more robust.

You could create separate wrapper functions for bool and int settings, like this:

def load_bool_setting(table_name: str, key_name: str) -> bool:
    setting = load_settings(table_name, key_name)
    if type(setting) != bool:
        raise ValueError(f"key {key_name} was not a bool as expected")
    return setting

Or you could make your original function generic so it handles any setting type:

T = TypeVar("T")

def load_typed_setting(table_name: str, key_name: str, expected_type: type[T]) -> T:
    with open(constants.SETTINGS_FILE_PATH, "rb") as settings_file:
        setting = tomllib.load(settings_file)
    if type(setting) != expected_type:
        raise ValueError(f"key {key_name} was not a {expected_type} as expected")
    return setting

[PedanticHacker]

I have now defined my load_setting() function like this:

def load_setting(group: str, name: str) -> bool | int:
    """Return a setting value by the given group and name."""
    with open("settings.toml", "rb") as settings_file:
        settings = tomllib.load(settings_file)
    return settings[group][name]

The usage of my load_setting() function could be something like this:

load_setting("engine", "pondering")

My settings.toml file looks like this:

[engine]
black = true
white = false
pondering = false

[clock]
time = 60
increment = 0

When I call my load_setting() function, it returns the value False, so the Python bool type representing the value False (and not false as is per TOML syntax stored in my settings.toml file). So, the return type of my load_setting() function is exactly as it should be.

Now, I can't, for the life of me, explain why (oh why?!) does mypy complain about the return type of my load_setting() function as being an int.

However, mypy does not complain if I pass the load_setting() function call to Python's built-in bool() function, so doing this is perfectly fine for mypy:

bool(load_setting("engine", "pondering"))

And only now is mypy finally satisfied. But having to use Python's bool() built-in function is strange. My load_setting() function returns False, but I still need to pass that to bool() just to make mypy to shut up.

Can anyone explain to me why is mypy not capable of handling the union type of a bool and an int?

[erictraut]

Mypy is enforcing the normal rules in the type system. Your function is annotated to return either a bool or an int, but you are attempting to assign it to a value that is declared to be a bool. Mypy is correctly pointing out a potential bug in your code. If your function happens to return an int value and you assign it to a variable that is declared as bool, you are violating the type of that variable. If your intent is for that variable to accept either a bool or an int, you can declare its type to be bool | int (or simply int, since bool is a subtype of int).

If you pass an int value to the constructor of bool, you will convert that value to a valid bool object. But is this really what you want to do? Let's say that the user of your program incorrectly configures his setting file to include the line pondering = 42. If you convert this value to a bool by calling bool(42), you will construct a value of True. Is this what you expect in this situation? More robust code would detect the unexpected value and inform the user that he probably didn't mean to use an integer value for this setting.

[PedanticHacker]

It won't be accurate to annotate the return type of my load_setting() function only as -> bool or only as -> int, because load_setting() can return either a bool or an int.

Let's see two uses of my load_setting() function when it returns a bool and when it returns an int.

load_setting("engine", "pondering")  # The return value is: False (i.e., a bool)
load_setting("clock", "time")  # The return value is: 60 (i.e., an int)

I am passing the result of my load_setting() function to another function which is not from my API but rather from a 3rd-party package, so I have no control over the 3rd-party function that receives the value as returned by my load_setting() function.

But, strangely enough, if I pass my load_setting() function in the form of bool(load_setting("engine", "pondering")) where a bool is expected by a 3rd-party function, mypy does not complain. The same goes for a 3rd-party function that expects an int where passing my load_setting() function in the form of int(load_setting("clock", "time")) does not receive any complaint by mypy.

Why does mypy not complain in the case of bool(load_setting("engine", "pondering")) and/or int(load_setting("clock", "time")) but does complain in the case of load_setting("engine", "pondering") and/or load_setting("clock", "time")?

[ikonst]

It won't be accurate to annotate the return type of my load_setting() function only as -> bool or only as -> int, because load_setting() can return either a bool or an int.

Yes.

I am passing the result of my load_setting() function to another function which is not from my API but rather from a 3rd-party package, so I have no control over the 3rd-party function that receives the value as returned by my load_setting() function.

Yes, this is how it usually is.

Why does mypy not complain in the case of bool(load_setting("engine", "pondering")) and/or int(load_setting("clock", "time")) but does complain in the case of load_setting("engine", "pondering") and/or load_setting("clock", "time")?

bool(anything) turns it into a bool type. For example bool("hello world") is a bool, and bool(my_database_object) is a bool.

Same for int(anything). int("hello world") is an int (even though it'll crash in runtime with TypeError, but it's you and me knowing that, not mypy).

If you had an load_settings which returned int | str, would it be clearer to you why:

value = load_settings("foo", "bar")
third_party_which_expects_str(value)

would detect a typing issue on the 2nd line?

[PedanticHacker]

bool(anything) turns it into a bool type. For example, bool("hello world") is a bool, and bool(my_database_object) is a bool.

Yes, @ikonst, I know this.

I want to know why do I need to use Python's built-in bool() function explicitly to shut up mypy. So, if a 3rd-party function receives a bool type value in the form of False, mypy complains. But if a 3rd-party function receives bool type value in the form of bool(False), mypy does not complain. Why is False not good enough? Why is only bool(False) good enough? Last time I checked: False == bool(False) # True, so they are equivalent. What is going on here?!

[JelleZijlstra]

It sounds like you are essentially doing this:

def some_function(arg: bool): ...

setting: bool | int = ...
some_function(setting)

Mypy obviously should complain about this: an int is not a bool.