Metadata-Version: 2.4
Name: tradecal
Version: 2026.10.0
Summary: Trading calendars with MIC identifiers and strict coverage boundaries
Author-email: SeedData <2236158935@qq.com>
License-Expression: LicenseRef-Proprietary
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pandas<3.0,>=2.2.0
Requires-Dist: pandas_market_calendars<6.0,>=5.4.0
Requires-Dist: pyarrow>=23.0.0

# tradecal 交易日历

`tradecal` 是纯客户端交易日历。日常查询不访问 Gateway、QuestDB、collect 端或在线数据源：

- A 股、港股和美股运行时使用 `pandas_market_calendars`（PMC）。
- 国内期货读取 tradecal 包内 parquet。

Python 要求 `>=3.10`；依赖 `pandas>=2.2,<3`、`pandas_market_calendars>=5.4,<6` 和 `pyarrow>=23`。

```bash
pip install tradecal
```

## 市场与事实源

对外只接受 ISO 10383 MIC；`CN_FUTURES` 是国内六家期货交易所的交易日并集。

| 市场 | 名称 | 运行时事实源 |
| --- | --- | --- |
| 上海股票 | `XSHG` | PMC `XSHG` |
| 深圳股票 | `XSHE` | PMC `XSHG` 交易日规则 |
| 香港股票 | `XHKG` | PMC `XHKG` |
| NYSE / Nasdaq 普通股票 | `XNYS` / `XNAS` | PMC `NYSE` / `NASDAQ` |
| 国内期货 | `CCFX` `XDCE` `XZCE` `XSGE` `XINE` `GFEX` | 包内 parquet |
| 国内期货并集 | `CN_FUTURES` | 包内六所交易日并集 |

```python
import tradecal as cal

calendar = cal.get_calendar("XNYS")
cal.get_calendar_names()
```

名称大小写不敏感并容忍首尾空格；`NYSE`、`NASDAQ`、`SHFE` 等非 MIC 名称会抛出
`ValueError`。

## 通用交易日接口

所有日历提供：

| 方法 | 语义 |
| --- | --- |
| `valid_days(start_date, end_date=None, tz=None)` | 区间内交易日；省略 `end_date` 时只查询单日 |
| `is_valid_day(date)` | 是否交易日 |
| `date_to_valid_day(date, direction)` | 映射到前一个或后一个交易日 |
| `valid_days_window(valid_day, count)` | 含锚点的前向或后向交易日窗口 |

交易日返回市场本地时区的午夜：美股为 `America/New_York`，A 股和国内期货为
`Asia/Shanghai`，港股为 `Asia/Hong_Kong`。`valid_days(..., tz=...)` 可覆盖输出时区。

### 严格覆盖边界

国内期货对象公开 `first_valid_day` 和 `last_valid_day`。当前包内覆盖为：

| 日历 | `first_valid_day` | `last_valid_day` |
| --- | --- | --- |
| `CCFX` | 2015-01-05 | 2026-12-31 |
| `XDCE` | 1993-03-01 | 2026-12-31 |
| `XZCE` | 1990-10-12 | 2026-12-31 |
| `XSGE` | 1991-05-28 | 2026-12-31 |
| `XINE` | 2017-05-23 | 2026-12-31 |
| `GFEX` | 2022-12-22 | 2026-12-31 |
| `CN_FUTURES` | 1990-10-12 | 2026-12-31 |

`XSHG` 和 `XSHE` 的 PMC 规则当前可靠上限为 2026-12-31，对象公开
`last_valid_day`。PMC 在官方下一年度休市安排发布前无法可靠推导中国调休和长假，因此不能把普通
工作日外推当作未来交易日。`XHKG`、`XNYS` 和 `XNAS` 采用 PMC 自身规则，不额外声明 tradecal
覆盖属性。

严格日历的所有交易日方法都遵守边界：请求日期、区间任一端或窗口结果越界时抛出
`ValueError`，不裁剪结果，也不把越界日期当作普通工作日或简单返回 `False`。

## schedule

### A 股、港股

`XSHG`、`XSHE`、`XHKG` 只支持 `session="regular"`，默认返回市场本地时区，列为：

```text
market_open, break_start, break_end, market_close
```

`break_start` 和 `break_end` 是午休边界；半日市使用 PMC 的特殊时间。A 股 schedule 同样受
2026-12-31 可靠上限约束。

### 美股

`XNYS` 和 `XNAS` 表示主要上市市场，使用统一的美国普通股票交易日和通用交易时段；不模拟每个
撮合 venue 的订单接收、竞价或券商规则。PMC 5.4 中 `NASDAQ` 与 `NYSE` 使用同一日历规则，
tradecal 仍保留各自 MIC 身份。

```python
us = cal.get_calendar("XNYS")

regular = us.schedule("2026-11-27", session="regular")
extended = us.schedule("2026-11-27", session="extended")
beijing = us.schedule("2026-06-01", session="extended", tz="Asia/Shanghai")
```

- `regular` 返回 `market_open`、`market_close`，通常为 `09:30–16:00 ET`。
- `extended` 返回 `pre`、`market_open`、`market_close`、`post`，通常为 `04:00–20:00 ET`。
- 节假日不返回行；2026-11-27 为 `09:30–13:00 ET`，PMC 5.4 的盘后结束时间为
  `17:00 ET`。
- DataFrame 索引始终是美国交易日标签；列转换成北京时间后可能落到次日。

美股还提供 `early_closes()`、`late_opens()` 和 `is_open_at()`。`is_open_at()` 要求带时区
时间戳，按左闭右开判断；`session="extended"` 表示从盘前开始到盘后结束的完整窗口。

美股能力不包含隔夜 / `24/5`、券商特定时段、个股临时停牌、实时熔断、期权、债券或期货。

### 国内期货

国内期货没有可靠的品种级交易时段事实源，`schedule()` 明确抛出 `NotImplementedError`。

## 数据与版本

国内期货数据来自各交易所交易日历，经 Tushare `fut_trade_cal` 采集后随包分发。
日常调用完全离线；包内数据不会自动刷新，覆盖不足时必须更新发行版本。

版本格式为 `YYYY.MM.PATCH`：YYYY 是 A 股和国内期货的覆盖年，MM 固定为该覆盖年
首次发布时的月份，PATCH 是该覆盖年后续发布的递增序号，不随自然月或自然年重置。
例如 `2027.11.0` 在 2026 年 11 月发布，2027 年 1 月修复使用 `2027.11.1`。
各市场精确覆盖日期以本页边界表及日历属性为准，港美股规则不由版本首段声明覆盖。

## License

本包采用专有许可 `LicenseRef-Proprietary`，安装与使用需获得 SeedData 授权。
wheel 公开分发并包含 Python 源码；源码仓库不公开。
