Pandas date_range不符合预期：为何未生成2023年起始时间？

问题复现 #

执行代码：

pd.date_range('2022-01-01 15:00', '2023-02-02 00:00', freq='YS')

实际返回结果：

DatetimeIndex(['2022-01-01 15:00:00'], dtype='datetime64[ns]', freq='AS-JAN')

但预期应包含2023-01-01 15:00:00，即：

DatetimeIndex(['2022-01-01 15:00:00', '2023-01-01 15:00:00'], dtype='datetime64[ns]', freq='AS-JAN')

该行为确实反直觉，属于设计上的不合理之处。

原因分析 #

Pandas在处理YS（年度起始）这类年度级频率时，内部逻辑会以年份边界作为判断依据，而非严格比较生成的时间点与结束时间的大小。即使2023-01-01 15:00:00早于给定的结束时间2023-02-02 00:00:00，也会因为该时间点属于2023年度，而原结束时间的年度范围被判定为不包含完整的2023年度周期，从而被排除在外。

实现预期效果的方法 #

方法1：指定生成周期数 #

直接通过periods参数指定要生成的年度起始点数量，避免依赖结束时间的判断逻辑：

pd.date_range('2022-01-01 15:00', periods=2, freq='YS')

此方法会直接生成2022和2023年1月1日15:00的时间点，完全符合预期。

方法2：基于周期范围转换 #

先生成年度周期，再转换为带指定时分秒的时间戳：

# 生成2022到2023年的年度周期
periods = pd.period_range('2022', '2023', freq='Y')
# 转换为年度起始时间，并加上15小时的偏移
dt_index = periods.to_timestamp(how='start') + pd.Timedelta(hours=15)

方法3：手动补充目标时间点 #

如果需要保留原结束时间的过滤逻辑，可以先生成初始结果，再手动添加符合条件的时间点：

base_index = pd.date_range('2022-01-01 15:00', '2023-02-02 00:00', freq='YS')
# 检查目标时间点是否在结束时间之前，若符合则添加
target_time = pd.Timestamp('2023-01-01 15:00')
if target_time <= pd.Timestamp('2023-02-02 00:00'):
    base_index = base_index.append(pd.DatetimeIndex([target_time]))

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