如何为返回自身（self）的类方法添加类型提示？

针对你遇到的这个问题，核心是要区分「返回任意类实例」和「返回调用方法的自身实例」两种语义，下面分情况给你讲清楚正确的实现方式：

推荐方案：使用Self类型 #

Self类型就是专门用来标注返回自身实例的场景，它能精确表达「返回调用该方法的那个实例」的语义，不同Python版本的使用方式略有不同：

1. Python 3.11+（优先推荐） #

从Python 3.11开始，Self已经被纳入标准库的typing模块，直接导入使用即可：

from typing import Self

class A:
    def foo(self) -> Self:
        # 执行你的操作
        return self

这种写法语义最精确，类型检查器（比如mypy、Pyright）能完美识别，甚至在子类继承时会自动适配类型——比如子类B(A)调用B().foo()，结果会被正确推断为B类型，而非父类A。

2. Python 3.8~3.10 #

对于这些版本，需要从typing_extensions库导入Self：

from typing_extensions import Self

class A:
    def foo(self) -> Self:
        # 执行你的操作
        return self

解决你遇到的mypy报错问题

你提到用typing_extensions.Self时mypy报错Variable "typing_extensions.Self" is not valid as a type，大概率是两个原因：

• 未安装typing_extensions：执行pip install typing-extensions安装即可
• mypy版本过低：需要升级到0.910及以上版本，执行pip install --upgrade mypy就能解决

兼容旧版本的折中方案：字符串标注A #

如果不想依赖typing_extensions，可以结合from __future__ import annotations用字符串标注类名：

from __future__ import annotations

class A:
    def foo(self) -> A:
        # 执行你的操作
        return self

虽然标注的是A，但类型检查器（比如VSCode默认的Pyright）会理解这里返回的是self——也就是你看到的悬停提示Self@A，它表示「当前类A的自身实例」，和返回任意A实例的语义有明确区分。不过这种写法在子类继承时，类型推断的精确性不如Self。

分析你试过的方案 #

• 方案1：标注为A（加from __future__ import annotations）：写法本身合法，但语义没有Self精确——不过实际类型检查时，大部分工具会对return self做特殊处理，也能正常工作，只是Self更贴合需求。
• 方案2：标注为Type[A]：完全不符合需求，Type[A]表示返回类本身（未实例化的对象），而非类的实例。

关于VSCode的Self@A提示 #

这个提示是Pyright给出的精确语义说明，它明确表示该方法返回的是调用它的那个具体实例，而非任意A实例。当你用Self类型标注时，提示会和标注完全对应；用A标注时，Pyright也会识别到实际返回的是自身，所以显示这个更精确的提示。

内容的提问来源于stack exchange，提问作者Kanishk