kepler.pulse 0.2.1

Trade day handling utilities for A-share market

kepler-pulse

交易日历工具库，支持多套日历实例、多种频率周期。

安装

pip install kepler-pulse

快速开始

from kepler.pulse import Calendar

# 创建日历实例（需自行注入交易日数据）
cal = Calendar()

# 注入交易日数据（支持 list/tuple/pd.Series）
cal.inject(trade_dates)

# 或者创建时直接传入
cal = Calendar(trade_dates)

基础操作

获取日期范围

cal.range('20240101', '20240131')
# → pd.Series: ['20240102', '20240103', ..., '20240131']

调整到最近交易日

# 向前找（默认）
cal.adjust('20240101', 'prev')
# → '20231229'（上一个交易日）

# 向后找
cal.adjust('20240101', 'next')
# → '20240102'（下一个交易日）

按步长跳转

# 正数向前
cal.step('20240102', 3)
# → '20240105'（后第3个交易日）

# 负数向后
cal.step('20240105', -2)
# → '20240103'（前第2个交易日）

计算交易日数量

cal.delta('20240101', '20240131')
# → 22（两个日期间的交易日数量）

频率操作

支持的频率类型：

• daily — 日频
• weekly — 周频
• biweekly — 双周频
• monthly — 月频
• quarterly — 季频
• halfyearly — 半年频
• yearly — 年频
• reportly — 财报频

获取周期边界日期

# 获取每月第一个交易日
cal.monthly.first('20240101', '20241231')
# → pd.Series: ['20240102', '20240201', '20240301', ...]

# 获取每月最后一个交易日
cal.monthly.last('20240101', '20241231')
# → pd.Series: ['20240131', '20240229', '20240329', ...]

# 获取月初+月末（去重排序）
cal.monthly.both('20240101', '20240331')
# → pd.Series: ['20240102', '20240131', '20240201', '20240229', ...]

获取下一个/上一个边界日期

# 下一个月初
cal.monthly.first.next('20240115')
# → '20240201'

# 下一个月末
cal.monthly.last.next('20240115')
# → '20240131'

# 上一个月初
cal.monthly.first.prev('20240115')
# → '20240102'

# 上一个月末
cal.monthly.last.prev('20240115')
# → '20231229'

# 支持步长
cal.monthly.first.next('20240115', step=2)
# → '20240301'（下下个月初）

其他频率示例

# 周频
cal.weekly.first('20240101', '20240131')
cal.weekly.last.next('20240115')

# 季频
cal.quarterly.first('20240101', '20241231')
cal.quarterly.last.prev('20240615')

# 年频
cal.yearly.first('20200101', '20241231')
cal.yearly.last.next('20240601')

期货操作

股指期货交割日

# 获取指定日期之前的交割日
cal.futures.stock('20240115')
# → pd.Series: ['20231117', '20231215', '20240119', ...]

# 获取所有交割日
cal.futures.stock(all=True)
# → list: ['20231117', '20231215', '20240119', ...]

国债期货交割日

cal.futures.treasury()
# → list: ['20231215', '20240315', ...]

主力合约

cal.futures.contracts('20240115')
# → pd.Series: ['2401', '2402']（当月+次月合约）

# 非换合约期
cal.futures.contracts('20240102')
# → pd.Series: ['2401']（仅当月合约）

多日历支持

# A股日历
cal_a = Calendar(a_share_dates)

# 港股日历
cal_hk = Calendar(hk_share_dates)

# 美股日历
cal_us = Calendar(us_share_dates)

# 独立使用
cal_a.monthly.first('20240101', '20241231')
cal_hk.monthly.first('20240101', '20241231')

API 对照表

基础操作

旧 API	新 API
get_trade_dts(begin, end)	cal.range(begin, end)
adjust_trade_dt(date, 'last')	cal.adjust(date, 'prev')
adjust_trade_dt(date, 'next')	cal.adjust(date, 'next')
step_trade_dt(date, n)	cal.step(date, n)
delta_trade_dt(begin, end)	cal.delta(begin, end)

频率操作

旧 API	新 API
Monthly(1).get(begin, end)	cal.monthly.first(begin, end)
Monthly(-1).get(begin, end)	cal.monthly.last(begin, end)
Monthly(1, -1).get(begin, end)	cal.monthly.both(begin, end)
Monthly(1).next(date)	cal.monthly.first.next(date)
Monthly(-1).next(date)	cal.monthly.last.next(date)
Monthly(1).prev(date)	cal.monthly.first.prev(date)
Monthly(-1).prev(date)	cal.monthly.last.prev(date)

期货操作

旧 API	新 API
get_delistdate(date)	cal.futures.stock(date)
get_delistdate_all()	cal.futures.stock(all=True)
get_delistdate_tf_all()	cal.futures.treasury()
get_contract(date)	cal.futures.contracts(date)

注意事项

1. 日期格式：仅支持 YYYYMMDD 格式的字符串或整数
2. 日历实例化：不再使用全局单例，需自行创建 Calendar 实例并注入交易日数据
3. 缓存机制：每个 Calendar 实例内部有缓存，相同参数不会重复计算