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。

pip install tradecal

市场与事实源

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

import tradecal as cal

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

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

通用交易日接口

所有日历提供：

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

严格覆盖边界

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

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

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

schedule

A 股、港股

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

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 身份。

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 源码；源码仓库不公开。