Files

60 KiB

Methods

Background: Functions as descriptors

Note: See also this related section in the descriptor guide: Functions and methods.

Say we have a simple class C with a function definition f inside its body:

class C:
    def f(self, x: int) -> str:
        return "a"

Whenever we access the f attribute through the class object itself (C.f) or through an instance (C().f), this access happens via the descriptor protocol. Functions are (non-data) descriptors because they implement a __get__ method. This is crucial in making sure that method calls work as expected. In general, the signature of the __get__ method in the descriptor protocol is __get__(self, instance, owner). The self argument is the descriptor object itself (f). The passed value for the instance argument depends on whether the attribute is accessed from the class object (in which case it is None), or from an instance (in which case it is the instance of type C). The owner argument is the class itself (C of type Literal[C]). To summarize:

  • C.f is equivalent to getattr_static(C, "f").__get__(None, C)
  • C().f is equivalent to getattr_static(C, "f").__get__(C(), C)

Here, inspect.getattr_static is used to bypass the descriptor protocol and directly access the function attribute. The way the special __get__ method on functions works is as follows. In the former case, if the instance argument is None, __get__ simply returns the function itself. In the latter case, it returns a bound method object:

from inspect import getattr_static

reveal_type(getattr_static(C, "f"))  # revealed: def f(self, x: int) -> str

# revealed: <method-wrapper '__get__' of function 'f'>
reveal_type(getattr_static(C, "f").__get__)

reveal_type(getattr_static(C, "f").__get__(None, C))  # revealed: def f(self, x: int) -> str
reveal_type(getattr_static(C, "f").__get__(C(), C))  # revealed: bound method C.f(x: int) -> str

In conclusion, this is why we see the following two types when accessing the f attribute on the class object C and on an instance C():

reveal_type(C.f)  # revealed: def f(self, x: int) -> str
reveal_type(C().f)  # revealed: bound method C.f(x: int) -> str

A bound method is a callable object that contains a reference to the instance that it was called on (can be inspected via __self__), and the function object that it refers to (can be inspected via __func__):

bound_method = C().f

reveal_type(bound_method.__self__)  # revealed: C
reveal_type(bound_method.__func__)  # revealed: def f(self, x: int) -> str

When we call the bound method, the instance is implicitly passed as the first argument (self):

reveal_type(C().f(1))  # revealed: str
reveal_type(bound_method(1))  # revealed: str

When we call the function object itself, we need to pass the instance explicitly:

# error: [invalid-argument-type] "Argument to function `C.f` is incorrect: Expected `C`, found `Literal[1]`"
# error: [missing-argument]
C.f(1)

reveal_type(C.f(C(), 1))  # revealed: str

When we access methods from derived classes, they will be bound to instances of the derived class:

class D(C):
    pass

reveal_type(D().f)  # revealed: bound method D.f(x: int) -> str

If we access an attribute on a bound method object itself, it will defer to types.MethodType:

reveal_type(bound_method.__hash__)  # revealed: bound method MethodType.__hash__() -> int

If an attribute is not available on the bound method object, it will be looked up on the underlying function object. We model this explicitly, which means that we can access __kwdefaults__ on bound methods, even though it is not available on types.MethodType:

reveal_type(bound_method.__kwdefaults__)  # revealed: dict[str, Any] | None

Basic method calls on class objects and instances

class Base:
    def method_on_base(self, x: int | None) -> str:
        return "a"

class Derived(Base):
    def method_on_derived(self, x: bytes) -> tuple[int, str]:
        return (1, "a")

reveal_type(Base().method_on_base(1))  # revealed: str
reveal_type(Base.method_on_base(Base(), 1))  # revealed: str

Base().method_on_base("incorrect")  # error: [invalid-argument-type]
Base().method_on_base()  # error: [missing-argument]
Base().method_on_base(1, 2)  # error: [too-many-positional-arguments]

reveal_type(Derived().method_on_base(1))  # revealed: str
reveal_type(Derived().method_on_derived(b"abc"))  # revealed: tuple[int, str]
reveal_type(Derived.method_on_base(Derived(), 1))  # revealed: str
reveal_type(Derived.method_on_derived(Derived(), b"abc"))  # revealed: tuple[int, str]

Method calls on literals

Boolean literals

reveal_type(True.bit_length())  # revealed: int
reveal_type(True.as_integer_ratio())  # revealed: tuple[int, Literal[1]]

Integer literals

reveal_type((42).bit_length())  # revealed: int

String literals

reveal_type("abcde".find("abc"))  # revealed: int
reveal_type("foo".encode(encoding="utf-8"))  # revealed: bytes

"abcde".find(123)  # error: [invalid-argument-type]

Bytes literals

reveal_type(b"abcde".startswith(b"abc"))  # revealed: bool

Methods bound to a union of literals

A saved method keeps the union of its possible receivers. A method bound to LiteralString can also cover methods bound to specific strings.

from typing import Literal
from typing_extensions import LiteralString

def f(s: Literal["a", "b"], other: LiteralString, flag: bool):
    method = s.isalpha
    reveal_type(method.__self__)  # revealed: Literal["a", "b"]

    mixed = method if flag else other.isalpha
    reveal_type(mixed)  # revealed: bound method LiteralString.isalpha() -> bool

Method calls on LiteralString

from typing_extensions import LiteralString

def f(s: LiteralString) -> None:
    reveal_type(s.find("a"))  # revealed: int

Method calls on tuple

def f(t: tuple[int, str]) -> None:
    reveal_type(t.index("a"))  # revealed: int

Method calls on unions and intersections

[environment]
python-version = "3.14"

Method defined on multiple elements

Instance methods

When the called method is defined on multiple elements E1, E2 of the union or intersection, the return types are combined accordingly. Note that the method receiver is narrowed to E1 & E2 for the intersection case, which allows us to infer the return type as list[E1 & E2] instead of list[E1] & list[E2], which would be uninhabited. Doing the same for unions would be wrong though, since E1 | E2 is not a valid receiver for E1.f and E2.f, individually.

from typing import Self

class E1:
    def f(self) -> list[Self]:
        return [self]

class E2:
    def f(self) -> list[Self]:
        return [self]

def _(union: E1 | E2, intersection: E1 & E2):
    reveal_type(union.f)  # revealed: (bound method E1.f() -> list[E1]) | (bound method E2.f() -> list[E2])
    reveal_type(union.f())  # revealed: list[E1] | list[E2]

    # revealed: (bound method (E1 & E2).f() -> list[E1 & E2]) & (bound method (E1 & E2).f() -> list[E1 & E2])
    reveal_type(intersection.f)
    reveal_type(intersection.f())  # revealed: list[E1 & E2]

Analogous tests for method calls on objects of a generic type which is bounded by a union or intersection:

def generic_bounds[U: E1 | E2, I: E1 & E2](union: U, intersection: I):
    # revealed: (bound method (U@generic_bounds & E1).f() -> list[U@generic_bounds & E1]) | (bound method (U@generic_bounds & E2).f() -> list[U@generic_bounds & E2])
    reveal_type(union.f)
    reveal_type(union.f())  # revealed: list[U@generic_bounds & E1] | list[U@generic_bounds & E2]

    # revealed: (bound method I@generic_bounds.f() -> list[I@generic_bounds]) & (bound method I@generic_bounds.f() -> list[I@generic_bounds])
    reveal_type(intersection.f)
    reveal_type(intersection.f())  # revealed: list[I@generic_bounds]

