如何为函数参数start_date添加覆盖特殊取值的类型提示？

原函数代码 #

from datetime import date

def days_between(start_date: date, end_date: date) -> int:
    if start_date == "initial":
        start_date = date(2023, 9, 1)
    delta = end_date - start_date
    return delta.days 

问题说明 #

当前函数的start_date参数类型提示标注为date，但实际支持传入唯一字符串值"initial"，类型提示未覆盖该合法输入，现针对三种优化方案逐一分析：

方案1：start_date: date | str #

这种写法能通过静态类型检查，但范围过宽——它允许传入任意字符串，而实际上只有"initial"是合法值，会误导使用者认为可以传其他字符串，反而增加误用概率。

方案2：使用字面量类型限定 #

直接写date | "initial"在语法上合法，但属于相对小众的写法，部分使用者可能不理解。更规范的做法是借助typing.Literal精确限定合法的字符串值：

from datetime import date
from typing import Literal

def days_between(start_date: date | Literal["initial"], end_date: date) -> int:
    if start_date == "initial":
        start_date = date(2023, 9, 1)
    delta = end_date - start_date
    return delta.days 

这种写法兼顾静态检查严谨性和参数范围的精确性，但需要使用者熟悉Literal类型的用法，否则可能造成困惑。

方案3：保留原类型提示，补充docstring说明 #

由于你更看重向用户清晰传达用法而非静态类型检查的形式正确性，这个方案最务实。通过docstring明确告知参数的合法输入范围，既能让类型检查器正常工作，又能清晰指导使用者：

from datetime import date

def days_between(start_date: date, end_date: date) -> int:
    """计算两个日期之间的天数差。
    
    参数:
        start_date: 起始日期，支持两种输入：
            - date类型对象
            - 字符串"initial"，将自动映射为2023年9月1日
        end_date: 结束日期，必须为date类型对象
    
    返回:
        两个日期之间的天数差（整数）
    """
    if isinstance(start_date, str) and start_date == "initial":
        start_date = date(2023, 9, 1)
    delta = end_date - start_date
    return delta.days 

同时建议加上isinstance判断，避免非预期的字符串传入导致后续报错。

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