Python typing.Self 怎样标注链式调用的返回类型

如果一个方法返回的就是当前对象，链式调用的返回标注通常应写成 Self，而不是写死成当前基类名称。这样，类型检查器才能在子类上继续保留子类类型；运行时对象本身不会因为加了标注而改变。

本文只讨论 typing.Self 与 fluent API、继承返回类型之间的关系。官方参考地址：https://docs.python.org/3/library/typing.html#typing.Self

先分清：方法返回的是谁

设计链式 API 时，先看方法的真实契约，而不是先挑一个看起来顺眼的类型名。若方法修改当前实例后返回 self，调用者需要继续看到实际子类；若方法无论由哪个子类调用都新建一个固定的基类对象，返回类型就应该写基类。

用 Self 保留链式调用的子类类型

下面的查询对象把过滤条件写入当前实例，然后返回自己。Self 表达的是“当前包围类对应的实例类型”，不是一个需要手动绑定的普通字符串。

from typing import Self, reveal_type


class Query:
    def __init__(self) -> None:
        # 当前对象保存链式调用逐步累积的条件。
        self.filters: list[tuple[str, str]] = []

    def where(self, field: str, value: str) -> Self:
        # 修改当前实例并返回 self，调用方可以继续链式调用。
        self.filters.append((field, value))
        return self


class UserQuery(Query):
    def only_active(self) -> Self:
        # 子类方法复用基类链式方法，仍然返回当前子类实例。
        return self.where("status", "active")


query = UserQuery().where("role", "admin").only_active()
reveal_type(query)  # 静态检查器应推断为 UserQuery

这里的关键不是链式语法本身，而是 where 返回了原来的 self。因此从 UserQuery 开始调用时，where 的结果仍然可以继续使用 only_active。如果把返回值写成 Query，类型检查器往往只能看到基类接口，子类方法就会在链条中丢失。

把 Self 放在确实随调用类变化的接口上

除了实例方法，官方文档还列出两个常见边界：返回 cls 实例的替代构造器，以及返回当前对象的 __enter__。它们都要求实现结果与调用类或当前实例保持一致。

from typing import Self


class Report:
    @classmethod
    def empty(cls) -> Self:
        # 通过 cls 创建调用者要求的具体类型，而不是写死 Report。
        return cls()

    def __enter__(self) -> Self:
        # 上下文管理器返回当前对象，退出时再由调用方结束资源管理。
        return self

    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
        # 该示例没有需要释放的资源，保留空的退出契约。
        return None


class CsvReport(Report):
    pass


report = CsvReport.empty()
reveal_type(report)  # 静态检查器应推断为 CsvReport

对于 classmethod，Self 的前提是实现确实使用 cls 创建同类对象。对于上下文管理器，前提是 __enter__ 返回的确实是当前实例。它们不是“看到继承就统一改成 Self”，而是根据接口契约选择。

固定返回基类时不要误用 Self

如果实现无论从哪个子类调用，都固定返回 Report()，那它并不保证返回子类实例。此时写 Self 会向调用方承诺一个无法兑现的类型，反而让静态检查结果失真。

from typing import Self


class Report:
    @classmethod
    def template(cls) -> "Report":
        # 这里明确固定创建 Report，不能承诺返回 CsvReport 等子类。
        return Report()


class CsvReport(Report):
    pass


template = CsvReport.template()
# template 的契约是 Report，而不是 CsvReport。

判断方法很简单：沿着所有正常返回路径追踪对象来源。如果返回的是 self，或由 cls 创建并保持动态类型，才适合 Self；如果返回固定类、工厂结果或另一种独立对象，就写真实的返回类型。

版本兼容与速查

typing.Self 从 Python 3.11 开始提供。需要兼容更早版本时，可以把导入改为 typing_extensions，并保持同样的标注语义：

try:
    from typing import Self
except ImportError:
    # 旧版本通过 typing_extensions 提供 Self 的兼容实现。
    from typing_extensions import Self

• 返回当前实例：优先使用 Self。
• 子类仍应获得自身类型：不要把链式方法写死成基类名。
• 固定返回基类：写基类名，不要用 Self 伪装成动态返回。
• 标注只服务静态类型工具：Python 运行时不会自动执行类型检查。

相关问题

Self 会改变 Python 的运行时行为吗？

不会。它主要提供给类型检查器、IDE 和代码审查使用，方法实际返回什么仍由函数体决定。

链式方法返回 None 还能用 Self 吗？

不能。只有返回当前实例或与当前调用类型保持一致的对象时，Self 才准确；返回 None 应标注为 None。