使用哨兵值作为函数默认参数时，如何正确添加类型提示以消除mypy类型不兼容报错

你碰到的这个场景太常见了——当None已经被赋予特定业务含义时，用object()做哨兵值会让mypy因为类型不匹配抛出错误。下面我给你两种思路的解决方案：要么修正类型提示让mypy认哨兵值，要么换更优雅的哨兵值策略。

一、修正类型提示，让mypy兼容哨兵值 #

你可以通过自定义类型或者Union组合类型，让参数的类型范围包含哨兵值的类型，这里有两种靠谱的写法：

方法1：用TypeVar定义专属哨兵类型 #

这种方式能明确区分哨兵值和正常参数的类型，类型提示更严谨：

from typing import Optional, Union, TypeVar

# 定义一个只用来标记哨兵值的专属类型
DefaultType = TypeVar('DefaultType', bound=object)
# 初始化哨兵值并标注其类型
DEFAULT: DefaultType = object()

def spam(ham: Union[Optional[list[str]], DefaultType] = DEFAULT):
    if ham is DEFAULT:
        ham = ['prosciutto', 'jamon']
    if ham is None:
        print('Eggs?')
    else:
        print(f"{len(ham)} ham(s).")

方法2：用枚举(Enum)作为哨兵值 #

枚举是mypy天然友好的单例实现，既能完美承担哨兵的功能，又不会有类型不匹配的问题：

from typing import Optional, List, Union
from enum import Enum

class Sentinel(Enum):
    DEFAULT = object()

def spam(ham: Union[Optional[List[str]], Sentinel] = Sentinel.DEFAULT):
    if ham is Sentinel.DEFAULT:
        ham = ['prosciutto', 'jamon']
    if ham is None:
        print('Eggs?')
    else:
        print(f"{len(ham)} ham(s).")

二、替代object()的哨兵值方案 #

如果你不想用object()，还有两种更贴合Python类型系统的替代策略：

方案1：使用函数重载(overload) #

通过对外暴露清晰的函数签名，把内部的哨兵值实现完全隐藏起来，用户调用体验更直观，同时mypy完全不会报错：

from typing import Optional, overload, List

# 对外暴露两个明确的签名：无参数 或 传入Optional[List[str]]
@overload
def spam() -> None: ...

@overload
def spam(ham: Optional[List[str]]) -> None: ...

# 内部用哨兵值处理默认逻辑，外部用户看不到这个默认值
_DEFAULT = object()
def spam(ham: Optional[List[str]] = _DEFAULT):
    if ham is _DEFAULT:
        ham = ['prosciutto', 'jamon']
    if ham is None:
        print('Eggs?')
    else:
        print(f"{len(ham)} ham(s).")

这样用户调用时，要么不传参数（匹配第一个重载），要么传None或列表（匹配第二个重载），mypy会严格检查传入的类型，而内部的哨兵逻辑完全不影响外部的类型提示。

方案2：用typing.cast快速绕过检查（不推荐） #

如果你只是想快速解决报错，不想改太多代码，可以用cast把哨兵值强制转换成参数类型，但这相当于“蒙混”mypy，虽然能过检查，但会降低类型提示的严谨性，只适合临时应急：

from typing import Optional, cast

DEFAULT = object()

def spam(ham: Optional[list[str]] = cast(Optional[list[str]], DEFAULT)):
    if ham is DEFAULT:
        ham = ['prosciutto', 'jamon']
    if ham is None:
        print('Eggs?')
    else:
        print(f"{len(ham)} ham(s).")

最后推荐优先选枚举哨兵或者函数重载的方案，它们更符合Python的类型规范，代码可读性和可维护性也更高。

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