当函数需区分“参数未传入”与“参数显式传入 None”时，传统 x: int | None = None 无法满足需求；本文介绍一种安全、简洁且类型友好的方案：使用不可实例化（或禁止继承）的私有标记类配合 Type[Marker] 注解。
当函数需区分“参数未传入”与“参数显式传入 none”时，传统 `x: int | none = none` 无法满足需求；本文介绍一种安全、简洁且类型友好的方案：使用不可实例化（或禁止继承）的私有标记类配合 `type[marker]` 注解。
在 Python 类型系统中，None 常被用作可选参数的默认值，但一旦 None 本身是合法业务值（例如表示“空字符串”、“未设置的配置项”等），我们就失去了判断“用户是否传参”的能力。此时，需要一个运行时唯一、不可伪造、类型可精确描述的哨兵值（sentinel）。
最常用且推荐的做法是定义一个私有空类作为标记：
class _undef:
pass
T_undef = type[_undef] # Python 3.12+ 推荐写法；3.9–3.11 请用 typing.Type[_undef]
然后在函数签名中将其纳入联合类型：
def process_value(x: int | None | T_undef = _undef) -> None:
if x is _undef:
print("No value was provided (not even None).")
elif x is None:
print("Explicitly received None.")
else:
print(f"Received integer: {x}")
✅ 该方案优势显著：
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 类型安全：mypy 能正确推断 _undef 是唯一可能匹配 T_undef 的值，拒绝任何其他对象（包括 None 或自定义对象）赋值给形参 x；
- 运行时可靠：is 判断零开销、绝对唯一；
- 简洁无依赖：无需引入 enum、Literal 或复杂元类（除非有强约束需求）；
- 符合惯例：下划线前缀表明 _undef 是模块内部实现细节，不应被外部使用或继承。
⚠️ 注意事项：
- 不要使用 Literal[_undef]：object() 实例不可哈希，不能用于 Literal；
- 避免直接写 x: int | None | type[_undef] = _undef：虽能通过类型检查，但 type[_undef] 表示“_undef 类本身”，而非其实例，语义错误；
- 若需彻底防止子类化（如高安全性场景），可添加 Final 元类（见下文），但对大多数应用属过度设计。
? 进阶：防子类化的最终方案（可选）
若严格要求 _undef 绝对不可被继承（例如避免恶意代码绕过 is 检查），可借助自定义 Final 元类：
from typing import Type
class Final(type):
def __new__(cls, name, bases, namespace):
for base in bases:
if isinstance(base, Final):
raise TypeError(f"{base.__name__} is final and cannot be subclassed")
return super().__new__(cls, name, bases, namespace)
class _undef(metaclass=Final):
pass
T_undef = Type[_undef]
此时 class Bad(_undef): ... 将在导入时立即报 TypeError，从源头杜绝误用。
总结：对于需区分“未传参”与“传了 None”的场景，定义私有空类 + Type[Class] 注解是最平衡、最 Pythonic、最受类型检查器支持的解决方案。它兼顾表达力、性能、可维护性与工程严谨性，应作为此类问题的首选实践。