Classmethods

The same works for classmethods, when accessed on unions or intersections of type[..] types:

from typing import Self

class E1:
    @classmethod
    def f(cls: type[Self]) -> list[Self]:
        return [cls()]

class E2:
    @classmethod
    def f(cls: type[Self]) -> list[Self]:
        return [cls()]

def _(
    union_external: type[E1] | type[E2],
    union_internal: type[E1 | E2],
    intersection_external: type[E1] & type[E2],
    intersection_internal: type[E1 & E2],
):
    # revealed: (bound method type[E1].f() -> list[E1]) | (bound method type[E2].f() -> list[E2])
    reveal_type(union_external.f)
    reveal_type(union_external.f())  # revealed: list[E1] | list[E2]

    # revealed: (bound method type[E1].f() -> list[E1]) | (bound method type[E2].f() -> list[E2])
    reveal_type(union_internal.f)
    reveal_type(union_internal.f())  # revealed: list[E1] | list[E2]

    # revealed: (bound method (type[E1] & type[E2]).f() -> list[E1 & E2]) & (bound method (type[E1] & type[E2]).f() -> list[E1 & E2])
    reveal_type(intersection_external.f)
    reveal_type(intersection_external.f())  # revealed: list[E1 & E2]

    # revealed: (bound method (type[E1] & type[E2]).f() -> list[E1 & E2]) & (bound method (type[E1] & type[E2]).f() -> list[E1 & E2])
    reveal_type(intersection_internal.f)
    reveal_type(intersection_internal.f())  # revealed: list[E1 & E2]

This also works with protocols:

from typing import Protocol

class G1[T]: ...
class G2[T]: ...

class P1(Protocol):
    @classmethod
    def f(cls: type[Self]) -> G1[Self]: ...

class P2(Protocol):
    @classmethod
    def f(cls: type[Self]) -> G2[Self]: ...

def _(
    union_external: type[P1] | type[P2],
    union_internal: type[P1 | P2],
    intersection_external: type[P1] & type[P2],
    intersection_internal: type[P1 & P2],
):
    # revealed: (() -> G1[P1]) | (() -> G2[P2])
    reveal_type(union_external.f)
    reveal_type(union_external.f())  # revealed: G1[P1] | G2[P2]

    # revealed: (() -> G1[P1]) | (() -> G2[P2])
    reveal_type(union_internal.f)
    reveal_type(union_internal.f())  # revealed: G1[P1] | G2[P2]

    # TODO: this should not leak the Self@f type variables
    # revealed: (() -> G1[Self@f]) & (() -> G2[Self@f])
    reveal_type(intersection_external.f)
    # TODO: this should be `G1[P1 & P2] & G2[P1 & P2]`
    reveal_type(intersection_external.f())  # revealed: G1[Self@f] & G2[Self@f]

    # TODO: this should not leak the Self@f type variables
    # revealed: (() -> G1[Self@f]) & (() -> G2[Self@f])
    reveal_type(intersection_internal.f)
    # TODO: this should be `G1[P1 & P2] & G2[P1 & P2]`
    reveal_type(intersection_internal.f())  # revealed: G1[Self@f] & G2[Self@f]

Method defined on a single element

Instance methods

If the called method is defined on only one element, attribute access fails on the union, but still succeeds on the intersection type:

from typing import Self

class E1:
    def f(self) -> list[Self]:
        return [self]

class E2: ...

def _(union_12: E1 | E2, union_21: E2 | E1, intersection_12: E1 & E2, intersection_21: E2 & E1):
    # error: [missing-union-attribute]
    reveal_type(union_12.f)  # revealed: bound method E1.f() -> list[E1]
    # error: [missing-union-attribute]
    reveal_type(union_12.f())  # revealed: list[E1]

    # error: [missing-union-attribute]
    reveal_type(union_21.f)  # revealed: bound method E1.f() -> list[E1]
    # error: [missing-union-attribute]
    reveal_type(union_21.f())  # revealed: list[E1]

    reveal_type(intersection_12.f)  # revealed: bound method (E1 & E2).f() -> list[E1 & E2]
    reveal_type(intersection_12.f())  # revealed: list[E1 & E2]

    reveal_type(intersection_21.f)  # revealed: bound method (E2 & E1).f() -> list[E2 & E1]
    reveal_type(intersection_21.f())  # revealed: list[E2 & E1]

Analogous tests for method calls on objects of a generic type which is bounded by a union or intersection:

def generic_bounds[U: E1 | E2, I: E1 & E2](union: U, intersection: I):
    # revealed: bound method (U@generic_bounds & E1).f() -> list[U@generic_bounds & E1]
    # error: [missing-union-attribute]
    reveal_type(union.f)
    # error: [missing-union-attribute]
    reveal_type(union.f())  # revealed: list[U@generic_bounds & E1]

    # revealed: bound method I@generic_bounds.f() -> list[I@generic_bounds]
    reveal_type(intersection.f)
    reveal_type(intersection.f())  # revealed: list[I@generic_bounds]

Classmethods

Same for classmethods:

from typing import Self

class E1:
    @classmethod
    def f(cls: type[Self]) -> list[Self]:
        return [cls()]

class E2: ...

def _(
    union_external: type[E1] | type[E2],
    union_internal: type[E1 | E2],
    intersection_external: type[E1] & type[E2],
    intersection_internal: type[E1 & E2],
):
    # error: [missing-union-attribute]
    reveal_type(union_external.f)  # revealed: bound method type[E1].f() -> list[E1]
    # error: [missing-union-attribute]
    reveal_type(union_external.f())  # revealed: list[E1]

    # error: [missing-union-attribute]
    reveal_type(union_internal.f)  # revealed: bound method type[E1].f() -> list[E1]
    # error: [missing-union-attribute]
    reveal_type(union_internal.f())  # revealed: list[E1]

    # revealed: bound method (type[E1] & type[E2]).f() -> list[E1 & E2]
    reveal_type(intersection_external.f)
    reveal_type(intersection_external.f())  # revealed: list[E1 & E2]

    # revealed: bound method (type[E1] & type[E2]).f() -> list[E1 & E2]
    reveal_type(intersection_internal.f)
    reveal_type(intersection_internal.f())  # revealed: list[E1 & E2]

This also works with protocols:

from typing import Protocol

class P1(Protocol):
    @classmethod
    def f(cls: type[Self]) -> list[Self]: ...

class Other: ...

def _(
    union_external: type[P1] | type[Other],
    union_internal: type[P1 | Other],
    intersection_external: type[P1] & type[Other],
    intersection_internal: type[P1 & Other],
):
    # error: [missing-union-attribute]
    # revealed: () -> list[P1]
    reveal_type(union_external.f)
    # error: [missing-union-attribute]
    reveal_type(union_external.f())  # revealed: list[P1]

    # error: [missing-union-attribute]
    # revealed: () -> list[P1]
    reveal_type(union_internal.f)
    # error: [missing-union-attribute]
    reveal_type(union_internal.f())  # revealed: list[P1]

    # TODO: this should not leak the Self@f type variable
    # revealed: () -> list[Self@f]
    reveal_type(intersection_external.f)
    # TODO: this should be list[P1 & Other]
    reveal_type(intersection_external.f())  # revealed: list[Self@f]

    # TODO: this should not leak the Self@f type variable
    # revealed: () -> list[Self@f]
    reveal_type(intersection_internal.f)
    # TODO: this should be list[P1 & Other]
    reveal_type(intersection_internal.f())  # revealed: list[Self@f]

