如何为Polars的日期参数正确添加类型注解？

场景复现 #

创建日期数据：

import polars as pl

df = pl.DataFrame(
    [
        pl.Series("start", ["2023-01-01"], dtype=pl.Date).str.to_date(),
        pl.Series("end", ["2024-01-01"], dtype=pl.Date).str.to_date(),
    ]
)

基于数据生成日期范围的代码可正常运行：

dates = pl.date_range(df[0, "start"], df[0, "end"], "1mo", eager=True)

但封装成自定义函数后无法通过pyright/Pylance类型检查：

def my_date_range(start: pl.Date, end: pl.Date) -> pl.Series:
    return pl.date_range(start, end, "1mo", eager=True)

报错信息：

Argument of type "Date" cannot be assigned to parameter "start" of type "IntoExprColumn | date | datetime" in function "date_range"
  Type "Date" is incompatible with type "IntoExprColumn | date | datetime"
    "Date" is incompatible with "date"
    "Date" is incompatible with "datetime"
    "Date" is incompatible with "Expr"
    "Date" is incompatible with "Series"
    "Date" is incompatible with "str"PylancereportArgumentType

经检查：

• type(df[0, "start"]) 返回 datetime.date
• isinstance(df[0, "start"], pl.Date) 返回 False
• 尝试导入polars.datetime失败

需解决：如何正确为my_date_range的日期参数添加类型注解？

1. 基础方案：使用Python标准库类型 #

从DataFrame中取出的单个日期值本质是Python原生的datetime.date对象，pl.Date只是Polars用于标记列数据类型的标识，并非单个元素的类型。直接用标准库类型注解即可通过检查：

from datetime import date
import polars as pl

def my_date_range(start: date, end: date) -> pl.Series:
    return pl.date_range(start, end, "1mo", eager=True)

2. 进阶方案：兼容多种输入类型 #

如果需要让函数同时支持原生date/datetime、Polars表达式/Series等多种输入，可以复用Polars内置的类型别名：

from datetime import date, datetime
from polars import Series
from polars.type_aliases import IntoExprColumn

def my_date_range(start: IntoExprColumn | date | datetime, end: IntoExprColumn | date | datetime) -> Series:
    return pl.date_range(start, end, "1mo", eager=True)

IntoExprColumn是Polars定义的类型别名，涵盖了所有可转换为表达式列的类型（包括Expr、Series、标量等），能大幅提升函数灵活性，同时通过类型检查。

补充说明 #

• Polars中的pl.Date是列级数据类型标记，不是单个元素的类型。当你从DataFrame中提取单个元素时，Polars会自动将其转换为Python标准库的datetime.date对象。
• 无需导入polars.datetime，Polars的日期时间操作直接通过pl模块调用即可，单个元素的类型对应标准库的date/datetime。

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