python 类型检查器不支持直接用运行时实例（如字符串或对象）作为类型注解，但可通过 `literal[enummember]` 实现等效效果：将单例封装为枚举成员，再用 `literal` 注解，使类型检查器能正确识别并支持 `is` 运算符驱动的类型窄化。
在 Python 类型系统中，函数返回类型注解必须是类型表达式（如 int、str、Literal["x"]），而不能是运行时值（如变量 my_marker）。因此，像 -> int | my_marker 或 -> int | Literal[my_marker]（其中 my_marker 是变量）这类写法在语法或语义上均不合法——Literal 要求其参数是编译期可确定的字面量（literal），而非动态绑定的变量名。
✅ 正确且实用的解决方案是：将单例值定义为 Enum 成员，并使用 Literal[MyEnum.MEMBER] 进行类型注解。这既满足类型系统的静态要求，又保留了运行时单例语义，并能被主流类型检查器（如 mypy、Pyright）正确处理 is 判断后的类型窄化。
以下是推荐实现：
from typing import Literal, Union
from enum import Enum
from random import random
class MyMarker(Enum):
# 使用有意义的成员名，值即为你的单例对象
SINGLETON = "This is very singletony, I promise!"
def get_object_or_a_singleton_marker() -> Union[int, Literal[MyMarker.SINGLETON]]:
if random() < 0.5:
return 42
else:
return MyMarker.SINGLETON
# 类型检查器能识别该调用返回 Union[int, Literal[MyMarker.SINGLETON]]
a_var = get_object_or_a_singleton_marker()
if a_var is not MyMarker.SINGLETON:
# ✅ 此分支中，a_var 的类型被精准窄化为 `int`
reveal_type(a_var) # mypy 输出: note: Revealed type is "builtins.int"
print(a_var + 10) # 类型安全：允许 int 运算⚠️ 注意事项：
- Enum 成员必须使用 Literal[MyEnum.MEMBER]（而非 MyEnum 或 type[MyEnum.MEMBER]），否则无法触发基于 is 的窄化；
- 若单例是自定义类实例（如 class Sentinel: pass; SENTINEL = Sentinel()），仍应将其封装进 Enum（SentinelEnum.VALUE = SENTINEL），因为 Literal 不支持任意对象（仅支持 str/int/bool/None 及其组合）；
- Enum 方案天然具备唯一性、不可变性和可读性，比全局常量字符串更健壮，也便于 IDE 补全和文档生成；
- 避免使用 TypeGuard 或 cast 等绕过型方案——它们破坏类型安全性或增加冗余代码，违背“保持 is 语法简洁”的原始需求。
总结：虽然 Python 类型系统不支持直接标注实例，但通过 Enum + Literal[EnumMember] 的组合，你既能获得精确的静态类型推导，又能维持自然、直观的运行时逻辑（if x is not SENTINEL:），是兼顾类型安全与开发体验的最佳实践。
