libfinance 0.0.6__tar.gz → 0.1.2__tar.gz

libfinance-0.1.2/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: libfinance
+Version: 0.1.2
+Summary: libfinance is a modern finance API
+Description-Content-Type: text/markdown
+Requires-Dist: lz4
+Requires-Dist: msgpack
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: pyarrow
+Requires-Dist: six
+Requires-Dist: python-dateutil
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/StateOfTheArt-quant/libfinance/main/docs/_shared/_static/img/libfinance_logo_dark.svg">
+  <img alt="libfinance" src="https://raw.githubusercontent.com/StateOfTheArt-quant/libfinance/main/docs/_shared/_static/img/libfinance_logo.svg" width="300">
+</picture>
+
+**面向量化研究与回测的 Python 金融数据接口 —— A 股与美股，同一套术语**
+
+[![PyPI](https://img.shields.io/pypi/v/libfinance?style=flat-square&logo=pypi&logoColor=white&label=PyPI)](https://pypi.org/project/libfinance/)
+[![docs zh-cn](https://img.shields.io/readthedocs/libfinance?style=flat-square&logo=readthedocs&logoColor=white&label=docs%20zh-cn)](https://libfinance.readthedocs.io/zh-cn/latest/)
+[![docs en](https://img.shields.io/readthedocs/libfinance-en?style=flat-square&logo=readthedocs&logoColor=white&label=docs%20en)](https://libfinance.readthedocs.io/en/latest/)
+
+[📘 中文文档](https://libfinance.readthedocs.io/zh-cn/latest/) ·
+[📗 English documentation](https://libfinance.readthedocs.io/en/latest/) ·
+[💻 示例代码](https://github.com/StateOfTheArt-quant/libfinance/tree/main/example) ·
+[🚀 快速开始](https://libfinance.readthedocs.io/zh-cn/latest/getting_started/quickstart.html) ·
+[🧭 概念设计](https://libfinance.readthedocs.io/zh-cn/latest/concepts/security_identifiers.html) ·
+[📑 API 参考](https://libfinance.readthedocs.io/zh-cn/latest/reference/contracts.html)
+
+</div>
+
+---
+
+`libfinance` 让 A 股与美股使用同一套术语：证券标识的写法相同，查询函数与参数名相同，返回的表结构也相同。两个市场的差别落在数据上，不落在调用方式上。
+
+覆盖行情、证券信息、交易日历、公司行动、财务数据及行业、指数与概念数据，并支持实时行情订阅。查询结果便于直接用于 pandas 分析。
+
+研究需要的不只是历史数字，还包括明确的证券身份、当时有效的信息，以及一致的价格口径。`libfinance` 把这三件事写进了数据设计：
+
+- **统一的证券标识符** —— 用 `<trading_code>.<namespace>` 表达证券，例如 `600000.XSHG`、`000001.XSHE`、`AAPL.US`，区分不同市场的同名代码；结合历史时点解析代码，减少更名与代码复用带来的歧义。
+- **point-in-time 机制 `as_of`** —— 按历史时点还原证券池，并选择当时已披露的财务版本，帮助避免未来信息和幸存者偏差。
+- **高质量的复权因子 `exfactor`** —— 结合公司行动处理价格可比性，提供不复权、前复权和后复权行情；通过 `get_ex_factor` 查看单次及累计因子，让价格变化有据可查。
+
+## 安装
+
+```bash
+pip install libfinance
+```
+
+从源码安装：
+
+```bash
+git clone https://github.com/StateOfTheArt-quant/libfinance.git
+cd libfinance/python
+pip install -e .
+```
+
+C++ 客户端（函数名、参数与 Python 版逐一相同，见 [cpp/README.md](cpp/README.md)）：
+
+```cpp
+#include <libfinance/libfinance.hpp>
+
+auto bars = libfinance::get_price({"000001.XSHE", "600000.XSHG"}, "2024-03-01", "2024-03-06");
+```
+
+## 快速开始
+
+按[安装与连接说明](https://libfinance.readthedocs.io/zh-cn/latest/getting_started/installation.html)配置服务后，即可查询：
+
+```python
+from libfinance import instruments, get_price, get_ex_factor
+
+# 查询历史时点对应的证券信息。
+print(instruments("600000.XSHG", as_of="2024-03-01"))
+
+# 显式选择不复权，查看历史原始行情。
+print(get_price(
+    ["000001.XSHE", "600000.XSHG"],
+    "2024-03-01", "2024-03-06", adjust_type="none",
+))
+
+# 查看公司行动对应的单次及累计复权因子。
+print(get_ex_factor("600000.XSHG", "2023-01-01", "2024-12-31"))
+```
+
+一分钟看懂这几行取到了什么，见[快速开始](https://libfinance.readthedocs.io/zh-cn/latest/getting_started/quickstart.html)。
+
+## A 股与美股共用一套术语
+
+统一体现在三个层面。
+
+| 层面 | 统一的内容 | 例 |
+| --- | --- | --- |
+| 证券标识 | 写法都是 `<trading_code>.<namespace>`；命名空间的粒度取决于该市场消除歧义所需的范围 | `600000.XSHG`、`AAPL.US` |
+| 函数与参数 | 两个市场调用同一组函数，参数名相同，`as_of` 与 `adjust_type` 的含义一致 | `get_price`、`instruments`、`get_dividends` |
+| 返回结构 | 列名与索引一致；某个市场不适用或未提供的字段取 `NaN`，不另设一张表 | 美股的 `turnover`、`limit_up`、`limit_down` |
+
+需要显式指定市场的，只有不涉及具体证券的查询：交易日历、全市场目录、数据覆盖范围。按证券查询时，命名空间已经给出了市场信息，列表里也可以混合两个市场的代码。
+
+```python
+from libfinance import instruments, get_trading_dates
+
+instruments(["000001.XSHE", "AAPL.US"])                      # 命名空间已给出市场
+get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体证券
+```
+
+统一的是术语和调用约定，数据本身的差异依然存在。下表的「市场」一列标出了每类数据实际覆盖的市场，逐个接口的情况见[查美股](https://libfinance.readthedocs.io/zh-cn/latest/howto/us_market.html)。
+
+## 数据覆盖
+
+| 数据 | 市场 | 主要函数 | 说明 |
+| --- | --- | --- | --- |
+| 交易日历 | CN · US | `get_trading_dates` | 交易日、区间取日、前后推 N 个交易日 |
+| 证券主数据 | CN · US | `all_instruments` | 代码、名称、类型、上市与退市日期 |
+| 日频行情 | CN · US | `get_price` | 开高低收、成交量额，可复权 |
+| 复权因子 | CN · US | `get_ex_factor` | 逐除权日的单次及累计因子 |
+| 股本结构 | CN | `get_shares` | 逐交易日的总股本与流通股本 |
+| 分红 / 拆股 / 配股 | CN · US | `get_dividends` | 除权事件，价格跳空的来源 |
+| 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
+| 财务报表（PIT） | CN | `get_pit_financials_ex` | 按季度取，带修订历史 |
+| 财务衍生指标 | CN、US | `get_financial_metrics` | 按交易日的财务衍生指标 |
+| 因子 | CN | `get_factor_exposure`、`list_factor_libraries`、`list_factors` | qlib、alpha158、Barra CNE5 风格 / 行业因子与描述符 |
+| 行业分类 | CN / US | `get_instrument_industry`、`get_industry_constituents`、`get_industry_weights` | 申万、GICS 等分类体系 |
+| 指数成分与权重 | CN | `get_index_weights` | 任意交易日的成分权重 |
+| 概念板块成分 | CN | `get_concept_weights` | THS 概念分类 |
+| 实时行情 | CN | `QuoteApi` | 订阅推送 |
+
+覆盖到哪一年、更新到哪一天，取决于你连的那个服务。**不要照抄文档里的日期**，用[数据新鲜度](https://libfinance.readthedocs.io/zh-cn/latest/data/freshness.html)里的两个函数自己查。
+
+## 概念设计
+
+| 主题 | 解决的问题 |
+| --- | --- |
+| [统一的证券标识符](https://libfinance.readthedocs.io/zh-cn/latest/concepts/security_identifiers.html) | 区分市场、证券身份及历史代码，准确关联不同数据 |
+| [point-in-time 机制 as_of](https://libfinance.readthedocs.io/zh-cn/latest/concepts/point_in_time.html) | 还原历史证券池与可见财报，避免未来信息和幸存者偏差 |
+| [高质量的复权因子 exfactor](https://libfinance.readthedocs.io/zh-cn/latest/concepts/exfactor.html) | 理解公司行动对价格的影响，以及三种价格口径的计算和用途 |
+
+## 文档与示例
+
+| | |
+| --- | --- |
+| [📘 中文文档](https://libfinance.readthedocs.io/zh-cn/latest/) | 概念设计、数据说明、操作指南与 API 参考 |
+| [📗 English documentation](https://libfinance.readthedocs.io/en/latest/) | The same documentation tree in English |
+| [💻 示例代码](https://github.com/StateOfTheArt-quant/libfinance/tree/main/example) | 按数据族排序的可运行示例（Python 与 C++ 一一对应），与 API 参考对照阅读 |
+| [🧩 操作指南](https://libfinance.readthedocs.io/zh-cn/latest/howto/index.html) | 取行情面板、PIT 回测、订阅实时行情等成套做法 |
+| [🩺 故障排查](https://libfinance.readthedocs.io/zh-cn/latest/howto/troubleshooting.html) | 按**症状**编排：看到什么现象，就从哪一行开始 |
+
+API 参考按合约信息和交易日历、行情信息、基本面信息、行业和概念信息、公司行动信息、实时行情分组，包含参数说明和带打印结果的场景示例。
+
+## 社区
+
+问题与需求请提 [Issue](https://github.com/StateOfTheArt-quant/libfinance/issues)。关注公众号获取更新：
+
+<div align="center">
+    <img alt="微信公众号二维码" src="https://raw.githubusercontent.com/StateOfTheArt-quant/libfinance/main/docs/_shared/_static/img/code.png" width="600" height="220">
+</div>
+
+## 仓库结构
+
+| 目录 | 内容 |
+| --- | --- |
+| `contract/` | 各语言客户端共同遵守的契约：公开函数（名称、参数顺序与默认值、返回）与它们调用的服务端函数 |
+| `contract/conformance/` | 同一组调用分别经 Python 与 C++ 客户端发给同一个服务端，逐项比对答案 |
+| `python/` | Python 客户端（PyPI 上的 `libfinance`） |
+| `cpp/` | C++ 客户端 |
+| `docs/` | 文档（中英双语） |

libfinance-0.1.2/README.md

@@ -0,0 +1,157 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/StateOfTheArt-quant/libfinance/main/docs/_shared/_static/img/libfinance_logo_dark.svg">
+  <img alt="libfinance" src="https://raw.githubusercontent.com/StateOfTheArt-quant/libfinance/main/docs/_shared/_static/img/libfinance_logo.svg" width="300">
+</picture>
+
+**面向量化研究与回测的 Python 金融数据接口 —— A 股与美股，同一套术语**
+
+[![PyPI](https://img.shields.io/pypi/v/libfinance?style=flat-square&logo=pypi&logoColor=white&label=PyPI)](https://pypi.org/project/libfinance/)
+[![docs zh-cn](https://img.shields.io/readthedocs/libfinance?style=flat-square&logo=readthedocs&logoColor=white&label=docs%20zh-cn)](https://libfinance.readthedocs.io/zh-cn/latest/)
+[![docs en](https://img.shields.io/readthedocs/libfinance-en?style=flat-square&logo=readthedocs&logoColor=white&label=docs%20en)](https://libfinance.readthedocs.io/en/latest/)
+
+[📘 中文文档](https://libfinance.readthedocs.io/zh-cn/latest/) ·
+[📗 English documentation](https://libfinance.readthedocs.io/en/latest/) ·
+[💻 示例代码](https://github.com/StateOfTheArt-quant/libfinance/tree/main/example) ·
+[🚀 快速开始](https://libfinance.readthedocs.io/zh-cn/latest/getting_started/quickstart.html) ·
+[🧭 概念设计](https://libfinance.readthedocs.io/zh-cn/latest/concepts/security_identifiers.html) ·
+[📑 API 参考](https://libfinance.readthedocs.io/zh-cn/latest/reference/contracts.html)
+
+</div>
+
+---
+
+`libfinance` 让 A 股与美股使用同一套术语：证券标识的写法相同，查询函数与参数名相同，返回的表结构也相同。两个市场的差别落在数据上，不落在调用方式上。
+
+覆盖行情、证券信息、交易日历、公司行动、财务数据及行业、指数与概念数据，并支持实时行情订阅。查询结果便于直接用于 pandas 分析。
+
+研究需要的不只是历史数字，还包括明确的证券身份、当时有效的信息，以及一致的价格口径。`libfinance` 把这三件事写进了数据设计：
+
+- **统一的证券标识符** —— 用 `<trading_code>.<namespace>` 表达证券，例如 `600000.XSHG`、`000001.XSHE`、`AAPL.US`，区分不同市场的同名代码；结合历史时点解析代码，减少更名与代码复用带来的歧义。
+- **point-in-time 机制 `as_of`** —— 按历史时点还原证券池，并选择当时已披露的财务版本，帮助避免未来信息和幸存者偏差。
+- **高质量的复权因子 `exfactor`** —— 结合公司行动处理价格可比性，提供不复权、前复权和后复权行情；通过 `get_ex_factor` 查看单次及累计因子，让价格变化有据可查。
+
+## 安装
+
+```bash
+pip install libfinance
+```
+
+从源码安装：
+
+```bash
+git clone https://github.com/StateOfTheArt-quant/libfinance.git
+cd libfinance/python
+pip install -e .
+```
+
+C++ 客户端（函数名、参数与 Python 版逐一相同，见 [cpp/README.md](cpp/README.md)）：
+
+```cpp
+#include <libfinance/libfinance.hpp>
+
+auto bars = libfinance::get_price({"000001.XSHE", "600000.XSHG"}, "2024-03-01", "2024-03-06");
+```
+
+## 快速开始
+
+按[安装与连接说明](https://libfinance.readthedocs.io/zh-cn/latest/getting_started/installation.html)配置服务后，即可查询：
+
+```python
+from libfinance import instruments, get_price, get_ex_factor
+
+# 查询历史时点对应的证券信息。
+print(instruments("600000.XSHG", as_of="2024-03-01"))
+
+# 显式选择不复权，查看历史原始行情。
+print(get_price(
+    ["000001.XSHE", "600000.XSHG"],
+    "2024-03-01", "2024-03-06", adjust_type="none",
+))
+
+# 查看公司行动对应的单次及累计复权因子。
+print(get_ex_factor("600000.XSHG", "2023-01-01", "2024-12-31"))
+```
+
+一分钟看懂这几行取到了什么，见[快速开始](https://libfinance.readthedocs.io/zh-cn/latest/getting_started/quickstart.html)。
+
+## A 股与美股共用一套术语
+
+统一体现在三个层面。
+
+| 层面 | 统一的内容 | 例 |
+| --- | --- | --- |
+| 证券标识 | 写法都是 `<trading_code>.<namespace>`；命名空间的粒度取决于该市场消除歧义所需的范围 | `600000.XSHG`、`AAPL.US` |
+| 函数与参数 | 两个市场调用同一组函数，参数名相同，`as_of` 与 `adjust_type` 的含义一致 | `get_price`、`instruments`、`get_dividends` |
+| 返回结构 | 列名与索引一致；某个市场不适用或未提供的字段取 `NaN`，不另设一张表 | 美股的 `turnover`、`limit_up`、`limit_down` |
+
+需要显式指定市场的，只有不涉及具体证券的查询：交易日历、全市场目录、数据覆盖范围。按证券查询时，命名空间已经给出了市场信息，列表里也可以混合两个市场的代码。
+
+```python
+from libfinance import instruments, get_trading_dates
+
+instruments(["000001.XSHE", "AAPL.US"])                      # 命名空间已给出市场
+get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体证券
+```
+
+统一的是术语和调用约定，数据本身的差异依然存在。下表的「市场」一列标出了每类数据实际覆盖的市场，逐个接口的情况见[查美股](https://libfinance.readthedocs.io/zh-cn/latest/howto/us_market.html)。
+
+## 数据覆盖
+
+| 数据 | 市场 | 主要函数 | 说明 |
+| --- | --- | --- | --- |
+| 交易日历 | CN · US | `get_trading_dates` | 交易日、区间取日、前后推 N 个交易日 |
+| 证券主数据 | CN · US | `all_instruments` | 代码、名称、类型、上市与退市日期 |
+| 日频行情 | CN · US | `get_price` | 开高低收、成交量额，可复权 |
+| 复权因子 | CN · US | `get_ex_factor` | 逐除权日的单次及累计因子 |
+| 股本结构 | CN | `get_shares` | 逐交易日的总股本与流通股本 |
+| 分红 / 拆股 / 配股 | CN · US | `get_dividends` | 除权事件，价格跳空的来源 |
+| 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
+| 财务报表（PIT） | CN | `get_pit_financials_ex` | 按季度取，带修订历史 |
+| 财务衍生指标 | CN、US | `get_financial_metrics` | 按交易日的财务衍生指标 |
+| 因子 | CN | `get_factor_exposure`、`list_factor_libraries`、`list_factors` | qlib、alpha158、Barra CNE5 风格 / 行业因子与描述符 |
+| 行业分类 | CN / US | `get_instrument_industry`、`get_industry_constituents`、`get_industry_weights` | 申万、GICS 等分类体系 |
+| 指数成分与权重 | CN | `get_index_weights` | 任意交易日的成分权重 |
+| 概念板块成分 | CN | `get_concept_weights` | THS 概念分类 |
+| 实时行情 | CN | `QuoteApi` | 订阅推送 |
+
+覆盖到哪一年、更新到哪一天，取决于你连的那个服务。**不要照抄文档里的日期**，用[数据新鲜度](https://libfinance.readthedocs.io/zh-cn/latest/data/freshness.html)里的两个函数自己查。
+
+## 概念设计
+
+| 主题 | 解决的问题 |
+| --- | --- |
+| [统一的证券标识符](https://libfinance.readthedocs.io/zh-cn/latest/concepts/security_identifiers.html) | 区分市场、证券身份及历史代码，准确关联不同数据 |
+| [point-in-time 机制 as_of](https://libfinance.readthedocs.io/zh-cn/latest/concepts/point_in_time.html) | 还原历史证券池与可见财报，避免未来信息和幸存者偏差 |
+| [高质量的复权因子 exfactor](https://libfinance.readthedocs.io/zh-cn/latest/concepts/exfactor.html) | 理解公司行动对价格的影响，以及三种价格口径的计算和用途 |
+
+## 文档与示例
+
+| | |
+| --- | --- |
+| [📘 中文文档](https://libfinance.readthedocs.io/zh-cn/latest/) | 概念设计、数据说明、操作指南与 API 参考 |
+| [📗 English documentation](https://libfinance.readthedocs.io/en/latest/) | The same documentation tree in English |
+| [💻 示例代码](https://github.com/StateOfTheArt-quant/libfinance/tree/main/example) | 按数据族排序的可运行示例（Python 与 C++ 一一对应），与 API 参考对照阅读 |
+| [🧩 操作指南](https://libfinance.readthedocs.io/zh-cn/latest/howto/index.html) | 取行情面板、PIT 回测、订阅实时行情等成套做法 |
+| [🩺 故障排查](https://libfinance.readthedocs.io/zh-cn/latest/howto/troubleshooting.html) | 按**症状**编排：看到什么现象，就从哪一行开始 |
+
+API 参考按合约信息和交易日历、行情信息、基本面信息、行业和概念信息、公司行动信息、实时行情分组，包含参数说明和带打印结果的场景示例。
+
+## 社区
+
+问题与需求请提 [Issue](https://github.com/StateOfTheArt-quant/libfinance/issues)。关注公众号获取更新：
+
+<div align="center">
+    <img alt="微信公众号二维码" src="https://raw.githubusercontent.com/StateOfTheArt-quant/libfinance/main/docs/_shared/_static/img/code.png" width="600" height="220">
+</div>
+
+## 仓库结构
+
+| 目录 | 内容 |
+| --- | --- |
+| `contract/` | 各语言客户端共同遵守的契约：公开函数（名称、参数顺序与默认值、返回）与它们调用的服务端函数 |
+| `contract/conformance/` | 同一组调用分别经 Python 与 C++ 客户端发给同一个服务端，逐项比对答案 |
+| `python/` | Python 客户端（PyPI 上的 `libfinance`） |
+| `cpp/` | C++ 客户端 |
+| `docs/` | 文档（中英双语） |

libfinance-0.1.2/VERSION

@@ -0,0 +1 @@
+0.1.2

libfinance-0.1.2/libfinance/__init__.py

@@ -0,0 +1,50 @@
+from .client import init_client
+
+# 不再 import 时连接 RPC（服务 A）；第一次调用 libfinance.api.* 会按 client.py 的
+# _DEFAULT_HOST/_DEFAULT_PORT 懒自动连接。两种方式指到别的服务端：
+#
+#   1. 环境变量（本地调试推荐，不用改代码）：
+#        export LIBFINANCE_HOST=127.0.0.1
+#        export LIBFINANCE_PORT=8080
+#      必须在 `import libfinance` 之前 export —— 取值发生在 import 时。
+#
+#   2. 显式调用：
+#        from libfinance import init_client
+#        init_client(host="127.0.0.1", port=8080)
+#
+# 两者都不设时连的是内置默认 libfinance.tech:8080，那是**生产环境**。
+# 这样 RPC 服务未就绪时，libfinance.subscribe 等子模块也可以独立使用。
+
+__all__ = ["__version__", "init_client"]
+
+
+def _version():
+    """The repository's one version (VERSION at its root), which the C++ client shares.
+
+    From a checkout it is read from that file; an installed package carries it in its metadata."""
+    from pathlib import Path
+    checkout = Path(__file__).resolve().parents[1]          # python/ in a checkout
+    if (checkout / "pyproject.toml").is_file() and (checkout / "VERSION").is_file():
+        return (checkout / "VERSION").read_text().strip()
+    try:
+        from importlib.metadata import version
+        return version("libfinance")
+    except Exception:  # noqa: BLE001 -- neither a checkout nor installed
+        return "0+unknown"
+
+
+__version__ = _version()
+#from libfinance.api import *
+def __go():
+    import sys
+    import importlib
+    import pkgutil
+
+    # 3.4 引入 asyncio，3.5 引入 async/await 语法，3.6 引入 async generator
+    async_syntax_supported = sys.version_info[:2] >= (3, 6)
+
+    for loader, module_name, is_pkg in pkgutil.walk_packages(__path__, "libfinance."):
+        if module_name.startswith("libfinance.api") and not is_pkg:
+            importlib.import_module(module_name)
+
+__go()

libfinance-0.1.2/libfinance/api/calendar.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+r"""交易日历。
+
+服务端只出\ **两条原语\ **——会话集合（\ ``get_trading_calendar``）与这份集合的\ **\ 权威区间**
+（\ ``get_calendar_coverage``\ ）。区间切片、前后推 n 个交易日、是否交易日、区间计数，全是
+在一个有序数组上做 bisect，在这里本地算：一个场所几千个日期、几十 KB、更新极慢，拉一次
+缓存一天，比每问一个日期就走一次 RPC 划算得多。
+
+**为什么必须一起取区间。** release 有一个 ``confirmed_through``——没人发布过的日子，
+任何据此推出的答案都是猜的。只拿会话集合而不校验区间，本地 bisect 会把"查询超出确认
+范围"悄悄变成"那几天没有交易"，回测不会察觉自己少了几天。区间也不能用
+``sessions[0]`` / ``sessions[-1]`` 顶替：端点是自然日，而最后一个会话是它之前的最后一个
+**交易日**\ ，中间隔着周末与假期。
+
+两者在 ``_calendar()`` 里\ **一次取回并一起缓存**\ ：分两次取、各自缓存，中间服务端切了一版
+就会拿到一对来自不同 release 的数据——用旧区间去校验新会话，而且没有任何迹象。
+
+``market`` 默认 ``"cn"``\ 。服务端的 calendar 命名空间同时绑了 CN 与 US，不传 market 时
+它无从选路会直接报错；给个默认值让既有调用继续工作，要美股传 ``market="us"``\ 。
+"""
+import json
+
+import pandas as pd
+
+from libfinance.client import get_client
+from libfinance.utils.decorators import export_as_api, ttl_cache
+
+DEFAULT_MARKET = "cn"
+
+
+class CalendarCoverageError(ValueError):
+    """查询落在 release 确认过的区间之外。
+
+    这不是"那天没有交易"——是没人发布过那一天，所以任何答案都是猜的。宁可报错，
+    也不要让调用方拿到一个悄悄变短的结果。
+    """
+
+
+def _to_timestamp(d):
+    return pd.Timestamp(d).replace(hour=0, minute=0, second=0, microsecond=0)
+
+
+@ttl_cache(24 * 3600)
+def _calendar(market=DEFAULT_MARKET):
+    """(会话集合, 区间下界, 区间上界)。两条 RPC 一次取回，绑在同一个缓存条目上。"""
+    client = get_client()
+    sessions = pd.to_datetime(json.loads(client.get_trading_calendar(market=market)))
+    window = client.get_calendar_coverage(market=market)
+    return (
+        sessions,
+        _to_timestamp(window["history_start"]),
+        _to_timestamp(window["confirmed_through"]),
+    )
+
+
+def _sessions(market, *dates):
+    """取会话集合，并确认每个被问到的日期都落在 release 确认过的区间内。"""
+    sessions, lower, upper = _calendar(market)
+    for value in dates:
+        if value < lower or value > upper:
+            raise CalendarCoverageError(
+                "{} 的查询 {} 超出 release 确认范围 {}..{}".format(
+                    market, value.date(), lower.date(), upper.date()
+                )
+            )
+    return sessions
+
+
+@export_as_api
+@ttl_cache(24 * 3600)
+def get_all_trading_dates(market=DEFAULT_MARKET):
+    r"""获取全部交易日。
+
+    :param market: 市场，cn（默认）或 us
+
+    :returns: pandas.DatetimeIndex，当前日历内全部交易日。
+    """
+    return _calendar(market)[0]
+
+
+@export_as_api
+def get_calendar_coverage(market=DEFAULT_MARKET):
+    r"""获取日历的权威区间——本 release 确认到哪一天。
+
+    :param market: 市场，cn（默认）或 us
+
+    :returns: dict，包含 history_start（历史起点）和 confirmed_through（确认上界），值为 pandas.Timestamp。
+    """
+    _, lower, upper = _calendar(market)
+    return {"history_start": lower, "confirmed_through": upper}
+
+
+@export_as_api
+def get_trading_dates(start_date, end_date, market=DEFAULT_MARKET):
+    r"""获取某个区间的交易日期
+
+    :param start_date: 开始日期
+    :param end_date: 结束日期
+    :param market: 市场，cn（默认）或 us
+
+    :returns: pandas.DatetimeIndex，包含起止日期之间的交易日（含两端）。
+    """
+    start_date, end_date = _to_timestamp(start_date), _to_timestamp(end_date)
+    sessions = _sessions(market, start_date, end_date)
+    left = sessions.searchsorted(start_date)
+    right = sessions.searchsorted(end_date, side="right")
+    return sessions[left:right]
+
+
+@export_as_api
+def get_previous_trading_date(date, n=1, market=DEFAULT_MARKET):
+    r"""获取指定日期之前的第 n 个交易日
+
+    :param date: 指定日期
+    :param n: 第 n 个交易日
+    :param market: 市场，cn（默认）或 us
+
+    :returns: pandas.Timestamp，严格早于输入日期的第 n 个交易日。
+    """
+    date = _to_timestamp(date)
+    sessions = _sessions(market, date)
+    pos = sessions.searchsorted(date)
+    if pos < n:
+        # 旧实现在这里返回 sessions[0]。那是个**错误答案**：调用方要的是"往前第 n 个"，
+        # 拿到的却是"最早的那个"，且无从分辨。宁可报错。
+        raise CalendarCoverageError(
+            "{} 之前没有第 {} 个交易日；release 的第一个交易日是 {}".format(
+                date.date(), n, sessions[0].date()
+            )
+        )
+    return sessions[pos - n]
+
+
+@export_as_api
+def get_next_trading_date(date, n=1, market=DEFAULT_MARKET):
+    r"""获取指定日期之后的第 n 个交易日
+
+    :param date: 指定日期
+    :param n: 第 n 个交易日
+    :param market: 市场，cn（默认）或 us
+
+    :returns: pandas.Timestamp，严格晚于输入日期的第 n 个交易日。
+    """
+    date = _to_timestamp(date)
+    sessions = _sessions(market, date)
+    pos = sessions.searchsorted(date, side="right")
+    if pos + n > len(sessions):
+        # 同上：旧实现返回 sessions[-1]，那是"日历到头了"而不是"往后第 n 个"。
+        raise CalendarCoverageError(
+            "{} 之后没有第 {} 个交易日；release 确认到 {}".format(
+                date.date(), n, _calendar(market)[2].date()
+            )
+        )
+    return sessions[pos + n - 1]
+
+
+@export_as_api
+def is_trading_date(date, market=DEFAULT_MARKET):
+    r"""判断指定日期是否为交易日
+
+    :param date: 指定日期
+    :param market: 市场，cn（默认）或 us
+
+    :returns: bool，交易日为 True，非交易日为 False；超出日历范围会报错。
+    """
+    date = _to_timestamp(date)
+    sessions = _sessions(market, date)
+    pos = sessions.searchsorted(date)
+    return pos < len(sessions) and sessions[pos] == date
+
+
+@export_as_api
+def get_n_trading_dates_until(date, n, market=DEFAULT_MARKET):
+    r"""获取截至指定日期（含）的最后 n 个交易日
+
+    :param date: 指定日期
+    :param n: 交易日个数
+    :param market: 市场，cn（默认）或 us
+
+    :returns: pandas.DatetimeIndex，截至该日的最近 n 个交易日；历史不足 n 个时返回已有日期。
+    """
+    date = _to_timestamp(date)
+    sessions = _sessions(market, date)
+    pos = sessions.searchsorted(date, side="right")
+    if pos >= n:
+        return sessions[pos - n:pos]
+    return sessions[:pos]
+
+
+@export_as_api
+def count_trading_dates(start_date, end_date, market=DEFAULT_MARKET):
+    r"""统计区间内的交易日数量
+
+    :param start_date: 开始日期
+    :param end_date: 结束日期
+    :param market: 市场，cn（默认）或 us
+
+    :returns: int，区间内的交易日数量（含两端）。
+    """
+    start_date, end_date = _to_timestamp(start_date), _to_timestamp(end_date)
+    sessions = _sessions(market, start_date, end_date)
+    return int(
+        sessions.searchsorted(end_date, side="right") - sessions.searchsorted(start_date)
+    )