(🐞) TypeGuard behaves inconsistently on instance methods.

Bug Report

When type guards are implemented as methods, Mypy's type narrowing behaviour is inconsistent:

• It depends on whether the method only takes the implicit self argument or instead takes additional arguments.
• It further depends on whether the second argument has a default value, regardless of whether an explicit value is passed to it in the call expression.

This does not appear to be in compliance with appears to fall through the cracks of PEP 647, whose stated behaviour does not depend on any arguments further than the first explicit argument. Some relevant quotes from the PEP follow:

Type checkers should assume that type narrowing should be applied to the expression that is passed as the first positional argument to a user-defined type guard. If the type guard function accepts more than one argument, no type narrowing is applied to those additional argument expressions.

If the type guard function is implemented as an instance or class method, an implicit self or cls argument will also be passed to the function.

If a type guard function is implemented as an instance method or class method, the first positional argument maps to the second parameter (after self or cls).

A concern was raised that there may be cases where it is desired to apply the narrowing logic on self and cls. [...] It was [...] decided that no special provision would be made for it. If narrowing of self or cls is required, the value can be passed as an explicit argument to a type guard function.

Expected Behavior

In Issue #16146, it was clarified that the intent of PEP 647 is for positionality to depend on the call expression: the first positional argument is c in the call expression a.f(c), but it is a in the call expression A.f(a, c).

Now, consider the following pattern where a type guard is implemented by an instance method, with arbitrary arguments:

class A:
    def f(self, ...) -> TypeGuard[B]:
        #       ^^^ your choice of arguments here
        return isinstance(self, B)

class B(A): ...

The My expectation here is that call expressions in the form A.f(a, ...)—where ... here stands for arbitary values passed to other arguments in such a way as to make the call legal—will always result in type narrowing of a from a: A to a: B. This behaviour should be independent of the number of additional arguments and/or whether additional arguments are given default values (mentioned here because default values increase the number of legal call expressions).

Actual Behavior

In the three code snippets below, Mypy fails to apply this logic to the case where methods only take the implicit argument self, so that A.f(a) does not result in type narrowing for a while A.f(a, c) does. Furthermore, A.f(a, c) results in type narrowing behaviour for a when c is not given a default value, but fails to do so when a default value for c is specified, regardless of whether the call expression is A.f(a, c) (explicit value passed for c) or A.f(a) (default value used for c).

If the method f is implemented as a classmethod, A.f(a) results in type narrowing for a, as expected.

Pylance behaves as expected I expect in all cases.

To Reproduce

❌ Case 1: only self argument.

from __future__ import annotations
from typing import Any, TypeGuard, reveal_type

class A:
    def f(self) -> TypeGuard[B]:
        return isinstance(self, B)

class B(A): ...

a = A()

assert A.f(a)
reveal_type(a)
# Pylance: Type of "a" is "B"
# Mypy: Revealed type is "A"

b: B = a
# Mypy: Incompatible types in assignment (expression has type "A", variable has type "B")
# Pylance: OK

✅ Case 2: self argument plus one explicit argument.

from __future__ import annotations
from typing import TypeGuard, reveal_type

class A:
    def f(self, c: str) -> TypeGuard[B]:
        print(c)
        return isinstance(self, B)

class B(A): ...

a = A()
assert A.f(a, "Hi!")

reveal_type(a)
# Mypy: Revealed type is "B"
# Pylance: Type of "a" is "B"

b: B = a # No error

❌ Case 3: self argument plus one explicit argument with default value. Second argument passed explicitly in call expression.

from __future__ import annotations
from typing import Any, TypeGuard, reveal_type

class A:
    def f(self, c: str = "") -> TypeGuard[B]:
        print(c)
        return isinstance(self, B)

class B(A): ...

a = A()
assert A.f(a, "Hi!")
reveal_type(a)
# Mypy: Revealed type is "A"
# Pylance: Type of "a" is "B"

b: B = a
# Mypy: Incompatible types in assignment (expression has type "A", variable has type "B")
# Pylance: OK

❌ Case 4: self argument plus one explicit argument with default value. Default value for second argument used implicitly in call expression.

from __future__ import annotations
from typing import Any, TypeGuard, reveal_type

class A:
    def f(self, c: str = "") -> TypeGuard[B]:
        print(c)
        return isinstance(self, B)

class B(A): ...

a = A()
assert A.f(a)
reveal_type(a)
# Mypy: Revealed type is "A"
# Pylance: Type of "a" is "B"

b: B = a
# Mypy: Incompatible types in assignment (expression has type "A", variable has type "B")
# Pylance: OK

✅ Case 5: self argument plus two explicit arguments, only one of which has a default value. (Behaviour does not depend on whether the third argument is passed explicitly or not.)

from __future__ import annotations
from typing import Any, TypeGuard, reveal_type

class A:
    def f(self, c: str, d: int = 0) -> TypeGuard[B]:
        print(c)
        return isinstance(self, B)

class B(A): ...

a = A()
assert A.f(a, "Hi")
reveal_type(a)
# Mypy: Revealed type is "B"
# Pylance: Type of "a" is "B"

b: B = a # No error

✅ Case 6: like Case 1, but using a class method instead of an instance method.

from __future__ import annotations
from typing import Any, Self, TypeGuard, reveal_type

class A:
    @classmethod
    def f(cls, a: Self) -> TypeGuard[B]:
        return isinstance(a, B)

class B(A): ...

a = A()
assert A.f(a)
reveal_type(a)
# Mypy: Revealed type is "B"
# Pylance: Type of "a" is "B"

b: B = a # No error

Your Environment

• Mypy version used: mypy 1.7.1 (compiled: yes)
• Mypy command-line flags: --strict
• Mypy configuration options from mypy.ini (and other config files): None
• Python version used: Python 3.12.0

Inizia eseguendo i sei casi di riproduzione dell’issue con mypy 1.7.1 e confronta il narrowing riportato con i risultati attesi. Traccia la gestione di TypeGuard per le chiamate ai metodi di istanza, includendo self implicito e gli argomenti predefiniti; il lavoro è completato quando i casi relativi ai metodi di istanza applicano il narrowing in modo coerente con il comportamento PEP 647 indicato, senza regressioni nei casi che passano.