Method defined on a single element and a dynamic type

from typing import Self, Any

class E1:
    def f(self) -> list[Self]:
        return [self]

def _(union: E1 | Any, intersection: E1 & Any):
    reveal_type(union.f)  # revealed: (bound method E1.f() -> list[E1]) | Any
    reveal_type(union.f())  # revealed: list[E1] | Any

    reveal_type(intersection.f)  # revealed: (bound method (E1 & Any).f() -> list[E1 & Any]) & Any
    reveal_type(intersection.f())  # revealed: list[E1 & Any] & Any

Stored protocol-bound methods

A protocol-bound method stored alongside another callable must not re-check its already-bound receiver when the callable union is invoked.

from collections.abc import Iterator
from typing import Any

class PeekIterator(Iterator[Any]):
    def __init__(self, iterator: Iterator[Any]) -> None:
        self._next = iterator.__next__

    def __next__(self) -> Any:
        return self._next()

    def use_fallback(self) -> None:
        self._next = lambda: None

Only a genuine implicit positional receiver can be consumed before call inference. Other parameter shapes must continue through the ordinary bound-method call path.

from typing import Protocol

class Variadic(Protocol):
    def method(*args: int) -> int: ...

def check_variadic(value: Variadic) -> None:
    value.method()  # error: [invalid-argument-type]

Bound methods without a positional receiver

A method can be retrieved from an instance even when it cannot accept the implicit receiver (has zero parameters):

from typing import Callable, Protocol

class NoReceiver:
    def method() -> int:
        return 1

bound_method = NoReceiver().method

However, this method cannot be called:

bound_method()  # error: [too-many-positional-arguments]

This method also cannot be assigned to a callable that expects no positional arguments:

c1: Callable[[], int] = bound_method  # error: [invalid-assignment]

When accessed on the class, method can be called and can be assigned to a callable that expects no positional arguments:

NoReceiver.method()
c2: Callable[[], int] = NoReceiver.method

The bound method cannot be assigned to a protocol with a method that expects a receiver in this position, so this assignment fails:

class HasMethod(Protocol):
    def method(self) -> int: ...

# snapshot: invalid-assignment
m: HasMethod = NoReceiver()

Our error message here could be better:

error[invalid-assignment]: Object of type `NoReceiver` is not assignable to `HasMethod`
  --> src/mdtest_snippet.py:16:16
   |
16 | m: HasMethod = NoReceiver()
   |    ---------   ^^^^^^^^^^^^ Incompatible value of type `NoReceiver`
   |    |
   |    Declared type
info: type `NoReceiver` is not assignable to protocol `HasMethod`
info: └── protocol member `method` is incompatible

Bound methods with various shapes of receivers

[environment]
python-version = "3.11"

All of these are valid ways to define a receiver for a method:

from typing import Callable, Protocol, Self

class Valid:
    def named(self) -> int:
        return 1

    def differently_named(receiver) -> int:
        return 1

    def positional_only(self, /) -> int:
        return 1

    def variadic(*args) -> int:
        return 1

    def unpacked(*args: *tuple[Self]) -> int:
        return 1

reveal_type(Valid().named())  # revealed: int
reveal_type(Valid().differently_named())  # revealed: int
reveal_type(Valid().positional_only())  # revealed: int
reveal_type(Valid().variadic())  # revealed: int
reveal_type(Valid().unpacked())  # revealed: int

On the other hand, these are all invalid:

from typing import Protocol

class Invalid:
    def wrong_type(self: int) -> int:
        return 1

    def keyword_only(*, self) -> int:
        return 1

    def keyword_variadic(**kwargs: int) -> int:
        return 1

    def variadic_wrong_type(*args: int) -> int:
        return 1

    def unpacked_wrong_type(*args: *tuple[int]) -> int:
        return 1

    def unpacked_empty(*args: *tuple[()]) -> int:
        return 1

# error: [invalid-argument-type]
Invalid().wrong_type()

# error: [missing-argument]
# error: [too-many-positional-arguments]
Invalid().keyword_only()

# error: [too-many-positional-arguments]
Invalid().keyword_variadic()

# error: [invalid-argument-type]
Invalid().variadic_wrong_type()

# error: [invalid-argument-type]
Invalid().unpacked_wrong_type()

# error: [too-many-positional-arguments]
Invalid().unpacked_empty()

Self in unpacked bound-method parameters

Binding a receiver consumes the first element of a fixed unpacked tuple:

[environment]
python-version = "3.12"
from collections.abc import Callable
from typing import Self

class C:
    def method(*args: *tuple[Self, int, Self]) -> None: ...
    @classmethod
    def class_method(*args: *tuple[type[Self], int, Self]) -> None: ...

C().method(1, C())
C.class_method(1, C())

base: Callable[[int, C], None] = C().method
class_base: Callable[[int, C], None] = C.class_method

Method calls on KnownInstance types

[environment]
python-version = "3.12"
type IntOrStr = int | str

reveal_type(IntOrStr.__or__)  # revealed: bound method TypeAliasType.__or__(right: Any, /) -> _SpecialForm

Method calls on types not disjoint from None

Very few methods are defined on object, None, and other types not disjoint from None. However, descriptor-binding behavior works on these types in exactly the same way as descriptor binding on other types. This is despite the fact that None is used as a sentinel internally by the descriptor protocol to indicate that a method was accessed on the class itself rather than an instance of the class:

from typing import Protocol, Literal
from ty_extensions import AlwaysFalsy

class Foo: ...

class SupportsStr(Protocol):
    def __str__(self) -> str: ...

class Falsy(Protocol):
    def __bool__(self) -> Literal[False]: ...

def _(a: object, b: SupportsStr, c: Falsy, d: AlwaysFalsy, e: None, f: Foo | None):
    a.__str__()
    b.__str__()
    c.__str__()
    d.__str__()
    e.__str__()
    f.__str__()

Method calls on subclasses of Any

from typing_extensions import assert_type, Any

class SubclassOfAny(Any):
    def method(self) -> int:
        return 1

a = SubclassOfAny()
assert_type(a.method(), int)

value: str = a.method()  # error: [invalid-assignment]

assert_type(a.non_existing_method(), Any)

Shadowing methods

Explanation and basic examples

Consider the following example where a method on a class can be dynamically swapped with another method:

class C:
    def method(self, x: int) -> str:
        print("original")
        return str(x)

    def some_compatible_method(self, x: int) -> str:
        print("replaced")
        return str(x)

    def swap(self) -> None:
        self.method = self.some_compatible_method

c = C()
c.swap()

When swap is called, self.some_compatible_method creates a bound method object which is assigned to the instance attribute self.method, i.e. it shadows the function defined on the class itself (C.method). At runtime, when c.method is accessed, Python first looks up method on the class itself. It finds the original function C.method, but since it is a non-data descriptor, attribute lookup continues to check if there is an attribute on the instance itself (see descriptor_protocol.md for details). In this case, it finds the bound method object referring to self.some_compatible_method and returns it without calling __get__, i.e. the function is not bound to the instance "again".

In summary, calling c.method(42) works, returns a string, and prints "replaced":

reveal_type(c.method(42))  # revealed: str

