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.fis equivalent togetattr_static(C, "f").__get__(None, C)C().fis equivalent togetattr_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)