libfinance 0.1.2__tar.gz → 0.1.4__tar.gz

libfinance-0.1.4/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: libfinance
+Version: 0.1.4
+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>
+
+**面向量化研究与回测的金融数据接口 —— A 股与美股一套术语，Python 与 C++ 一套函数**
+
+[![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>
+
+---
+
+量化研究的结论依赖历史数据，而历史数据有三类常见的失真：证券代码会更名、复用，不同市场之间还会重号；财务报表在披露后会被修订，回测若读取最新版本，就用上了当时无从获得的信息；分红、拆股等公司行动改变价格的可比性，复权口径不一致会直接扭曲收益。研究与生产又常常分别使用 Python 与 C++，两套接口的细微差别会让同一策略在迁移后得到不同的结果。
+
+`libfinance` 是面向量化研究与回测的金融数据客户端，覆盖 A 股与美股，提供 Python 与 C++ 两种实现。它以统一的证券标识、按时点（point-in-time）的数据版本和逐事件计算的复权因子组织行情、证券目录、交易日历、公司行动、股本、财务、行业 / 指数 / 主题成分与日频因子等数据；两个市场、两种语言遵循同一份接口契约，调用方式一致，差异只来自数据本身。
+
+数据设计的四条约定：
+
+- **统一的证券标识符** —— `<trading_code>.<namespace>`，如 `600000.XSHG`、`000001.XSHE`、`AAPL.US`。命名空间区分不同市场的同号代码，代码按历史时点解析，更名与代码复用不会串到别的证券。
+- **point-in-time 机制 `as_of`** —— 按历史时点还原证券池、选取当时已披露的财务版本，避免未来信息与幸存者偏差。
+- **高质量的复权因子 `exfactor`** —— 由公司行动逐事件计算，提供不复权、前复权、后复权三种口径；`get_ex_factor` 给出单次与累计因子，价格的每一次调整都可追溯。
+- **Python 与 C++ 统一的函数设计** —— 两种客户端按同一份契约（`contract/contract.json`）实现，函数名、参数顺序与默认值、校验与报错、返回的列一一对应；同一组调用经两种客户端发给同一服务端逐项比对。
+
+## 安装
+
+```bash
+pip install libfinance
+```
+
+从源码安装：
+
+```bash
+git clone https://github.com/StateOfTheArt-quant/libfinance.git
+cd libfinance/python
+pip install -e .
+```
+
+> [!TIP]
+> **使用 C++？** C++ 客户端与 Python 版函数一一对应，通过 CMake `FetchContent` 引入项目，依赖 Apache Arrow C++。安装、构建与示例见 [cpp/README.md](https://github.com/StateOfTheArt-quant/libfinance/blob/main/cpp/README.md)。
+
+## 快速开始
+
+按[安装与连接说明](https://libfinance.readthedocs.io/zh-cn/latest/getting_started/installation.html)配置服务后即可查询。以下输出均为真实运行结果，数据持续更新，行数与数值可能不同。
+
+**证券目录** —— 两个市场在同一张表里，列相同：
+
+```python
+from libfinance import all_instruments
+
+stocks = all_instruments(type="stock")
+stocks.set_index("order_book_id").loc[
+    ["600000.XSHG", "000001.XSHE", "AAPL.US", "NVDA.US"], ["market", "exchange", "name"]]
+```
+
+```text
+              market exchange                               name
+order_book_id
+600000.XSHG       CN     XSHG                               浦发银行
+000001.XSHE       CN     XSHE                               平安银行
+AAPL.US           US     XNAS          Apple Inc. - Common Stock
+NVDA.US           US     XNAS  NVIDIA Corporation - Common Stock
+```
+
+**交易日** —— 区间按自然日给，返回其中的交易日（美股传 `market="us"`）：
+
+```python
+from libfinance import get_trading_dates
+
+get_trading_dates("2024-05-11", "2024-05-20")
+```
+
+```text
+DatetimeIndex(['2024-05-13', '2024-05-14', '2024-05-15', '2024-05-16',
+               '2024-05-17', '2024-05-20'],
+              dtype='datetime64[us]', freq=None)
+```
+
+**行情** —— 一次调用混查两个市场；美股没有涨跌停，`limit_up` 为 `NaN`，表结构不变：
+
+```python
+from libfinance import get_price
+
+get_price(["600000.XSHG", "AAPL.US"], "2024-03-01", "2024-03-05",
+          fields=["open", "close", "volume", "limit_up"], adjust_type="none")
+```
+
+```text
+                            open   close    volume  limit_up
+order_book_id datetime
+600000.XSHG   2024-03-01    7.13    7.11  29431801      7.87
+              2024-03-04    7.12    7.07  27855963      7.82
+              2024-03-05    7.05    7.16  41756232      7.78
+AAPL.US       2024-03-01  179.55  179.66  73563100       NaN
+              2024-03-04  176.15  175.10  81510101       NaN
+              2024-03-05  170.76  170.12  95132400       NaN
+```
+
+`adjust_type="none"` 取当天的真实成交价；不传时默认前复权（`"pre"`），见[价格口径](https://libfinance.readthedocs.io/zh-cn/latest/data/price.html)。
+
+**因子** —— 库名 `system/alpha158` 展开为 158 个因子，每个因子一列：
+
+```python
+from libfinance import get_factor_exposure
+
+f = get_factor_exposure(["600000.XSHG", "000001.XSHE"], "system/alpha158", "2026-09-07", "2026-09-10")
+f.iloc[:, :6].rename(columns=lambda c: c.rsplit("/", 1)[1]).round(4)   # 前 6 列，列名只留因子名
+```
+
+```text
+                            KMID    KLEN   KMID2     KUP    KUP2    KLOW
+order_book_id date
+600000.XSHG   2026-09-07 -0.0212  0.0286 -0.7407  0.0032  0.1111  0.0042
+              2026-09-08  0.0076  0.0141  0.5385  0.0065  0.4615  0.0000
+              2026-09-09 -0.0022  0.0086 -0.2500  0.0043  0.5000  0.0022
+              2026-09-10  0.0141  0.0184  0.7647  0.0011  0.0588  0.0033
+000001.XSHE   2026-09-07 -0.0143  0.0194 -0.7391  0.0008  0.0435  0.0042
+              2026-09-08  0.0103  0.0137  0.7500  0.0026  0.1875  0.0009
+              2026-09-09 -0.0051  0.0085 -0.6000  0.0026  0.3000  0.0009
+              2026-09-10  0.0146  0.0171  0.8500  0.0009  0.0500  0.0017
+```
+
+逐步说明见[快速开始](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`、`instruments` | 股票、指数、行业、主题；代码、名称、上市与退市日期 |
+| 日频行情 | CN · US | `get_price` | 开高低收、成交量额、涨跌停价，可复权 |
+| 复权因子 | CN · US | `get_ex_factor` | 逐除权日的单次及累计因子 |
+| 股本 | CN · US | `get_shares` | 逐交易日的总股本与流通股本 |
+| 换手率 | CN、US | `get_turnover_rate` | 逐交易日的换手率（未复权成交量 ÷ A 股自由流通股本或美股已发行股数） |
+| 分红 / 拆股 / 配股 | CN · US | `get_dividends`、`get_splits`、`get_allotments` | 除权事件；配股只有 A 股 |
+| 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
+| 财务报表（PIT） | CN · US | `get_pit_financials_ex` | 按季度取，带修订历史 |
+| 财务衍生指标 | CN · US | `get_financial_metrics` | 按交易日的财务衍生指标 |
+| 行业分类 | CN · US | `get_instrument_industry`、`get_industry_constituents`、`get_industry_weights` | 申万、GICS 等分类体系 |
+| 指数成分与权重 | CN · US | `get_index_constituents`、`get_index_weights` | 中证、标普等 |
+| 主题成分与权重 | CN | `get_theme_constituents`、`get_theme_weights` | THS 主题 |
+| 日频因子 | CN | `get_factor_exposure`、`list_factor_libraries`、`list_factors` | alpha158、qlib，Barra CNE5 风格 / 行业因子，CNE5 与 CNE6 描述符；见[因子数据](https://libfinance.readthedocs.io/zh-cn/latest/data/factors.html)与[因子字典](https://libfinance.readthedocs.io/zh-cn/latest/reference/factor_dictionary.html) |
+| 实时行情 | CN | `get_last_quotes`、`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) | 理解公司行动对价格的影响，以及三种价格口径的计算和用途 |
+| [Python 与 C++ 统一的函数设计](https://libfinance.readthedocs.io/zh-cn/latest/concepts/python_cpp.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 参考按合约信息和交易日历、行情、基本面、行业与指数和主题、公司行动、实时行情、因子分组，每个函数附 Python 与 C++ 两种写法的示例及其真实输出。
+
+## 社区
+
+问题与需求请提 [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.4/README.md

@@ -0,0 +1,216 @@
+<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>
+
+**面向量化研究与回测的金融数据接口 —— A 股与美股一套术语，Python 与 C++ 一套函数**
+
+[![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>
+
+---
+
+量化研究的结论依赖历史数据，而历史数据有三类常见的失真：证券代码会更名、复用，不同市场之间还会重号；财务报表在披露后会被修订，回测若读取最新版本，就用上了当时无从获得的信息；分红、拆股等公司行动改变价格的可比性，复权口径不一致会直接扭曲收益。研究与生产又常常分别使用 Python 与 C++，两套接口的细微差别会让同一策略在迁移后得到不同的结果。
+
+`libfinance` 是面向量化研究与回测的金融数据客户端，覆盖 A 股与美股，提供 Python 与 C++ 两种实现。它以统一的证券标识、按时点（point-in-time）的数据版本和逐事件计算的复权因子组织行情、证券目录、交易日历、公司行动、股本、财务、行业 / 指数 / 主题成分与日频因子等数据；两个市场、两种语言遵循同一份接口契约，调用方式一致，差异只来自数据本身。
+
+数据设计的四条约定：
+
+- **统一的证券标识符** —— `<trading_code>.<namespace>`，如 `600000.XSHG`、`000001.XSHE`、`AAPL.US`。命名空间区分不同市场的同号代码，代码按历史时点解析，更名与代码复用不会串到别的证券。
+- **point-in-time 机制 `as_of`** —— 按历史时点还原证券池、选取当时已披露的财务版本，避免未来信息与幸存者偏差。
+- **高质量的复权因子 `exfactor`** —— 由公司行动逐事件计算，提供不复权、前复权、后复权三种口径；`get_ex_factor` 给出单次与累计因子，价格的每一次调整都可追溯。
+- **Python 与 C++ 统一的函数设计** —— 两种客户端按同一份契约（`contract/contract.json`）实现，函数名、参数顺序与默认值、校验与报错、返回的列一一对应；同一组调用经两种客户端发给同一服务端逐项比对。
+
+## 安装
+
+```bash
+pip install libfinance
+```
+
+从源码安装：
+
+```bash
+git clone https://github.com/StateOfTheArt-quant/libfinance.git
+cd libfinance/python
+pip install -e .
+```
+
+> [!TIP]
+> **使用 C++？** C++ 客户端与 Python 版函数一一对应，通过 CMake `FetchContent` 引入项目，依赖 Apache Arrow C++。安装、构建与示例见 [cpp/README.md](https://github.com/StateOfTheArt-quant/libfinance/blob/main/cpp/README.md)。
+
+## 快速开始
+
+按[安装与连接说明](https://libfinance.readthedocs.io/zh-cn/latest/getting_started/installation.html)配置服务后即可查询。以下输出均为真实运行结果，数据持续更新，行数与数值可能不同。
+
+**证券目录** —— 两个市场在同一张表里，列相同：
+
+```python
+from libfinance import all_instruments
+
+stocks = all_instruments(type="stock")
+stocks.set_index("order_book_id").loc[
+    ["600000.XSHG", "000001.XSHE", "AAPL.US", "NVDA.US"], ["market", "exchange", "name"]]
+```
+
+```text
+              market exchange                               name
+order_book_id
+600000.XSHG       CN     XSHG                               浦发银行
+000001.XSHE       CN     XSHE                               平安银行
+AAPL.US           US     XNAS          Apple Inc. - Common Stock
+NVDA.US           US     XNAS  NVIDIA Corporation - Common Stock
+```
+
+**交易日** —— 区间按自然日给，返回其中的交易日（美股传 `market="us"`）：
+
+```python
+from libfinance import get_trading_dates
+
+get_trading_dates("2024-05-11", "2024-05-20")
+```
+
+```text
+DatetimeIndex(['2024-05-13', '2024-05-14', '2024-05-15', '2024-05-16',
+               '2024-05-17', '2024-05-20'],
+              dtype='datetime64[us]', freq=None)
+```
+
+**行情** —— 一次调用混查两个市场；美股没有涨跌停，`limit_up` 为 `NaN`，表结构不变：
+
+```python
+from libfinance import get_price
+
+get_price(["600000.XSHG", "AAPL.US"], "2024-03-01", "2024-03-05",
+          fields=["open", "close", "volume", "limit_up"], adjust_type="none")
+```
+
+```text
+                            open   close    volume  limit_up
+order_book_id datetime
+600000.XSHG   2024-03-01    7.13    7.11  29431801      7.87
+              2024-03-04    7.12    7.07  27855963      7.82
+              2024-03-05    7.05    7.16  41756232      7.78
+AAPL.US       2024-03-01  179.55  179.66  73563100       NaN
+              2024-03-04  176.15  175.10  81510101       NaN
+              2024-03-05  170.76  170.12  95132400       NaN
+```
+
+`adjust_type="none"` 取当天的真实成交价；不传时默认前复权（`"pre"`），见[价格口径](https://libfinance.readthedocs.io/zh-cn/latest/data/price.html)。
+
+**因子** —— 库名 `system/alpha158` 展开为 158 个因子，每个因子一列：
+
+```python
+from libfinance import get_factor_exposure
+
+f = get_factor_exposure(["600000.XSHG", "000001.XSHE"], "system/alpha158", "2026-09-07", "2026-09-10")
+f.iloc[:, :6].rename(columns=lambda c: c.rsplit("/", 1)[1]).round(4)   # 前 6 列，列名只留因子名
+```
+
+```text
+                            KMID    KLEN   KMID2     KUP    KUP2    KLOW
+order_book_id date
+600000.XSHG   2026-09-07 -0.0212  0.0286 -0.7407  0.0032  0.1111  0.0042
+              2026-09-08  0.0076  0.0141  0.5385  0.0065  0.4615  0.0000
+              2026-09-09 -0.0022  0.0086 -0.2500  0.0043  0.5000  0.0022
+              2026-09-10  0.0141  0.0184  0.7647  0.0011  0.0588  0.0033
+000001.XSHE   2026-09-07 -0.0143  0.0194 -0.7391  0.0008  0.0435  0.0042
+              2026-09-08  0.0103  0.0137  0.7500  0.0026  0.1875  0.0009
+              2026-09-09 -0.0051  0.0085 -0.6000  0.0026  0.3000  0.0009
+              2026-09-10  0.0146  0.0171  0.8500  0.0009  0.0500  0.0017
+```
+
+逐步说明见[快速开始](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`、`instruments` | 股票、指数、行业、主题；代码、名称、上市与退市日期 |
+| 日频行情 | CN · US | `get_price` | 开高低收、成交量额、涨跌停价，可复权 |
+| 复权因子 | CN · US | `get_ex_factor` | 逐除权日的单次及累计因子 |
+| 股本 | CN · US | `get_shares` | 逐交易日的总股本与流通股本 |
+| 换手率 | CN、US | `get_turnover_rate` | 逐交易日的换手率（未复权成交量 ÷ A 股自由流通股本或美股已发行股数） |
+| 分红 / 拆股 / 配股 | CN · US | `get_dividends`、`get_splits`、`get_allotments` | 除权事件；配股只有 A 股 |
+| 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
+| 财务报表（PIT） | CN · US | `get_pit_financials_ex` | 按季度取，带修订历史 |
+| 财务衍生指标 | CN · US | `get_financial_metrics` | 按交易日的财务衍生指标 |
+| 行业分类 | CN · US | `get_instrument_industry`、`get_industry_constituents`、`get_industry_weights` | 申万、GICS 等分类体系 |
+| 指数成分与权重 | CN · US | `get_index_constituents`、`get_index_weights` | 中证、标普等 |
+| 主题成分与权重 | CN | `get_theme_constituents`、`get_theme_weights` | THS 主题 |
+| 日频因子 | CN | `get_factor_exposure`、`list_factor_libraries`、`list_factors` | alpha158、qlib，Barra CNE5 风格 / 行业因子，CNE5 与 CNE6 描述符；见[因子数据](https://libfinance.readthedocs.io/zh-cn/latest/data/factors.html)与[因子字典](https://libfinance.readthedocs.io/zh-cn/latest/reference/factor_dictionary.html) |
+| 实时行情 | CN | `get_last_quotes`、`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) | 理解公司行动对价格的影响，以及三种价格口径的计算和用途 |
+| [Python 与 C++ 统一的函数设计](https://libfinance.readthedocs.io/zh-cn/latest/concepts/python_cpp.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 参考按合约信息和交易日历、行情、基本面、行业与指数和主题、公司行动、实时行情、因子分组，每个函数附 Python 与 C++ 两种写法的示例及其真实输出。
+
+## 社区
+
+问题与需求请提 [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.4/VERSION

@@ -0,0 +1 @@
+0.1.4

{libfinance-0.1.2 → libfinance-0.1.4}/libfinance/api/exfactor.py

@@ -22,7 +22,7 @@ def get_ex_factor(
     :param end_date: 结束除权日，含当日；省略则查询至数据截止日。
         代码按该日有效的身份解析，省略时按当前代码解析
     :returns: 以 ex_date 为 DatetimeIndex 的 DataFrame，包含 order_book_id、
-        permanent_id、ex_factor、ex_cum_factor。ex_factor 是单个除权日因子，同日行动已合成；
+        ex_factor、ex_cum_factor。ex_factor 是单个除权日因子，同日行动已合成；
         ex_cum_factor 是从数据版本内该证券首个事件前以 1 为基准的累计因子。
         已覆盖证券在窗口内无记录时返回保留索引和列结构的空表。
 

{libfinance-0.1.2 → libfinance-0.1.4}/libfinance/api/get_price.py

@@ -129,7 +129,7 @@ def get_price(
         指数原样返回
     :param adjust_orig: 前复权的基准日；省略时为 ``end_date``\ ：价格换算到查询区间最后一天的口径，
         区间之后的除权不影响结果（point-in-time）
-    :returns: 以 ``(order_book_id, datetime)`` 为索引的 DataFrame，列为 ``permanent_id`` 与所选字段。
+    :returns: 以 ``(order_book_id, datetime)`` 为索引的 DataFrame，列为所选字段。
 
     复权规则：成交量随复权反向缩放，成交额 ``turnover`` 不受复权影响。
     """
@@ -167,7 +167,7 @@ def get_price(
 
 
 def _to_panel(frame):
-    r"""daybar 的扁平表（\ ``order_book_id, permanent_id, session_date, 字段...``\ ）还原成
+    r"""daybar 的扁平表（\ ``order_book_id, session_date, 字段...``\ ）还原成
     ``(order_book_id, datetime)`` 索引。不认识的形状原样返回，让调用方看见真实的列。"""
     if not isinstance(frame, pd.DataFrame) or not {"order_book_id", "session_date"} <= set(frame.columns):
         return frame

{libfinance-0.1.2 → libfinance-0.1.4}/libfinance/api/index_components.py

@@ -50,7 +50,7 @@ def get_index_weights(order_book_id: str, as_of=None) -> pd.DataFrame:
 
     :param order_book_id: 指数代码，如 ``"000300.XSHG"``
     :param as_of: 那一天的事实；省略则取指数已确认的最新日期
-    :returns: pandas.DataFrame，包含 order_book_id（成分证券）、permanent_id、weight、methodology、source（指数发布机构）、
+    :returns: pandas.DataFrame，包含 order_book_id（成分证券）、weight、methodology、source（指数发布机构）、
         basis（origin 数据源发布 / reconstructed 按编制方法重构）、date（权重所在的日子）、quality_flags。
         权重是月末快照：其余交易日取之前最近一期、按各成分的复权收益率漂移，date 为 as_of，quality_flags 带 DRIFTED。
     """

{libfinance-0.1.2 → libfinance-0.1.4}/libfinance/api/instrument.py

@@ -5,8 +5,8 @@ r"""证券目录：股票、指数、行业、主题在同一个 instrument 聚
 签名与列名取自后端 instrument 数据族（\ ``instrument.all_instruments`` /
 ``instrument.instruments``\ ），本模块只做参数检查、按数据版本缓存与结果的形状。
 
-* ``order_book_id`` 是代码（\ ``600000.XSHG``\ 、\ ``000300.XSHG``\ 、\ ``AAPL.US``\ ），
-  ``permanent_id`` 是证券不随代码变化的身份，\ ``name`` 是名称。
+* ``order_book_id`` 是代码（\ ``600000.XSHG``\ 、\ ``000300.XSHG``\ 、\ ``AAPL.US``\ ），也是客户端唯一的证券标识；
+  ``name`` 是名称。
 * ``type`` 取 ``stock`` / ``index`` / ``industry`` / ``theme``\ 。
 * ``source`` 是定义并编号证券的机构：股票的交易所（XSHG、XNAS）、指数的发布机构
   （CSI、SPDJI）、行业的分类体系（SW、GICS）、主题的 THS；\ ``exchange`` 只有股票有。
@@ -25,7 +25,7 @@ from libfinance.utils.validators import ensure_list_of_string
 VALID_TYPES = ("stock", "index", "industry", "theme")
 
 #: all_instruments 的列，按后端的顺序。
-COLUMNS = ("order_book_id", "permanent_id", "type", "market", "name", "exchange", "source")
+COLUMNS = ("order_book_id", "type", "market", "name", "exchange", "source")
 
 
 class Instrument(object):
@@ -90,7 +90,7 @@ def all_instruments(
     :param as_of: 给出则为该日的历史视图；省略时各类型取各自的当前状态。某类型不覆盖的日期
         报 CoverageError 并写明类型，缩小 ``type`` 或 ``source`` 即可。
     :param cached: 是否使用按服务端数据版本更新的缓存；显式指定市场时直接查询。
-    :returns: DataFrame，列为 ``order_book_id, permanent_id, type, market, name, exchange, source``\ 。
+    :returns: DataFrame，列为 ``order_book_id, type, market, name, exchange, source``\ 。
     """
     types = _normalize_types(type)
     sources = _optional_strings(source, "source")

{libfinance-0.1.2 → libfinance-0.1.4}/libfinance/api/live_quote.py

@@ -8,8 +8,7 @@ from libfinance.subscribe.md_protocol import Quote
 Quote 的字段集与订阅路径统一（定义见 libfinance/subscribe/md_protocol.py，对齐 dynamics）：
 
     data_time: int
-    instrument_id: str            exchange_id: str        # 代码与交易所后缀，如 600000 / XSHG
-    instrument_type: int          # InstrumentType 枚举
+    order_book_id: str            # 如 600000.XSHG（协议 v4 起唯一的标的字段）
     pre_close_price / pre_settlement_price / last_price / volume / turnover
     pre_open_interest / open_interest
     open_price / high_price / low_price / upper_limit_price / lower_limit_price
@@ -17,13 +16,16 @@ Quote 的字段集与订阅路径统一（定义见 libfinance/subscribe/md_prot
     total_bid_volume / total_ask_volume / total_trade_num
     bid_price / ask_price / bid_volume / ask_volume    # 均为 list[float]，10 档
     trading_phase_code: str
-    order_book_id: str            # 只读属性 = f"{instrument_id}.{exchange_id}"
 
 注意：本函数走 RPC（8080），与行情网关是两条独立通路，只是复用同一个 Quote 类型。
 服务端返回体的字段名须与上面一致；下面用 __dict__ 注入，多余的键会原样带上，
 缺失的键则在访问时才报 AttributeError。
 """
 
+#: 协议 v4 之前的标的字段：order_book_id 已包含全部信息，旧服务端送来也丢掉。
+_RETIRED = frozenset(("instrument_id", "exchange_id", "instrument_type"))
+
+
 def dict_to_quotes_ultrafast(raw_data) -> dict[str, Quote]:
     result = {}
     for k, v in raw_data.items():
@@ -39,7 +41,8 @@ def dict_to_quotes_ultrafast(raw_data) -> dict[str, Quote]:
             
         # 🧹 3. 是 dict 时快速清洗内部 None 值，防止下游量价计算报 TypeError
         # 字典推导式在 CPython 底层由 C 循环驱动，性能损耗 < 5%
-        clean_v = {fk: fv for fk, fv in v.items() if fv is not None}
+        clean_v = {fk: fv for fk, fv in v.items() if fv is not None and fk not in _RETIRED}
+        clean_v.setdefault("order_book_id", k)   # 键就是 order_book_id；旧服务端不带这个字段
         
         # 🚀 4. 绕过 __init__ 参数绑定，直接注入对象内存
         q = object.__new__(Quote)

{libfinance-0.1.2 → libfinance-0.1.4}/libfinance/api/shares.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-"""股本：统一字段，CN 与 US 同一套（后端 shares 数据族的 get_shares_panel）。"""
+"""股本：统一字段，CN 与 US 同一套（后端 shares 数据族的 get_shares_panel）；以及由它算出的日频换手率。"""
 from typing import List, Optional, Union
 
 import pandas as pd
@@ -71,6 +71,42 @@ def get_shares(
     return _indexed(frame)
 
 
+@export_as_api
+def get_turnover_rate(
+    order_book_ids: Union[str, List[str]],
+    start_date=None,
+    end_date=None,
+) -> pd.DataFrame:
+    r"""获取日频换手率。
+
+    A 股换手率 = 当日未复权成交量 ÷ 当日生效的自由流通股本（没有时用流通股本）；
+    美股换手率 = 当日未复权成交量 ÷ 当日已发行股数。结果是\ **小数**\ （0.01 即 1%）。
+    A 股结果与 factors-daybar 的因子（如 ``system/broker-daybar/TURN20``\ ）读取的换手率同一口径。
+
+    :param order_book_ids: 单个代码或代码列表，如 ``"600000.XSHG"``、``"AAPL.US"``
+    :param start_date: 开始日期；只给一个日期时取那一天
+    :param end_date: 结束日期；两个都省略时各市场分别取最近两周内最后一个有行情的交易日
+
+    :returns: pandas.DataFrame，以 (order_book_id, date) 为索引，一列 ``turnover_rate``\ 。停牌日没有行；
+              没有股本数据的证券或日子为 NaN。
+    """
+    order_book_ids = ensure_list_of_string(order_book_ids, "order_book_ids")
+    if not order_book_ids:
+        raise ValueError("order_book_ids: at least one order book id expected")
+    if start_date is not None:
+        start_date = to_date_str(start_date)
+    if end_date is not None:
+        end_date = to_date_str(end_date)
+    if start_date is not None and end_date is not None and start_date > end_date:
+        raise ValueError(
+            "invalid date range: [{!r}, {!r}]".format(start_date, end_date)
+        )
+    frame = get_client().get_turnover_rate(
+        order_book_ids=order_book_ids, start_date=start_date, end_date=end_date,
+    )
+    return _indexed(frame)
+
+
 def _indexed(frame):
     """服务端的扁平表（order_book_id, date, 字段...）-> (order_book_id, date) 索引；已带索引的原样返回。"""
     if not isinstance(frame, pd.DataFrame) or not {"order_book_id", "date"} <= set(frame.columns):