We can see that C.method is not actually replaced, though. Calling C.method(c, 42) directly still invokes the original function on the class. It prints "original" and returns a string.

reveal_type(C.method(c, 42))  # revealed: str

Since this is a common pattern, ty does support it. We generally allow this replacement if the callable being assigned has a signature that is compatible with the original method:

from typing import Callable

class Correct:
    def method(self, x: int, /) -> str:
        return str(x)

    def compatible_method(self, x: int, /) -> str:
        return str(x)

    def swap(self, replacement: Callable[[int], str]) -> None:
        self.method = self.compatible_method

        self.method = replacement

        self.method = lambda x: str(x)

        class CompatibleCallable:
            def __call__(self, x: int) -> str:
                return str(x)

        self.method = CompatibleCallable()

We emit diagnostics if the signature is not compatible:

class Wrong:
    def method(self, x: int, /) -> str:
        return str(x)

    def incompatible_method1(self, x: str, /) -> str:
        return x

    def incompatible_method2(self, /) -> str:
        return ""

    def swap(self, wrong_replacement: Callable[[str], str]) -> None:
        self.method = self.incompatible_method1  # error: [invalid-assignment]
        self.method = self.incompatible_method2  # error: [invalid-assignment]
        self.method = wrong_replacement  # error: [invalid-assignment]
        self.method = lambda: ""  # error: [invalid-assignment]
        self.method = lambda self, x: ""  # error: [invalid-assignment]
        self.method = lambda x: x  # error: [invalid-assignment]
        self.method = Wrong.method  # error: [invalid-assignment]

Keyword arguments

If callers can pass x by keyword, the shadowing callable must also accept that keyword. Both lambdas below accept a positional argument, but only the first accepts x=42.

class C:
    def method(self, x: int) -> str:
        return str(x)

    def swap(self) -> None:
        self.method = lambda x: str(x)

    def swap_with_different_keyword(self) -> None:
        self.method = lambda y: str(y)  # error: [invalid-assignment]

c = C()
c.swap()
c.method(x=42)

When a method accepts arguments only by keyword, a shadowing lambda can list those parameters in either order. Here, callers pass y by name, so the lambda's y should be inferred as int.

class D:
    def method(self, *, x: str, y: int) -> int:
        return y

    def swap(self) -> None:
        self.method = lambda x, y: y + 1
        # TODO: Infer the lambda's parameter types by name for keyword-only arguments.
        # See https://github.com/astral-sh/ty/issues/4935
        # error: [invalid-assignment]
        # error: [unsupported-operator]
        self.method = lambda y, x: y + 1

Classmethods and static methods

The same reasoning applies to classmethods and static methods:

class C:
    @classmethod
    def class_method(cls, x: int) -> str:
        return str(x)

    @staticmethod
    def static_method(x: int) -> str:
        return str(x)

    def swap(self) -> None:
        self.class_method = lambda x: str(x)
        self.static_method = lambda x: str(x)

        reveal_type(self.class_method(42))  # revealed: str
        reveal_type(self.static_method(42))  # revealed: str

Replacing with an invalid signature is an error:

        self.class_method = lambda x: x  # error: [invalid-assignment]
        self.static_method = lambda x: x  # error: [invalid-assignment]

Unsoundness

Shadowing a method in the way described above is actually unsound. For one, since we allow replacement with arbitrary callables, we cannot guarantee that the replacement will have all attributes that the original bound method had. Consider:

from typing import Callable

class Problematic:
    def method(self, x: int, /) -> str:
        return str(x)

    def swap(self) -> None:
        class CompatibleCallable:
            def __call__(self, x: int) -> str:
                return str(x)

        self.method = CompatibleCallable()

p = Problematic()

Attributes like __self__ are usually present on bound methods (demonstrating with p.swap here):

p.swap.__self__  # ok

However, after we call swap(), the method attribute is replaced with a callable that is not a bound method, and thus lacks the __self__ attribute. ty does not aim to track this, and therefore does not emit an error for the missing __self__ attribute:

p.swap()
p.method.__self__

Maybe more importantly, consider what happens if the class is subclassed. Since we only checked the replacement against the base class method's signature, shadowing the method in the subclass may lead to inconsistencies:

class C:
    def method(self, x: int) -> object:
        return x

    def seemingly_compatible(self, x: int) -> object:
        return x

    def swap(self) -> None:
        # TODO: with a proposed strict rule, this should be an error
        self.method = self.seemingly_compatible

class D(C):
    def method(self, x: int) -> str:
        return str(x)

If we call swap() on a D instance, method promises to return a str, but returns an int instead:

d = D()
d.swap()

reveal_type(d.method(42))  # revealed: str

We might therefore consider implementing a stricter check that emits a diagnostic on the problematic self.method = self.seemingly_compatible assignment above.

Explicitly annotated instance attributes

When the instance attribute assignment is explicitly annotated with a type that is incompatible with the method it shadows, we assume that shadowing is intentional, and prefer the annotation over the method's type:

class C:
    def f(self) -> int:
        return 1

    def __init__(self) -> None:
        self.f: str = "foo"

# TODO: The explicit annotation should make this a `str`.
reveal_type(C().f)  # revealed: bound method C.f() -> int
# TODO: This should emit `not-callable`.
C().f()

Identity of a shadowed static method

A static method that can optionally be replaced should not retain its identity as a singleton type that refers to def format:

from typing import Callable

class Formatter:
    @staticmethod
    def format(text: str, /) -> str:
        return text

    def __init__(self, custom: Callable[[str], str] | None = None) -> None:
        if custom is not None:
            self.format = custom

def check(formatter: Formatter) -> None:
    reveal_type(formatter.format("hello"))  # revealed: str
    # TODO: This should be `bool` because the instance may hold the custom callable.
    reveal_type(formatter.format is Formatter.format)  # revealed: Literal[True]

Error cases: Calling __get__ for methods

The __get__ method on types.FunctionType has the following overloaded signature in typeshed:

from types import FunctionType, MethodType
from typing import overload

@overload
def __get__(self, instance: None, owner: type, /) -> FunctionType: ...
@overload
def __get__(self, instance: object, owner: type | None = None, /) -> MethodType: ...

Here, we test that this signature is enforced correctly:

from inspect import getattr_static

class C:
    def f(self, x: int) -> str:
        return "a"

method_wrapper = getattr_static(C, "f").__get__

reveal_type(method_wrapper)  # revealed: <method-wrapper '__get__' of function 'f'>

# All of these are fine:
method_wrapper(C(), C)
method_wrapper(C())
method_wrapper(C(), None)
method_wrapper(None, C)

reveal_type(object.__str__.__get__(object(), None)())  # revealed: str

# TODO: passing `None` without an `owner` argument fails at runtime.
# Ideally we would emit a diagnostic here:
method_wrapper(None)

# Passing something that is not assignable to `type` as the `owner` argument is an
# error: [no-matching-overload] "No overload of method wrapper `__get__` of function `f` matches arguments"
method_wrapper(None, 1)

# TODO: passing `None` as the `owner` argument when `instance` is `None` fails at runtime.
# Ideally we would emit a diagnostic here.
method_wrapper(None, None)

# Calling `__get__` without any arguments is an
# error: [no-matching-overload] "No overload of method wrapper `__get__` of function `f` matches arguments"
method_wrapper()

# Calling `__get__` with too many positional arguments is an
# error: [no-matching-overload] "No overload of method wrapper `__get__` of function `f` matches arguments"
method_wrapper(C(), C, "one too many")

