Can @overload solve typing issue for int and Literal[value]?

[XCanG]

I have a case where I have a function that accept general int type and return str, however 0 is an exception that cannot be handled, so I return None in that case, the problem now is that I would have output str | None. While I have checks in some dynamic cases for None output, I also have some static cases where input always != 0, but because of output type hint I would have to add unnecessary checks which I want to avoid. I was trying to solve that with @overload, but IDE still complain about improper use of overloading.

Some pseudo-code:

@overload
def func(num: Literal[0]) -> None: ...

@overload
def func(num: int) -> str: ...

def func(num: int) -> str | None:
    if num == 0:
        return None
    # rest of the code that return str

The error I get in this case on 1st overload:

Overload 1 for "func" overlaps overload 2 and returns an incompatible type Pylance(reportOverlappingOverload)

Can you recommend me solution for better typing in this case?

[carljm]

There is no good solution for this case, because it would require having a type that represents "all ints except 0", which we do not have.

The problem is that 0 is an inhabitant of the type int, so if your function is called with a value typed as int, at runtime that value might actually be 0, the type checker just doesn't have a precise enough type to know whether it is or not. Consider, for example:

def other_func(x: int):
    v = func(x)

With your overload, the type checker will think that v must be str, but actually it could be None, because there's nothing preventing the call other_func(0) -- 0 is a valid int.

This is why your overlapping overload is an error.

If we had a type NonZeroInt, you could use that instead of int in your second overload, and then your overload would be sound. But you would only be allowed to call func with values of type Literal[0] or NonZeroInt, not with values of type int (since that wouldn't match either overload).

[XCanG]

Is there a way to use some different tech to achieve similar result without adding if checks?

[carljm]

It depends what you mean by a "similar result" and what tradeoffs you are willing to accept. I think you would have to establish a NonZeroInt type (which can be done today as a subclass of int that checks at construction that its value is not zero, or as a typing.NewType if you don't want any runtime checks and want to take responsibility yourself that you only construct it where the value cannot be zero), and then your overloads would look something like this:

@overload
def func(num: NonZeroInt) -> str: ...

@overload
def func(num: Literal[0]) -> None: ...

@overload
def func(num: int) -> str | None: ...

def func(num: int) -> str | None:
    if num == 0:
        return None

I've included a third overload here to also allow calling the function with int, in which case the return type will (correctly) be str | None. (Type checkers won't flag this as an overlapping overload, since the return type is a super-type of both str and int, making it sound.)

[XCanG]

I did that, but the new type NonZeroInt wasn't considering same as int, so if I declare some var, e.g. x = 5 and then call func(x) it is considering it as either Literal[5] or int which still fall back onto return type str | None. It will only work if I call it with x = NonZeroInt(5), but it will be basically same or worse than if check.

[carljm]

Yea, that's the fundamental problem. The correct return type for int really is str | None, because the type int includes 0 also. If you want to avoid the None part of the return type, you first have to tell the type system somehow that you have a nonzero int. And that will probably be just as awkward as dealing with the None return type, unless you can convert a large part of your system to passing around only the nonzero int type.

You can also ignore the overlapping overloads error, and get the behavior you were originally looking for. You just have to be aware that that behavior is unsound, and will tell you the return type is str when it might actually be None.