Metadata-Version: 2.4
Name: kepler.pulse
Version: 0.2.2
Summary: Trade day handling utilities for A-share market
Author-email: liubola <lby3523@gmail.com>
Maintainer-email: liubola <lby3523@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/liubola/kepler-pulse
Project-URL: Repository, https://github.com/liubola/kepler-pulse
Project-URL: Bug Reports, https://github.com/liubola/kepler-pulse/issues
Keywords: trading,calendar,financial,stock-market,china,a-share,trade-dates
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

# kepler-pulse

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

## 安装

```bash
pip install kepler-pulse
```

## 快速开始

```python
from kepler.pulse import Calendar

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

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

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

## 基础操作

### 获取日期范围

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

### 调整到最近交易日

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

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

### 按步长跳转

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

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

### 计算交易日数量

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

## 频率操作

支持的频率类型：
- `daily` — 日频
- `weekly` — 周频
- `biweekly` — 双周频
- `monthly` — 月频
- `quarterly` — 季频
- `halfyearly` — 半年频
- `yearly` — 年频
- `reportly` — 财报频

### 获取周期边界日期

```python
# 获取每月第一个交易日
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', ...]
```

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

```python
# 下一个月初
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'（下下个月初）
```

### 其他频率示例

```python
# 周频
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')
```

## 期货操作

### 股指期货交割日

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

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

### 国债期货交割日

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

### 主力合约

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

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

## 多日历支持

```python
# 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` 实例内部有缓存，相同参数不会重复计算