Fallback to metaclass

When a method is accessed on a class object, it is looked up on the metaclass if it is not found on the class itself. This also creates a bound method that is bound to the class object itself:

from __future__ import annotations

class Meta(type):
    def f(cls, arg: int) -> str:
        return "a"

class C(metaclass=Meta):
    pass

reveal_type(C.f)  # revealed: bound method <class 'C'>.f(arg: int) -> str
reveal_type(C.f(1))  # revealed: str

The method f cannot be accessed from an instance of the class:

# error: [missing-attribute] "Object of type `C` has no attribute `f`"
C().f

A metaclass function can be shadowed by a method on the class:

from typing import Any, Literal

class D(metaclass=Meta):
    def f(arg: int) -> Literal["a"]:
        return "a"

reveal_type(D.f(1))  # revealed: Literal["a"]

If the class method is possibly missing, we union the return types:

def flag() -> bool:
    return True

class E(metaclass=Meta):
    if flag():
        def f(arg: int) -> Any:
            return "a"

reveal_type(E.f(1))  # revealed: str | Any

@classmethod

Basic

When a @classmethod attribute is accessed, it returns a bound method object, even when accessed on the class object itself:

from __future__ import annotations

class C:
    @classmethod
    def f(cls: type[C], x: int) -> str:
        return "a"

reveal_type(C.f)  # revealed: bound method <class 'C'>.f(x: int) -> str
reveal_type(C().f)  # revealed: bound method type[C].f(x: int) -> str

The cls method argument is then implicitly passed as the first argument when calling the method:

reveal_type(C.f(1))  # revealed: str
reveal_type(C().f(1))  # revealed: str

When the class method is called incorrectly, we detect it:

C.f("incorrect")  # error: [invalid-argument-type]
C.f()  # error: [missing-argument]
C.f(1, 2)  # error: [too-many-positional-arguments]

If the cls parameter is wrongly annotated, we emit an error at the call site:

class D:
    @classmethod
    def f(cls: D):
        # This function is wrongly annotated, it should be `type[D]` instead of `D`
        pass

# error: [invalid-argument-type] "Argument to bound method `D.f` is incorrect: Expected `D`, found `<class 'D'>`"
D.f()

When a class method is accessed on a derived class, it is bound to that derived class:

class Derived(C):
    pass

reveal_type(Derived.f)  # revealed: bound method <class 'Derived'>.f(x: int) -> str
reveal_type(Derived().f)  # revealed: bound method type[Derived].f(x: int) -> str

reveal_type(Derived.f(1))  # revealed: str
reveal_type(Derived().f(1))  # revealed: str

Implicit receivers in generic final classes

For a generic final class, an implicit type[Self] receiver can bind to another classmethod on the exact generic class object:

[environment]
python-version = "3.12"
from typing import final

@final
class GenericFinal[T]:
    @classmethod
    def call_method(cls) -> None:
        cls.method()

    @classmethod
    def method(cls) -> None: ...

Accessing the classmethod as a static member

inspect.getattr_static bypasses descriptor binding and returns the classmethod descriptor. Ordinary attribute access (C.f or C().f) instead returns a bound method. We model the descriptor explicitly, but display it using the wrapped function's name and signature:

from inspect import getattr_static

class C:
    @classmethod
    def f(cls): ...

reveal_type(getattr_static(C, "f"))  # revealed: def f(cls) -> Unknown
# revealed: <method-wrapper '__get__' of function 'f'>
reveal_type(getattr_static(C, "f").__get__)

Calling the classmethod descriptor's __get__ binds the wrapped function to the class:

reveal_type(getattr_static(C, "f").__get__(None, C))  # revealed: bound method <class 'C'>.f() -> Unknown
reveal_type(getattr_static(C, "f").__get__(C(), C))  # revealed: bound method <class 'C'>.f() -> Unknown
reveal_type(getattr_static(C, "f").__get__(C()))  # revealed: bound method type[C].f() -> Unknown

The owner argument takes precedence over the instance argument:

reveal_type(getattr_static(C, "f").__get__("dummy", C))  # revealed: bound method <class 'C'>.f() -> Unknown

Classmethods mixed with other decorators

[environment]
python-version = "3.12"

When a @classmethod is additionally decorated with another decorator, it is still treated as a class method:

def does_nothing[T](f: T) -> T:
    return f

class C:
    @classmethod
    @does_nothing
    def f1(cls, x: int) -> str:
        return "a"

    @does_nothing
    @classmethod
    def f2(cls, x: int) -> str:
        return "a"

reveal_type(C.f1(1))  # revealed: str
reveal_type(C().f1(1))  # revealed: str
reveal_type(C.f2(1))  # revealed: str
reveal_type(C().f2(1))  # revealed: str

Classmethods with Self and callable-returning decorators

When a classmethod is decorated with a decorator that returns a callable type (like @contextmanager), Self in the return type should correctly resolve to the subclass when accessed on a derived class.

from contextlib import contextmanager
from collections.abc import Generator
from typing_extensions import Self

class Base:
    @classmethod
    @contextmanager
    def create(cls) -> Generator[Self, None, None]:
        yield cls()

class Child(Base): ...

reveal_type(Base.create())  # revealed: _GeneratorContextManager[Base, None, None]
with Base.create() as base:
    reveal_type(base)  # revealed: Base

reveal_type(Base().create())  # revealed: _GeneratorContextManager[Base, None, None]
with Base().create() as base:
    reveal_type(base)  # revealed: Base

reveal_type(Child.create())  # revealed: _GeneratorContextManager[Child, None, None]
with Child.create() as child:
    reveal_type(child)  # revealed: Child

reveal_type(Child().create())  # revealed: _GeneratorContextManager[Child, None, None]
with Child().create() as child:
    reveal_type(child)  # revealed: Child

__init_subclass__

Basics

The __init_subclass__ method is implicitly a classmethod:

class Base:
    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.custom_attribute: int = 0

class Derived(Base):
    pass

reveal_type(Derived.custom_attribute)  # revealed: int

Subclasses must be constructed with arguments matching the required arguments of the base __init_subclass__ method.

class Empty: ...

class RequiresArg:
    def __init_subclass__(cls, arg: int): ...

class NoArg:
    def __init_subclass__(cls): ...

Single-base definitions

# snapshot: missing-argument
class MissingArg(RequiresArg): ...
error[missing-argument]: No argument provided for required parameter `arg` of function `RequiresArg.__init_subclass__`
  --> src/mdtest_snippet.py:18:1
   |
18 | class MissingArg(RequiresArg): ...
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
info: Parameter declared here
  --> src/mdtest_snippet.py:13:32
   |
13 |     def __init_subclass__(cls, arg: int): ...
   |                                ^^^^^^^^
# snapshot: invalid-argument-type
class InvalidType(RequiresArg, arg="foo"): ...
class Valid(RequiresArg, arg=1): ...
error[invalid-argument-type]: Argument to function `RequiresArg.__init_subclass__` is incorrect
  --> src/mdtest_snippet.py:20:32
   |
20 | class InvalidType(RequiresArg, arg="foo"): ...
   |                                ^^^^^^^^^ Expected `int`, found `Literal["foo"]`
info: Function defined here
  --> src/mdtest_snippet.py:13:9
   |
13 |     def __init_subclass__(cls, arg: int): ...
   |         ^^^^^^^^^^^^^^^^^      -------- Parameter declared here
