如何为带类型函数的可选日期参数设置符合mypy规则的默认值？

先看原始函数：

from datetime import date

def my_func(start_date: date) -> None:
    print(start_date)

我们需要为start_date设置默认值，同时满足三个要求：

• 符合mypy类型检查规则
• 不在函数签名中执行函数调用（避免解析时提前执行初始化逻辑）

错误写法分析 #

1. 直接用字符串作为默认值

def my_func(start_date: date = "2020-12-31") -> None:
    print(start_date)

mypy会抛出类型不兼容错误：

Incompatible default for argument "start_date" (default has type "str", argument has type "date")

2. 在签名中直接调用date()构造函数

def my_func(start_date: date = date(2020, 12, 31)) -> None:
    print(start_date)

这种写法的问题是，date(2020,12,31)会在函数被Python解析时就执行，而非函数实际调用时。如果默认值依赖动态数据（比如当前日期），或者构造逻辑有副作用，会导致不符合预期的结果。

可行解决方案 #

方案一：用None作为默认值，函数内部初始化

这是最常用且符合Python惯用写法的方案：

from datetime import date
from typing import Optional

def my_func(start_date: Optional[date] = None) -> None:
    if start_date is None:
        start_date = date(2020, 12, 31)
    print(start_date)

• 通过Optional[date]告诉mypy参数可以是date类型或None，符合类型规则
• 初始化逻辑仅在函数实际被调用时执行，避免提前执行的问题
• 可读性高，调用者也能清晰理解参数可省略

方案二：使用自定义哨兵值

如果不想让参数接受None（比如避免调用者传入None导致逻辑错误），可以定义一个唯一的哨兵对象：

from datetime import date
from typing import Union

# 创建一个唯一的哨兵对象，外部无法复制
_SENTINEL = object()

def my_func(start_date: Union[date, object] = _SENTINEL) -> None:
    if start_date is _SENTINEL:
        start_date = date(2020, 12, 31)
    print(start_date)

• 哨兵对象是全局唯一的，确保只有未传参时才会触发默认值逻辑
• Union[date, object]让mypy可以正确识别参数类型
• 缺点是类型注解稍显复杂，可读性略低于方案一

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