Python 3.11中带前向引用与None的函数返回值类型提示问题求助

这个问题我之前也碰到过，核心原因是你把字符串和None直接用|操作符组合了——Python 3.11的联合类型|只支持类型对象之间的运算，字符串不是类型，所以才会抛出TypeError: unsupported operand type(s) for |: 'str' and 'NoneType'。下面给你几个可行的解决方案，按推荐程度排序：

方案1：使用__future__ annotations（推荐） #

这是最简洁的方式，Python 3.7+支持这个导入，它会让所有类型提示保留为字符串形式，延迟到运行时或类型检查器（如mypy、pyright）解析时才处理，完美解决前向引用问题。

只需在文件顶部导入，然后直接写正常的联合类型标注即可：

from __future__ import annotations

class MyClass:
    def some_function(self, param1, param2) -> None | UnknownKlass:
        # 函数实现逻辑
        if param1 > param2:
            return None
        return UnknownKlass()

# 后续定义前向引用的类
class UnknownKlass:
    pass

方案2：将整个联合类型标注用引号包裹 #

如果不想使用__future__导入，可以把整个返回类型标注作为字符串，这样Python在定义函数时不会尝试解析|操作，避免报错：

class MyClass:
    def some_function(self, param1, param2) -> "None | UnknownKlass":
        # 函数实现逻辑
        pass

class UnknownKlass:
    pass

类型检查器依然能正确识别这个字符串形式的联合类型。

方案3：使用Optional（兼容旧写法） #

如果你习惯使用typing模块的工具，可以用Optional来替代Union[X, None]，同时把前向引用的类名用引号包裹：

from typing import Optional

class MyClass:
    def some_function(self, param1, param2) -> Optional["UnknownKlass"]:
        # 函数实现逻辑
        pass

class UnknownKlass:
    pass

Optional["UnknownKlass"]等价于Union["UnknownKlass", None]，同样能绕过定义时的类型解析错误。

为什么原来的写法会报错？ #

你之前尝试的None | "UnknownKlass"，是把None（一个NoneType的实例）和字符串"UnknownKlass"做|运算——Python的|操作符在类型提示中的联合类型用法，仅支持实际的类型对象（比如int、自定义类）之间的组合，字符串不是类型对象，所以触发了类型错误。

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