# snapshot: missing-argument
# snapshot: unknown-argument
class IncorrectArg(RequiresArg, not_arg="foo"):
    a = 1
    b = 2
    c = 3
    d = 4
    e = 5
    f = 6
    g = 7
    h = 8
    i = 9
    j = 10
error[missing-argument]: No argument provided for required parameter `arg` of function `RequiresArg.__init_subclass__`
  --> src/mdtest_snippet.py:24:1
   |
24 | class IncorrectArg(RequiresArg, not_arg="foo"):
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
info: Parameter declared here
  --> src/mdtest_snippet.py:13:32
   |
13 |     def __init_subclass__(cls, arg: int): ...
   |                                ^^^^^^^^


error[unknown-argument]: Argument `not_arg` does not match any known parameter of function `RequiresArg.__init_subclass__`
  --> src/mdtest_snippet.py:24:33
   |
24 | class IncorrectArg(RequiresArg, not_arg="foo"):
   |                                 ^^^^^^^^^^^^^
info: Function signature here
  --> src/mdtest_snippet.py:13:9
   |
13 |     def __init_subclass__(cls, arg: int): ...
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
class NotCallableInitSubclass:
    __init_subclass__ = None

# snapshot: non-callable-init-subclass
class Bad(NotCallableInitSubclass):
    a = 1
    b = 2
    c = 3
error[non-callable-init-subclass]: Invalid definition of class `Bad`
  --> src/mdtest_snippet.py:39:7
   |
36 |     __init_subclass__ = None
   |     ----------------- `NotCallableInitSubclass.__init_subclass__` has type `None | Unknown`, which may not be callable
37 |
38 | # snapshot: non-callable-init-subclass
39 | class Bad(NotCallableInitSubclass):
   |       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Superclass `NotCallableInitSubclass` cannot be subclassed
info: `__init_subclass__` on a superclass is implicitly called during creation of a class object
info: See https://docs.python.org/3/reference/datamodel.html#customizing-class-creation

The metaclass keyword is ignored, as it has special meaning and is not passed to __init_subclass__ at runtime.

class Base:
    def __init_subclass__(cls, arg: int): ...

class Valid(Base, arg=5, metaclass=object): ...

# error: [invalid-argument-type]
class Invalid(Base, metaclass=type, arg="foo"): ...

Overload matching is performed correctly:

from typing import Literal, overload

class Base:
    @overload
    def __init_subclass__(cls, mode: Literal["a"], arg: int) -> None: ...
    @overload
    def __init_subclass__(cls, mode: Literal["b"], arg: str) -> None: ...
    def __init_subclass__(cls, mode: str, arg: int | str) -> None: ...

class Valid(Base, mode="a", arg=5): ...
class Valid(Base, mode="b", arg="foo"): ...

# error: [no-matching-overload]
class InvalidType(Base, mode="b", arg=5):
    a = 1
    b = 2
    c = 3
    d = 4
    e = 5

More complex cases

For multiple inheritance, the first resolved __init_subclass__ method is used.

[environment]
python-version = "3.12"
class Empty: ...

class RequiresArg:
    def __init_subclass__(cls, arg: int): ...

class NoArg:
    def __init_subclass__(cls): ...

class Valid(NoArg, RequiresArg): ...
class MissingArg(RequiresArg, NoArg): ...  # error: [missing-argument]
class InvalidType(RequiresArg, NoArg, arg="foo"): ...  # error: [invalid-argument-type]
class Valid(RequiresArg, NoArg, arg=1): ...

# Ensure base class without __init_subclass__ is ignored
class Valid(Empty, NoArg): ...
class Valid(Empty, RequiresArg, NoArg, arg=1): ...
class MissingArg(Empty, RequiresArg): ...  # error: [missing-argument]
class MissingArg(Empty, RequiresArg, NoArg): ...  # error: [missing-argument]
class InvalidType(Empty, RequiresArg, NoArg, arg="foo"): ...  # error: [invalid-argument-type]

# Multiple inheritance with args
class Base(Empty, RequiresArg, NoArg, arg=1): ...
class Valid(Base, arg=1): ...
class MissingArg(Base): ...  # error: [missing-argument]
class InvalidType(Base, arg="foo"): ...  # error: [invalid-argument-type]

Keyword splats are allowed if their type can be determined:

from typing import TypedDict

class RequiresKwarg:
    def __init_subclass__(cls, arg: int): ...

class WrongArg(TypedDict):
    kwarg: int

class InvalidType(TypedDict):
    arg: str

wrong_arg: WrongArg = {"kwarg": 5}

# error: [missing-argument]
# error: [unknown-argument]
class MissingArg(RequiresKwarg, **wrong_arg): ...

invalid_type: InvalidType = {"arg": "foo"}

# error: [invalid-argument-type]
class InvalidType(RequiresKwarg, **invalid_type): ...

So are generics:

from typing import Generic, TypeVar, Literal, overload

class Base[T]:
    def __init_subclass__(cls, arg: T): ...

class Valid(Base[int], arg=1): ...
class InvalidType(Base[int], arg="x"): ...  # error: [invalid-argument-type]

# Old generic syntax
T = TypeVar("T")

class Base(Generic[T]):
    def __init_subclass__(cls, arg: T) -> None: ...

class Valid(Base[int], arg=1): ...
class InvalidType(Base[int], arg="x"): ...  # error: [invalid-argument-type]

Generic subclasses

[environment]
python-version = "3.13"
Type parameter defaults

When checking cls for an inherited __init_subclass__ hook, the generic subclass retains its type parameters rather than replacing them with their defaults. Child[T] therefore satisfies the receiver bound Base[T].

class Base[T]:
    def __init_subclass__(cls, *, flag: bool = False) -> None: ...

class NoDefault[T](Base[T]): ...
class Child[T = int](Base[T]): ...
class PartialDefault[U, T = int](Base[T]): ...

Class keyword arguments are still checked against the hook's signature.

class WithKeyword[T = int](Base[T], flag=True): ...

# error: [invalid-argument-type] "Expected `bool`, found"
class InvalidKeyword[T = int](Base[T], flag="bad"): ...
Explicit receiver annotations

The implicit call also accepts an explicit cls: type[Base[T]] annotation.

class Base[T]:
    def __init_subclass__(cls: type["Base[T]"]) -> None: ...

class Child[T = int](Base[T]): ...

A hook restricted to RestrictedBase[int] rejects a subclass that remains generic, even when int is its default.

class RestrictedBase[T]:
    def __init_subclass__(cls: type["RestrictedBase[int]"]) -> None: ...

class Concrete(RestrictedBase[int]): ...

# error: [invalid-argument-type] "Expected `type[RestrictedBase[int]]`"
class Invalid[T = int](RestrictedBase[T]): ...
Legacy type parameter defaults

The same receiver relationship holds for subclasses using legacy type variables with defaults.

from typing import Generic, TypeVar

T = TypeVar("T")
U = TypeVar("U", default=int)

class Base(Generic[T]):
    def __init_subclass__(cls) -> None: ...

class Child(Base[U]): ...
Keyword arguments using subclass type parameters

Keyword arguments can refer to the subclass's type parameters. The argument must be compatible with that type parameter, not just its default: T can be specialized to a type other than int.

from typing import cast

class Base[T]:
    def __init_subclass__(cls, *, value: T) -> None: ...

