类型提示返回 self 的 class 方法的返回值？

Question

as the questions describes, I wanna type hint a self return, something like:

class A:
  def foo(self) -> [what goes here?]:
    # do something
    return self

Things I already tried:

1. annotating it as A ( adding from __future__ import annotations at the top ): this means the method returns an instantiated A() object, not necessarily self .
2. annotating it as Type[A] ( adding from typing import Type ): this means the method is returning is returning an un-instantiated A , which isnt remotely close to self .
3. annotating is as Self ( adding from typing_extensions import Self ): mypy gives an error: Variable "typing_extensions.Self" is not valid as a type [valid-type]mypy(error)

Things that might be of help : hovering over the method foo with no annotations of a return value, VScode hints shows - Self@A , i dont understand it but, this definitely differentiates between returning another instantiated class A() and returning self ... Thanks

Answer 1

I can't find any question that covers this closely, so will try to explain.

What does "same type" mean for type checking

Well, probably this is the long form of "you can't, and you shouldn't".

Type checking aims to confirm that all functions are called with proper argument types and return expected types. I suggest to read PEP483 first to understand concept of type better. Suppose you have the following:

s1 = ''.join(['a', 'b', 'c'])
s2 = ''.join(['a', 'b', 'c'])
assert s1 is not s2
assert s1 == s2

( join to avoid optimization, but it's another story). Are they the same object? No, is not clearly states this (they have different memory addresses). But will s2 be acceptable whenever you want s1 ? Definitely yes. You will not create a function that operates only on s1 and checks this fact with is , right?

Now what is the difference between self as reference to exact object and self as any A instance? When we talk about type checking, all A instances are completely equivalent and indistinguishable. They have the same set of methods and attributes (including types). We can ask: "which type errors can be introduced or removed, if we explicitly declare object to be self instance and not just self type?" I really cannot think of any. If you want this for semantics, use docstring - types should not be abused for everything. self object is absolutely the same as any other A() instance for type checker.

Simple solution: return class instance

Your first code sample is almost fine. Annotate return as A to tell that it returns instance of class A , it will work for final class:

class A:
    def foo(self) -> A:
        return self

However, this approach has a drawback (it is good explained in PEP673 about Self type):

class AChild(A):
    pass

# mypy
reveal_type(AChild().foo())  # N: revealed type is "__main__.A"

If you create new A in foo and return it, then this approach is perfect. If you return self - it is valid, but not precise. That's why we need Self type.

Self type is too modern

As of now, mypy does not support Self type described in PEP673 , so it fails with a cryptic message. However, your usage in 3rd example was perfectly valid and will work after implementation in type checkers (see 5-th code block in "Motivation" section of PEP).

Here's how you can use Self (assuming python=3.11 not to bother with typing_extensions and near future for mypy support):

from typing import Self

class A:
    def foo(self) -> Self:
        return self

class AChild(A):
    pass

# mypy
reveal_type(AChild().foo())  # N: revealed type is "__main__.AChild"
reveal_type(A().foo())  # N: revealed type is "__main__.A"

It is great, but does not work now. Note that other checkers (namely pyright and pyre ) have support for this.

Implementing Self type without using it

However, you can mimic Self accurately with a few lines of code (and python >= 3.7 , AFAIR).

from typing import TypeVar

_Self = TypeVar('_Self', bound='A')

class A:
    def foo(self: _Self) -> _Self:
        return self

class AChild(A):
    pass

# mypy
reveal_type(AChild().foo())  # N: revealed type is "__main__.AChild"
reveal_type(A().foo())  # N: revealed type is "__main__.A"

Now this works. All subclasses will return their class instance.