我的个人技术笔记

9.7 日期偏移

5 min read

说明

日期偏移（DateOffset）是 pandas 中实现日历频率的机制，遵循月份长度、周末、节假日等日历规则，与固定时长的 Timedelta 不同。 所有偏移类均位于 pandas.tseries.offsets，并可通过 freq 字符串别名使用。

import pandas as pd
from pandas.tseries.offsets import (
    DateOffset, BDay, BMonthEnd, BMonthBegin, MonthEnd, MonthBegin,
    QuarterEnd, QuarterBegin, YearEnd, YearBegin, Week, WeekOfMonth,
    BusinessHour, CustomBusinessDay,
)

DateOffset

说明

通用日期偏移基类，支持任意时间单位的组合。

ts = pd.Timestamp('2026-08-19 13:05:00')
 
# 组合偏移
print(ts + DateOffset(years=1, months=2, days=3, hours=4))
# 2027-10-22 17:05:00
 
# 月份加减自动处理月末
print(pd.Timestamp('2026-01-31') + DateOffset(months=1))
# 2026-02-28 00:00:00
 
# 频率字符串对应
print(ts + pd.offsets.DateOffset(weeks=2))

BDay

说明

工作日偏移（Business Day），默认跳过周六、周日。频率字符串别名：'B'。

ts = pd.Timestamp('2026-08-21')   # 周五
print(ts + BDay(1))               # 2026-08-24（周一）
print(ts + BDay(2))               # 2026-08-25（周二）
print(pd.date_range('2026-08-03', periods=3, freq='B'))

BMonthEnd / BMonthBegin

说明

工作月月末 / 工作月月初偏移，自动跳过周末。频率字符串别名：'BM' / 'BMS'。

print(pd.Timestamp('2026-01-15') + BMonthEnd())    # 2026-01-30（1 月最后一个工作日）
print(pd.Timestamp('2026-01-15') + BMonthBegin())  # 2026-02-02（2 月第一个工作日）
 
# 带 n 的偏移
print(pd.Timestamp('2026-01-31') + BMonthEnd(2))   # 2026-03-31

MonthEnd / MonthBegin

说明

日历月月末 / 月初偏移，不跳过周末。频率字符串别名：'ME'（新）/ 'M'（旧）、'MS'。

print(pd.Timestamp('2026-08-19') + MonthEnd())     # 2026-08-31
print(pd.Timestamp('2026-08-19') + MonthBegin())   # 2026-09-01
 
# 月末滚动
print(pd.Timestamp('2026-01-31') + MonthEnd(1))    # 2026-02-28
print(pd.Series(pd.date_range('2026-01-01', periods=3, freq='ME')))

QuarterEnd / QuarterBegin

说明

季度末 / 季度初偏移，可指定锚定月份。频率字符串别名：'QE'（新）/ 'Q'（旧）、'QS'。

print(pd.Timestamp('2026-08-19') + QuarterEnd())     # 2026-09-30（默认 12 月锚定）
print(pd.Timestamp('2026-08-19') + QuarterBegin())   # 2026-10-01
 
# 指定锚定月份（如 2 月锚定）
print(pd.Timestamp('2026-08-19') + QuarterEnd(month=2))
# 2026-11-30

YearEnd / YearBegin

说明

年末 / 年初偏移，可指定锚定月份。频率字符串别名：'YE'（新）/ 'Y' 或 'A'（旧）、'YS' 或 'AS'。

print(pd.Timestamp('2026-08-19') + YearEnd())       # 2026-12-31
print(pd.Timestamp('2026-08-19') + YearBegin())     # 2027-01-01
 
# 指定财务年结月（如 6 月）
print(pd.Timestamp('2026-08-19') + YearEnd(month=6))
# 2027-06-30

Week

说明

周偏移，默认按周日锚定，可指定 weekday。频率字符串别名：'W'、'W-MON' 等。