class Valid[T = int](Base[T], value=cast(T, 1)): ...

# error: [invalid-argument-type] "Expected `T@Invalid`, found `Literal[1]`"
class Invalid[T = int](Base[T], value=1): ...

An explicitly specialized base accepts the concrete argument.

class AlsoValid(Base[int], value=1): ...

@staticmethod

Basic

When a @staticmethod attribute is accessed, it returns the underlying function object. This is true whether it's accessed on the class or on an instance of the class.

from __future__ import annotations

class C:
    @staticmethod
    def f(x: int) -> str:
        return "a"

reveal_type(C.f)  # revealed: def f(x: int) -> str
reveal_type(C().f)  # revealed: def f(x: int) -> str

The method can then be called like a regular function from either the class or an instance, with no implicit first argument passed.

reveal_type(C.f(1))  # revealed: str
reveal_type(C().f(1))  # revealed: str

When the static method is called incorrectly, we detect it:

C.f("incorrect")  # error: [invalid-argument-type]
C.f()  # error: [missing-argument]
C.f(1, 2)  # error: [too-many-positional-arguments]

When a static method is accessed on a derived class, it behaves identically:

class Derived(C):
    pass

reveal_type(Derived.f)  # revealed: def f(x: int) -> str
reveal_type(Derived().f)  # revealed: def f(x: int) -> str

reveal_type(Derived.f(1))  # revealed: str
reveal_type(Derived().f(1))  # revealed: str

Staticmethod assigned in class body

Assigning a staticmethod(...) object directly in the class body should preserve the callable behavior of the wrapped function when accessed on both classes and instances.

def foo(*args, **kwargs) -> None:
    print("foo", args, kwargs)

class A:
    __call__ = staticmethod(foo)
    bar = staticmethod(foo)

a = A()
a()
a.bar()
a(5)
a.bar(5)
a(x=10)
a.bar(x=10)

A.bar()
A.bar(5)
A.bar(x=10)

Staticmethods wrapping lambdas

A staticmethod can wrap a lambda. Access through a class or instance returns the lambda, including its function attributes, without binding an instance to its first parameter.

wrapper = staticmethod(lambda x: str(x))

class C:
    f = wrapper

reveal_type(C.f(1))  # revealed: str
reveal_type(C().f(1))  # revealed: str
reveal_type(C.f.__code__)  # revealed: CodeType

The staticmethod object exposes the lambda through __func__ and __wrapped__. Its __get__ method can also be called explicitly.

reveal_type(wrapper.__func__(1))  # revealed: str
reveal_type(wrapper.__wrapped__(1))  # revealed: str
wrapper.__get__(None, object)(1)

Accessing the staticmethod as a static member

from inspect import getattr_static

class C:
    @staticmethod
    def f(): ...

getattr_static bypasses descriptor binding and returns the staticmethod descriptor. Ordinary attribute access (C.f or C().f) instead returns the underlying function. We model the descriptor explicitly, but display it using the wrapped function's name and signature:

reveal_type(getattr_static(C, "f"))  # revealed: def f() -> Unknown

The __get__ of a staticmethod object simply returns the underlying function. It ignores both the instance and owner arguments.

reveal_type(getattr_static(C, "f").__get__(None, C))  # revealed: def f() -> Unknown
reveal_type(getattr_static(C, "f").__get__(C(), C))  # revealed: def f() -> Unknown
reveal_type(getattr_static(C, "f").__get__(C()))  # revealed: def f() -> Unknown
reveal_type(getattr_static(C, "f").__get__("dummy", C))  # revealed: def f() -> Unknown

Staticmethods mixed with other decorators

[environment]
python-version = "3.12"

When a @staticmethod is additionally decorated with another decorator, it is still treated as a static method:

from __future__ import annotations

def does_nothing[T](f: T) -> T:
    return f

class C:
    @staticmethod
    @does_nothing
    def f1(x: int) -> str:
        return "a"

    @does_nothing
    @staticmethod
    def f2(x: int) -> str:
        return "a"

reveal_type(C.f1(1))  # revealed: str
reveal_type(C().f1(1))  # revealed: str
reveal_type(C.f2(1))  # revealed: str
reveal_type(C().f2(1))  # revealed: str

When a @staticmethod is decorated with @contextmanager, accessing it from an instance should not bind self:

from contextlib import contextmanager
from collections.abc import Generator

class D:
    @staticmethod
    @contextmanager
    def ctx(num: int) -> Generator[int, None, None]:
        yield num

    def use_ctx(self) -> None:
        # Accessing via self should not bind self
        with self.ctx(10) as x:
            reveal_type(x)  # revealed: int

# Accessing via class works
reveal_type(D.ctx(5))  # revealed: _GeneratorContextManager[int, None, None]

# Accessing via instance should also work (no self-binding)
reveal_type(D().ctx(5))  # revealed: _GeneratorContextManager[int, None, None]

__new__

__new__ is an implicit @staticmethod; accessing it on an instance does not bind the cls argument:

from typing_extensions import Self

reveal_type(object.__new__)  # revealed: def __new__[Self](cls) -> Self
reveal_type(object().__new__)  # revealed: def __new__[Self](cls) -> Self
# revealed: Overload[[Self](cls, x: str | Buffer | SupportsInt | SupportsIndex | SupportsTrunc = 0, /) -> Self, [Self](cls, x: str | bytes | bytearray, /, base: SupportsIndex) -> Self]
reveal_type(int.__new__)
# revealed: Overload[[Self](cls, x: str | Buffer | SupportsInt | SupportsIndex | SupportsTrunc = 0, /) -> Self, [Self](cls, x: str | bytes | bytearray, /, base: SupportsIndex) -> Self]
reveal_type((42).__new__)

class X:
    def __init__(self, val: int): ...
    def make_another(self) -> Self:
        reveal_type(self.__new__)  # revealed: def __new__[Self](cls) -> Self
        return self.__new__(type(self))

Calling object.__new__ from an overriding __new__ method preserves Self, so an invalid attribute access on the result is reported:

class Item:
    def __new__(cls) -> Self:
        result = object.__new__(cls)
        reveal_type(result)  # revealed: Self@__new__
        # error: [missing-attribute]
        result.nonexistent()
        return result

Explicitly marking __new__ as a static method does not change the inferred result:

class StaticItem:
    @staticmethod
    def __new__(cls) -> Self:
        result = object.__new__(cls)
        reveal_type(result)  # revealed: Self@__new__
        return result

Self is also preserved through a chain of inherited __new__ calls:

class Foo: ...

class Bar(Foo):
    def __new__(cls) -> Self:
        return Foo.__new__(cls)

class Baz(Bar):
    def __new__(cls) -> Self:
        result = Bar.__new__(cls)
        reveal_type(result)  # revealed: Self@__new__
        # error: [missing-attribute]
        result.nonexistent()
        return result

Bound-method attribute fallback

Bound-method attributes are resolved first on types.MethodType, then, if absent, on the underlying function object. A protocol refinement of the bound method must not be used as the receiver for that underlying-function fallback:

from typing import Protocol, runtime_checkable

class C:
    def f(self, x: int) -> str:
        return "a"

@runtime_checkable
class ReturnsStr(Protocol):
    def __call__(self, x: str) -> str: ...

def narrowed_bound_method_attribute():
    method = C().f
    if isinstance(method, ReturnsStr):
        reveal_type(method)  # revealed: (bound method C.f(x: int) -> str) & ReturnsStr
        reveal_type(method.__globals__)  # revealed: dict[str, Any]

