NaT与timedelta、relativedelta相加行为差异问题咨询

核心结论 #

这个差异不是由relativedelta的“相对”计算特性直接导致，本质是pandas对两类时间差对象的空值适配逻辑不一致，加上relativedelta自身没有做缺失值兼容处理。

问题复现 #

复现代码及报错信息如下：

from datetime import timedelta
from dateutil.relativedelta import relativedelta
import numpy as np
import pandas as pd

# 正常返回NaT
pd.to_datetime(np.nan) + timedelta(days=1)
# 输出: NaT

# 触发报错
pd.to_datetime(np.nan) + relativedelta(days=1)

报错栈核心信息：

Traceback (most recent call last):
  ...
  File "C:\...\Python39\lib\calendar.py", line 124, in monthrange
    raise IllegalMonthError(month)
calendar.IllegalMonthError: bad month number nan; must be 1-12

具体原因拆解 #

• timedelta是Python标准库原生时间差类型，pandas对其做了完整的适配：只要运算一侧是NaT（pandas的缺失时间标识），会直接触发空值短路逻辑，不执行实际时间计算，直接返回NaT，因此不会报错。
• relativedelta是python-dateutil库独立实现的偏移类型，pandas没有为它和NaT的运算做专门的空值短路处理。执行NaT + relativedelta(...)时，会优先调用relativedelta的反向加法方法，把NaT当作普通时间对象传入自身的计算逻辑。
• relativedelta的内部计算逻辑存在前置日历校验：哪怕你只传入days=1这类固定天级偏移参数，它也会先读取传入时间的年、月属性，调用calendar.monthrange获取当月最大天数，避免日期偏移后出现越界问题。而NaT的年、月属性返回值是np.nan，传入月份校验逻辑时自然触发非法月份报错，和是否使用“相对年月偏移”没有直接关系——就算不传入months/years参数，只传天/小时级偏移，一样会触发这个错误。

解决建议 #

• 优先使用pandas原生的偏移类型（比如pd.offsets.Day(1)、pd.offsets.DateOffset(months=1)）和pandas时间对象做运算，这类类型原生支持NaT空值短路，不会触发报错。
• 如果必须使用relativedelta，可以先对时间序列做非空掩码，仅对非空的时间值应用relativedelta偏移，计算完成后再把原空值位置填回NaT即可。

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