print(pd.Timestamp('2026-08-19') + Week())            # 2026-08-23（周日）
print(pd.Timestamp('2026-08-19') + Week(weekday=0))   # 2026-08-24（周一）
print(pd.date_range('2026-01-01', periods=3, freq='W-MON'))

WeekOfMonth

说明

每月第几周的星期几偏移（如「每月第 2 个周五」）。

# week=0 表示第一个，weekday=4 表示周五
wom = WeekOfMonth(week=1, weekday=4)
print(pd.Timestamp('2026-08-19') + wom)
# 2026-09-11（9 月第二个周五）
 
print(pd.date_range('2026-01-01', periods=3, freq='WOM-2FRI'))

BusinessHour

说明

工作小时偏移，默认 09:00-17:00，周一至周五。频率字符串别名：'BH'。

ts = pd.Timestamp('2026-08-19 15:00')   # 周三下午 3 点
print(ts + BusinessHour())              # 2026-08-19 16:00
print(ts + BusinessHour(3))             # 2026-08-20 10:00（跨天）
 
# 自定义工作时间
bh = BusinessHour(start='09:00', end='12:00')
print(ts + bh)

CustomBusinessDay

说明

自定义工作日偏移，支持节假日日历与自定义星期工作日。频率字符串别名：'C'。

from pandas.tseries.holiday import USFederalHolidayCalendar
 
cal = USFederalHolidayCalendar()
 
cbd = CustomBusinessDay(calendar=cal)
print(pd.Timestamp('2026-07-03') + cbd)   # 2026-07-06（跳过 7/4 独立日周末）
 
# 自定义工作日（如仅周三）
wed_only = CustomBusinessDay(weekmask='Wed')
print(pd.date_range('2026-08-01', periods=3, freq=wed_only))

自定义偏移

说明

可通过继承 DateOffset 或组合现有偏移构建自定义频率。

from pandas.tseries.offsets import DateOffset
 
# 组合偏移（每 2 周 + 1 天）
custom = DateOffset(weeks=2, days=1)
print(pd.Timestamp('2026-08-19') + custom)
 
# 使用 apply / rollforward / rollback 精确控制
class QuarterEndFriday(MonthEnd):
    """月末向前调整到周五"""
    def __init__(self):
        super().__init__()
 
# 更常用：通过 calendar 与 offsets 组合实现业务频率

节假日日历 pandas.tseries.holiday

说明

pandas.tseries.holiday 模块提供节假日日历定义，可与 CustomBusinessDay 等偏移配合生成业务频率。

from pandas.tseries.holiday import (
    USFederalHolidayCalendar,
    AbstractHolidayCalendar,
    Holiday, nearest_workday,  # 或具体规则函数
)
from pandas.tseries.offsets import CustomBusinessDay
 
# 使用内置美国联邦节假日
cal = USFederalHolidayCalendar()
print(cal.holidays('2026-01-01', '2026-12-31'))
# DatetimeIndex(['2026-01-01', '2026-01-19', '2026-02-16', ...])
 
# 自定义节假日日历
class ChinaHolidayCalendar(AbstractHolidayCalendar):
    rules = [
        Holiday('New Year', month=1, day=1),
        Holiday('National Day', month=10, day=1),
    ]
 
cn_cal = ChinaHolidayCalendar()
cbd_cn = CustomBusinessDay(calendar=cn_cal)
print(pd.bdate_range('2026-09-28', periods=5, freq=cbd_cn))
 
# 获取节假日日期
print(cn_cal.holidays('2026-01-01', '2026-12-31'))

常用内置日历

日历类说明
USFederalHolidayCalendar美国联邦节假日
USColumbusDay / USThanksgivingDay 等美国单个节日规则
AbstractHolidayCalendar自定义日历基类
Holiday定义单个节假日规则（支持 month、day、offset、observance）

🔗 相关链接

Graph View

Backlinks