Decorated functions and bound methods

[environment]
python-version = "3.12"

We treat the result of a callable-returning decorator as a function descriptor. This means that C().decorated_method is also a BoundMethod, and that we can access its __self__ and __func__ attributes.

from typing import Callable

def identity[**P, R](function: Callable[P, R]) -> Callable[P, R]:
    return function

class C:
    def plain_method(self, value: int) -> str:
        return str(value)

    @identity
    def decorated_method(self, value: int) -> str:
        return str(value)

reveal_type(type(C().plain_method))  # revealed: <class 'MethodType'>
reveal_type(type(C().decorated_method))  # revealed: <class 'MethodType'>

decorated = C().decorated_method

reveal_type(decorated.__self__)  # revealed: C
reveal_type(decorated.__func__)  # revealed: (self, value: int) -> str
reveal_type(decorated(1))  # revealed: str
reveal_type(decorated.__call__(1))  # revealed: str
decorated("wrong")  # error: [invalid-argument-type]
callback: Callable[[int], str] = decorated

Receiver rebinding does not shadow methods

Assigning to self does not assign to its method attributes. An empty loop targeting self therefore leaves method calls bound, both before the loop and outside the method containing it.

This guards against a regression in implicit attribute type inference: synthetic loop-header definitions for attribute places such as self.method are not attribute assignments and must not be considered when inferring instance attribute types.

class C:
    def method(self) -> None:
        pass

    def rebind(self) -> None:
        self.method()
        for self in []:
            pass

C().method()

Builtin functions and methods

Some builtin functions and methods are heavily special-cased by ty. This mdtest checks that various properties are understood correctly for these functions and methods.

import types
from typing import Any, Callable
from ty_extensions import static_assert
from ty_extensions._internal import RegularCallableTypeOf, TypeOf, is_assignable_to

def f(obj: type) -> None: ...

class MyClass:
    @property
    def my_property(self) -> int:
        return 42

    @my_property.setter
    def my_property(self, value: int | str) -> None: ...

static_assert(is_assignable_to(types.FunctionType, Callable[..., Any]))

# revealed: <wrapper-descriptor '__get__' of 'function' objects>
reveal_type(types.FunctionType.__get__)
static_assert(is_assignable_to(TypeOf[types.FunctionType.__get__], Callable[..., Any]))

# revealed: def f(obj: type) -> None
reveal_type(f)
static_assert(is_assignable_to(TypeOf[f], Callable[..., Any]))

# revealed: <method-wrapper '__get__' of function 'f'>
reveal_type(f.__get__)
static_assert(is_assignable_to(TypeOf[f.__get__], Callable[..., Any]))

# revealed: def __call__(self, *args: Any, **kwargs: Any) -> Any
reveal_type(types.FunctionType.__call__)
static_assert(is_assignable_to(TypeOf[types.FunctionType.__call__], Callable[..., Any]))

# revealed: <method-wrapper '__call__' of function 'f'>
reveal_type(f.__call__)
static_assert(is_assignable_to(TypeOf[f.__call__], Callable[..., Any]))

# revealed: <wrapper-descriptor '__get__' of 'property' objects>
reveal_type(property.__get__)
static_assert(is_assignable_to(TypeOf[property.__get__], Callable[..., Any]))

# revealed: property
reveal_type(MyClass.my_property)
static_assert(is_assignable_to(TypeOf[property], Callable[..., Any]))
static_assert(not is_assignable_to(TypeOf[MyClass.my_property], Callable[..., Any]))

# revealed: <method-wrapper '__get__' of property 'my_property'>
reveal_type(MyClass.my_property.__get__)
static_assert(is_assignable_to(TypeOf[MyClass.my_property.__get__], Callable[..., Any]))

# revealed: <wrapper-descriptor '__set__' of 'property' objects>
reveal_type(property.__set__)
static_assert(is_assignable_to(TypeOf[property.__set__], Callable[..., Any]))

# revealed: <method-wrapper '__set__' of property 'my_property'>
reveal_type(MyClass.my_property.__set__)
static_assert(is_assignable_to(TypeOf[MyClass.my_property.__set__], Callable[..., Any]))

# revealed: def startswith(self, prefix: str | tuple[str, ...], start: SupportsIndex | None = None, end: SupportsIndex | None = None, /) -> bool
reveal_type(str.startswith)
static_assert(is_assignable_to(TypeOf[str.startswith], Callable[..., Any]))

# revealed: <method-wrapper 'startswith' of string 'foo'>
reveal_type("foo".startswith)
static_assert(is_assignable_to(TypeOf["foo".startswith], Callable[..., Any]))

def _(
    a: RegularCallableTypeOf[types.FunctionType.__get__],
    b: RegularCallableTypeOf[f],
    c: RegularCallableTypeOf[f.__get__],
    d: RegularCallableTypeOf[types.FunctionType.__call__],
    e: RegularCallableTypeOf[f.__call__],
    f: RegularCallableTypeOf[property],
    g: RegularCallableTypeOf[property.__get__],
    h: RegularCallableTypeOf[MyClass.my_property.__get__],
    i: RegularCallableTypeOf[property.__set__],
    j: RegularCallableTypeOf[MyClass.my_property.__set__],
    k: RegularCallableTypeOf[str.startswith],
    l: RegularCallableTypeOf["foo".startswith],
):
    # revealed: Overload[(self: FunctionType, instance: None, owner: type, /) -> Unknown, (self: FunctionType, instance: object, owner: type | None = None, /) -> Unknown]
    reveal_type(a)

    # revealed: (obj: type) -> None
    reveal_type(b)

    # TODO: ideally this would have precise return types rather than `Unknown`
    # revealed: Overload[(instance: None, owner: type, /) -> Unknown, (instance: object, owner: type | None = None, /) -> Unknown]
    reveal_type(c)

    # revealed: (self, *args: Any, **kwargs: Any) -> Any
    reveal_type(d)

    # revealed: (obj: type) -> None
    reveal_type(e)

    # revealed: (fget: ((Any, /) -> Any) | None = None, fset: ((Any, Any, /) -> None) | None = None, fdel: ((Any, /) -> None) | None = None, doc: str | None = None) -> property
    reveal_type(f)

    # revealed: Overload[(self: property, instance: None, owner: type, /) -> Unknown, (self: property, instance: object, owner: type | None = None, /) -> Unknown]
    reveal_type(g)

    # TODO: ideally this would have precise return types rather than `Unknown`
    # revealed: Overload[(instance: None, owner: type, /) -> Unknown, (instance: object, owner: type | None = None, /) -> Unknown]
    reveal_type(h)

    # TODO: ideally this would have `-> None` rather than `-> Unknown`
    # revealed: (self: property, instance: object, value: object, /) -> Unknown
    reveal_type(i)

    # TODO: ideally this would have a more precise input type and `-> None` rather than `-> Unknown`
    # revealed: (instance: object, value: object, /) -> Unknown
    reveal_type(j)

    # revealed: (self, prefix: str | tuple[str, ...], start: SupportsIndex | None = None, end: SupportsIndex | None = None, /) -> bool
    reveal_type(k)

    # revealed: (prefix: str | tuple[str, ...], start: SupportsIndex | None = None, end: SupportsIndex | None = None, /) -> bool
    reveal_type(l)