Python 3.15 sentinel 类型的默认值设计

Python 3.15 增加了内置的 sentinel 类型，用来表示一个和业务值分离的唯一缺省标记。它特别适合函数参数：当 None 本身也是合法输入时，不能再用 None 同时代表“调用者没有传值”。

官方地址：https://docs.python.org/3.15/library/functions.html#sentinel

把“未提供”单独建模成模块级 sentinel，用 is 做身份判断；把 None 留给调用者明确传入的空值。Python 3.15 还允许这个 sentinel 直接出现在类型表达式中。

为什么 None 和 object() 不够理想

假设一个查询函数允许调用者明确传入 None，但省略参数时要读取配置文件中的默认值。此时下面两种状态必须分开：

• 没有传 timeout：函数自行计算默认超时。
• 传入 timeout=None：调用者明确要求“不设置超时”。

旧代码常用 None 或模块级 object() 解决问题。前者会和合法输入撞值，后者虽然能做身份比较，但 repr 往往是难读的对象地址，类型签名也很难表达。PEP 661 将这个需求收敛成了一个可读的标准类型。

用 sentinel() 建立清晰的默认值边界

把 sentinel 放在模块级，并让变量名与 sentinel 名称保持一致，是最容易理解和最方便序列化的写法。repr 默认就是名称，因此函数签名和日志不会出现对象地址。

from __future__ import annotations

from builtins import sentinel

# 模块级常量代表“调用者没有提供 timeout”，不要让它和 None 混用。
TIMEOUT_MISSING = sentinel("TIMEOUT_MISSING")


def connect(timeout: float | None | TIMEOUT_MISSING = TIMEOUT_MISSING) -> str:
    # 身份判断只识别这个模块创建的缺省标记，避免把普通值误判为缺省。
    if timeout is TIMEOUT_MISSING:
        timeout = load_default_timeout()
    # None 仍然是一个有意义的显式输入，这里不把它改写成默认值。
    return open_connection(timeout)


def load_default_timeout() -> float:
    # 示例只表达默认值来源，真实项目可替换为配置中心或环境变量读取。
    return 3.0


def open_connection(timeout: float | None) -> str:
    # 这里用字符串表示连接结果，便于聚焦参数边界而不是网络细节。
    return f"timeout={timeout!r}"


print(connect())
print(connect(None))

示例的关键不是把 sentinel 传给业务实现，而是在边界处尽早把它转换成真正的业务值。判断使用 is，不要依赖 ==：sentinel 是唯一对象，身份语义比相等语义更直接。

把 sentinel 写进类型表达式

Python 3.15 的官方文档给出了 int | MISSING 这类写法。前提是 sentinel 通常赋给同名变量，类型检查器才能把它当作一个可识别的类型表达式组成部分。它表达的是“整数值或这个特定的缺省标记”，而不是任意对象。

from builtins import sentinel

# 名称相同，既能让 repr 可读，也能让类型表达式指向明确的 sentinel。
MISSING = sentinel("MISSING")


def parse_limit(limit: int | MISSING = MISSING) -> int:
    # 省略参数时使用配置；显式传入整数时直接采用调用者的值。
    if limit is MISSING:
        return read_limit_from_config()
    return limit


def read_limit_from_config() -> int:
    # 示例返回固定值，实际项目应在这里处理配置不存在或格式错误。
    return 100


print(parse_limit())
print(parse_limit(20))

运行时不会替你执行静态类型检查，注解主要服务于类型检查器、IDE 和代码阅读者。若团队的检查器版本还不认识 Python 3.15 的新规则，先升级检查器，或者在兼容分支暂时保留旧式注解。

复制、pickle 和类作用域的边界

标准 sentinel 的一个实用特性是浅复制和深复制仍返回原对象，因此身份检查不会因为复制而失效。可导入模块中的命名 sentinel 还可以参与 pickle；要让反序列化找回同一个对象，名称、模块和可导入路径必须保持稳定。

旧版本兼容怎么安排

sentinel 是 Python 3.15 的新内置能力，不能把同一段代码直接假定为 3.14 及更早版本都能运行。若项目需要跨版本支持，可以把兼容实现集中在一个小模块里：新版本调用内置 sentinel，旧版本使用稳定的自定义类或模块级 object()，业务代码只依赖这个模块导出的标记。

import sys

if sys.version_info >= (3, 15):
    from builtins import sentinel

    # 新版本使用标准实现，获得可读 repr 和类型表达式能力。
    MISSING = sentinel("MISSING")
else:
    class _Missing:
        # 固定 repr，避免日志出现不稳定的对象地址。
        def __repr__(self) -> str:
            return "MISSING"

    # 旧版本只创建一次，所有模块都从这里导入同一个对象。
    MISSING = _Missing()


def value_or_default(value=MISSING):
    # 跨版本代码统一使用身份判断，调用方无需知道实现细节。
    if value is MISSING:
        return "default"
    return value

兼容层的重点是保持身份和导入路径稳定，而不是模拟 3.15 的全部类型系统能力。等项目最低 Python 版本提升到 3.15 后，再删除旧分支，并把 sentinel 纳入公开 API 的文档。

一张速查表

最后记住三个动作：先确认“未提供”是否和合法业务值不同；不同就定义一个模块级 sentinel；在边界处用 is 转换，并把类型表达式、导入路径和最低 Python 版本一起写进项目约定。

相关问题

• sentinel 可以用 == 判断吗？不建议。它的语义是唯一身份，使用 is 更能避免自定义相等规则带来的误判。
• 能否把多个状态都塞进一个 sentinel？不能。每次调用 sentinel() 都会创建不同对象；多个有序状态更适合使用枚举。
• 为什么不总用 None？当 None 是业务上的有效输入时，None 就无法同时承担“参数未提供”的标记职责。
• sentinel 能继承吗？不能。Python 3.15 的 sentinel 类型不支持子类化。