libfinance 0.1.3

面向量化研究与回测的金融数据接口 —— A 股与美股一套术语，Python 与 C++ 一套函数

📘 中文文档 · 📗 English documentation · 💻 示例代码 · 🚀 快速开始 · 🧭 概念设计 · 📑 API 参考

量化研究的结论依赖历史数据，而历史数据有三类常见的失真：证券代码会更名、复用，不同市场之间还会重号；财务报表在披露后会被修订，回测若读取最新版本，就用上了当时无从获得的信息；分红、拆股等公司行动改变价格的可比性，复权口径不一致会直接扭曲收益。研究与生产又常常分别使用 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）实现，函数名、参数顺序与默认值、校验与报错、返回的列一一对应；同一组调用经两种客户端发给同一服务端逐项比对。

安装

pip install libfinance

从源码安装：

git clone https://github.com/StateOfTheArt-quant/libfinance.git
cd libfinance/python
pip install -e .

快速开始

按安装与连接说明配置服务后即可查询。以下输出均为真实运行结果，数据持续更新，行数与数值可能不同。

证券目录 —— 两个市场在同一张表里，列相同：

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"]]

              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"）：

from libfinance import get_trading_dates

get_trading_dates("2024-05-11", "2024-05-20")

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，表结构不变：

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")

                            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"），见价格口径。

因子 —— 库名 system/alpha158 展开为 158 个因子，每个因子一列：

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 列，列名只留因子名

                            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

逐步说明见快速开始。

A 股与美股共用一套术语

统一体现在三个层面。

需要显式指定市场的，只有不涉及具体证券的查询：交易日历、全市场目录、数据覆盖范围。按证券查询时，命名空间已经给出了市场信息，列表里也可以混合两个市场的代码。

from libfinance import instruments, get_trading_dates

instruments(["000001.XSHE", "AAPL.US"])                      # 命名空间已给出市场
get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体证券

统一的是术语和调用约定，数据本身的差异依然存在。下表的「市场」一列标出了每类数据实际覆盖的市场，逐个接口的情况见查美股。

数据覆盖

覆盖到哪一年、更新到哪一天，取决于你连的那个服务。不要照抄文档里的日期，用数据新鲜度里的两个函数自己查。

概念设计

文档与示例

API 参考按合约信息和交易日历、行情、基本面、行业与指数和主题、公司行动、实时行情、因子分组，每个函数附 Python 与 C++ 两种写法的示例及其真实输出。

社区

问题与需求请提 Issue。关注公众号获取更新：

仓库结构