TypeGuard self

[povilasb]

1. Based on https://www.python.org/dev/peps/pep-0647/

When TypeGuard is used to annotate the return type of a function or method that accepts at least one parameter, that function or method is treated by type checkers as a user-defined type guard. The type argument provided for TypeGuard indicates the type that has been validated by the function.

2. @erictraut since this is your PEP I wonder what you'd think about expanding the scope of the TypeGuard to support narrowing the Self type when it is generic.

3. Let me give you an example with a monad type that I'm using:

class Result(Monad[T], Generic[T, E]):
    ...
    
 class Ok(Result[T, E]):
    def __init__(self, value: T) -> None:
        self.value = value
        
 class Err(Result[T, E]):
    def __init__(self, err: E) -> None:
        self.err = err

Say I have this function that resolves to Result during the runtime:

def fetch_data() -> Result[dict, Exception]:
    ...

When I want to narrow down the type, I can do this:

def is_ok(res: Result[T, Any]) -> TypeGuard[Ok[T]]:
   return isinstance(res, Ok)


def is_err(res: Result[Any, E]) -> TypeGuard[Err[E]]:
   return isinstance(res, Err)
   
res = fetch_data()
if is_ok(res):
   reveal_type(res)  # type is dict

4. Ideally I'd like it to be:

res = fetch_data()
if res.is_ok():
    reveal_type(res)  # type is dict

5. Unfortunately based on TypeGuard spec, I can't do it like this:

class Result(Monad[T], Generic[T, E]):

    def is_ok(self) -> TypeGuard[Ok[T]]:
        ...

    def is_err(self) -> TypeGuard[Err[E]]:
        ...

Since TypeGuard method requires an argument that will be "type guarded".
But conceptually I want to "type guard" self type when it is generic.

[erictraut]

This was specifically discussed when creating PEP 647, and it was rejected. Applying the TypeGuard to a self parameter would create an ambiguity because it wouldn't be clear whether to apply narrowing to the first or second parameter of the user-defined type guard function.

If you want to narrow the type of self, you can pass it explicitly to a user-defined function as you've done above.

So no, I think this would be a bad idea to extend PEP 647 in this manner, and I would strongly oppose any proposal to do so.

[povilasb]

A concern was raised that there may be cases where it is desired to apply the narrowing logic on self and cls. This is an unusual use case, and accommodating it would significantly complicate the implementation of user-defined type guards.

Can't argue with the extra complexity argument.

But, I assume things would become a lot simpler with a separate type, say SelfTypeGuard?

The use cases I see are purely with generic type narrowing using a method of self.
Technically not something that we can't do with is_of_type(obj) already, but obj.is_of_type() reads more naturally to me.
That being said, something like SelfTypeGuard would make Python typing system more expressive and allow engineers to choose themselves the preferred style for generic class type guards.

What do you think, Eric?

[erictraut]

Anyone is welcome to propose any extension to the Python type system, but I personally don't think that this use case is common enough to justify a new mechanism.

There's already a straightforward way to do this — pass self as an explicit argument. Adding a new mechanism would not make the typing system more expressive; it would simply provide a second way to do something that you can already do today. It may be less aesthetically pleasing to you, but it's effective, and it works fine in these rare scenarios where this is needed.

I'll also note that there's an active discussion about extending the existing TypeGuard to include a StrictTypeGuard option. If we added SelfTypeGuard, we'd need to also add a StrictSelfTypeGuard for completeness, and that seems even more unnecessary.

[GatienBouyer]

I found an alternative that works in my case using mypy 1.3.0, but not with Pyright (Pylance v2023.5.30 with Pyright 1.1.307)

from typing import Literal, final
from abc import ABC, abstractmethod


class Result(ABC):
	@property
	@abstractmethod
	def is_ok(self) -> bool: ...

@final
class Ok(Result):
	is_ok: Literal[True] = True
	def __init__(self, value: str) -> None:
		self.value = value

@final
class Err(Result):
	is_ok: Literal[False] = False
	def __init__(self, err: str) -> None:
		self.err = err

def fetch_data() -> Ok | Err:
	return Ok("ok")

res = fetch_data()
if res.is_ok:
	reveal_type(res)  # type is Ok

[erictraut]

Yes, this is intended behavior. You're attempting to use a type guard pattern that is intentionally not supported by pyright. For a full list of supported type guard patterns, refer to this documentation. If you change your code to res.is_ok == True or res.is_ok is True, pyright will narrow the type as you are hoping. The "truthy" check (without an == or is operator) is not supported for attribute-based discrimination because it would impose too high a computational cost at analysis time. It would force pyright to evaluate the type of every if conditional (and all dependent symbols) to determine whether it's potentially falsy or truthy. This is an example of a feature that would benefit very few pyright users but would have a measurable performance impact on all users. The tradeoff would not be worth it. Mypy's architecture and design objectives are different from pyright's. For more details, refer to this documentation.

[GatienBouyer]

I wasn't aware of this difference. Thank you for the clarification.