libfinance 0.1.1__tar.gz → 0.1.2__tar.gz

{libfinance-0.1.1 → libfinance-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libfinance
-Version: 0.1.1
+Version: 0.1.2
 Summary: libfinance is a modern finance API
 Description-Content-Type: text/markdown
 Requires-Dist: lz4
@@ -122,10 +122,11 @@ get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体
 | 分红 / 拆股 / 配股 | CN · US | `get_dividends` | 除权事件，价格跳空的来源 |
 | 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
 | 财务报表（PIT） | CN | `get_pit_financials_ex` | 按季度取，带修订历史 |
-| 财务衍生指标 | CN、US | `get_financial_metrics` | 按交易日的财务衍生指标（RQData get_factor 同形） |
+| 财务衍生指标 | 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` | 同花顺概念分类 |
+| 概念板块成分 | CN | `get_concept_weights` | THS 概念分类 |
 | 实时行情 | CN | `QuoteApi` | 订阅推送 |
 
 覆盖到哪一年、更新到哪一天，取决于你连的那个服务。**不要照抄文档里的日期**，用[数据新鲜度](https://libfinance.readthedocs.io/zh-cn/latest/data/freshness.html)里的两个函数自己查。
@@ -163,7 +164,7 @@ API 参考按合约信息和交易日历、行情信息、基本面信息、行
 | 目录 | 内容 |
 | --- | --- |
 | `contract/` | 各语言客户端共同遵守的契约：公开函数（名称、参数顺序与默认值、返回）与它们调用的服务端函数 |
+| `contract/conformance/` | 同一组调用分别经 Python 与 C++ 客户端发给同一个服务端，逐项比对答案 |
 | `python/` | Python 客户端（PyPI 上的 `libfinance`） |
 | `cpp/` | C++ 客户端 |
-| `conformance/` | 同一组调用分别经 Python 与 C++ 客户端发给同一个服务端，逐项比对答案 |
 | `docs/` | 文档（中英双语） |

{libfinance-0.1.1 → libfinance-0.1.2}/README.md

@@ -109,10 +109,11 @@ get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体
 | 分红 / 拆股 / 配股 | CN · US | `get_dividends` | 除权事件，价格跳空的来源 |
 | 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
 | 财务报表（PIT） | CN | `get_pit_financials_ex` | 按季度取，带修订历史 |
-| 财务衍生指标 | CN、US | `get_financial_metrics` | 按交易日的财务衍生指标（RQData get_factor 同形） |
+| 财务衍生指标 | 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` | 同花顺概念分类 |
+| 概念板块成分 | CN | `get_concept_weights` | THS 概念分类 |
 | 实时行情 | CN | `QuoteApi` | 订阅推送 |
 
 覆盖到哪一年、更新到哪一天，取决于你连的那个服务。**不要照抄文档里的日期**，用[数据新鲜度](https://libfinance.readthedocs.io/zh-cn/latest/data/freshness.html)里的两个函数自己查。
@@ -150,7 +151,7 @@ API 参考按合约信息和交易日历、行情信息、基本面信息、行
 | 目录 | 内容 |
 | --- | --- |
 | `contract/` | 各语言客户端共同遵守的契约：公开函数（名称、参数顺序与默认值、返回）与它们调用的服务端函数 |
+| `contract/conformance/` | 同一组调用分别经 Python 与 C++ 客户端发给同一个服务端，逐项比对答案 |
 | `python/` | Python 客户端（PyPI 上的 `libfinance`） |
 | `cpp/` | C++ 客户端 |
-| `conformance/` | 同一组调用分别经 Python 与 C++ 客户端发给同一个服务端，逐项比对答案 |
 | `docs/` | 文档（中英双语） |

libfinance-0.1.2/VERSION

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

libfinance-0.1.2/libfinance/api/factors.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+r"""日频因子：qlib、alpha158、Barra CNE5 风格 / 行业因子与描述符（factors-daybar）。
+
+因子名写全名：库 ``owner/library[@rev]``\ （展开为它的全部因子）或因子 ``owner/library/factor[@rev]``\ ，
+可以混在一次请求里；\ ``list_factor_libraries``\ 、\ ``list_factors`` 列出可用的名字。值为 float32，NaN 表示
+在 universe 中但无法计算。
+
+截面因子（如 ``system/barra-cne5`` 的风格因子）的值取决于截面里有哪些股票，由服务端在读取时计算：默认是
+当天全部 A 股，传 ``universe`` 时在这批代码上重算。时序因子（qlib、alpha158、Barra 描述符、行业哑变量）
+不受 ``universe`` 影响。
+"""
+from typing import List, Optional, Union
+
+import pandas as pd
+
+from libfinance.client import get_client
+from libfinance.utils.cache import warn_if_clamped, warn_if_truncated
+from libfinance.utils.decorators import export_as_api
+from libfinance.utils.utils import to_date_str
+from libfinance.utils.validators import ensure_list_of_string, ensure_string
+
+
+@export_as_api
+def get_factor_exposure(
+    order_book_ids: Union[str, List[str]],
+    factor_names: Union[str, List[str]],
+    start_date,
+    end_date,
+    universe: Optional[Union[str, List[str]]] = None,
+) -> pd.DataFrame:
+    r"""获取因子暴露。
+
+    :param order_book_ids: 单个代码或代码列表
+    :param factor_names: 库名（如 ``"system/barra-cne5"``\ ）或因子全名（如 ``"system/qlib/MA5"``\ ），
+                         一个或一组，可以混合
+    :param start_date: 起始日期；与 ``end_date`` 相同时是当天的截面
+    :param end_date: 结束日期
+    :param universe: 截面因子的计算范围（代码列表）；省略为当天全部 A 股。只影响截面因子
+
+    :returns: pandas.DataFrame，以 (order_book_id, date) 为索引，每个因子一列，列名为因子全名
+              （库展开为 ``owner/library/factor``\ ）。
+    """
+    ids = ensure_list_of_string(order_book_ids, "order_book_ids")
+    if not ids:
+        raise ValueError("order_book_ids: at least one order book id expected")
+    names = ensure_list_of_string(factor_names, "factor_names")
+    if not names:
+        raise ValueError("factor_names: at least one factor name expected")
+    start, end = to_date_str(start_date), to_date_str(end_date)
+    if start > end:
+        raise ValueError("start_date {} is after end_date {}".format(start, end))
+    members = None if universe is None else ensure_list_of_string(universe, "universe")
+    warn_if_clamped("get_factor_exposure", start)
+    warn_if_truncated("get_factor_exposure", len(ids))
+    frame = get_client().get_factor_exposure(order_book_ids=ids, factor_names=names, start_date=start,
+                                             end_date=end, universe=members)
+    if not isinstance(frame, pd.DataFrame) or not {"order_book_id", "date"} <= set(frame.columns):
+        return frame
+    frame = frame.copy()
+    frame["date"] = pd.to_datetime(frame["date"])
+    return frame.set_index(["order_book_id", "date"])
+
+
+@export_as_api
+def list_factor_libraries() -> pd.DataFrame:
+    r"""列出因子库。
+
+    :returns: pandas.DataFrame，列为 name（库名）、version（当前版本）、factors（因子数）、description。
+    """
+    rows = get_client().list_factor_libraries()
+    return pd.DataFrame(list(rows or []), columns=["name", "version", "factors", "description"])
+
+
+@export_as_api
+def list_factors(library: Optional[str] = None) -> List[str]:
+    r"""列出因子全名。
+
+    :param library: 库名，如 ``"system/barra-cne5"``\ ；省略为全部库
+
+    :returns: 带版本的因子全名列表，如 ``["system/barra-cne5/SIZE@v2.0.0", ...]``\ ；去掉 ``@版本`` 即读取当前版本
+    """
+    if library is not None:
+        library = ensure_string(library, "library")
+    return list(get_client().list_factors(library=library) or [])

{libfinance-0.1.1 → libfinance-0.1.2}/libfinance/api/financials.py

@@ -74,7 +74,7 @@ def get_financial_metrics(
     start_date=None,
     end_date=None,
 ) -> pd.DataFrame:
-    r"""获取财务衍生指标（RQData ``get_factor`` 同形），CN 与 US 同一套公式。
+    r"""获取财务衍生指标，CN 与 US 同一套公式。
 
     每个交易日的值来自那一天收盘后能看到的最新报告：数值在公告日跳变、其间持平；最新报告算不出的为 NaN，
     不退回更早的报告。

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

@@ -124,14 +124,14 @@ def get_price(
         字段由服务端核对。
     :param skip_suspended: 是否去掉无成交的日子（成交量为 0），默认 False。只发布收盘点位、没有成交量
         的指数日不算停牌。
-    :param include_now: 对日线没有影响，保留与 rqdata 的 ``get_price`` 对齐
+    :param include_now: 对日线没有影响，保留以兼容常见的 ``get_price`` 签名
     :param adjust_type: 股票的复权方式：\ ``"pre"`` 前复权（默认）、\ ``"post"`` 后复权或 ``"none"`` 原始价；
         指数原样返回
     :param adjust_orig: 前复权的基准日；省略时为 ``end_date``\ ：价格换算到查询区间最后一天的口径，
         区间之后的除权不影响结果（point-in-time）
     :returns: 以 ``(order_book_id, datetime)`` 为索引的 DataFrame，列为 ``permanent_id`` 与所选字段。
 
-    规则同 rqalpha：成交量随复权反向缩放，成交额 ``turnover`` 不受复权影响。
+    复权规则：成交量随复权反向缩放，成交额 ``turnover`` 不受复权影响。
     """
     ids = ensure_list_of_string(order_book_ids, "order_book_ids")
     if not ids:

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

@@ -8,7 +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        # rqdata 风格，如 600000 / XSHG
+    instrument_id: str            exchange_id: str        # 代码与交易所后缀，如 600000 / XSHG
     instrument_type: int          # InstrumentType 枚举
     pre_close_price / pre_settlement_price / last_price / volume / turnover
     pre_open_interest / open_interest

{libfinance-0.1.1 → libfinance-0.1.2}/libfinance/api/theme.py

@@ -48,7 +48,7 @@ def get_instrument_themes(order_book_ids, source: Optional[str] = None, as_of=No
 def get_theme_weights(order_book_id: str, as_of=None) -> pd.DataFrame:
     r"""获取主题在指定日期的成分权重。
 
-    每一行都带 ``methodology``\ ：同花顺主题的 ``derived_equal_weight`` 是由成分名单推出的等权，
+    每一行都带 ``methodology``\ ：THS 主题的 ``derived_equal_weight`` 是由成分名单推出的等权，
     不是供应商权重。
 
     :param order_book_id: 主题代码，如 ``"885311.THS"``

{libfinance-0.1.1 → libfinance-0.1.2}/libfinance/subscribe/md_protocol.py

@@ -147,7 +147,7 @@ class InstrumentType(IntEnum):
     CryptoUFuture = 11
 
 
-# 交易所标识：全系统统一 rqdata 风格（order_book_id 后缀）。
+# 交易所标识：全系统统一用 order_book_id 的后缀。
 EXCHANGE_OF_MARKET = {
     MarketType.SSE: "XSHG",
     MarketType.SZE: "XSHE",
@@ -185,7 +185,7 @@ class _Coded:
 
     @property
     def order_book_id(self) -> str:
-        """rqdata 风格标识，如 600519.XSHG。"""
+        """order_book_id，如 600519.XSHG。"""
         return "{}.{}".format(self.instrument_id, self.exchange_id) if self.instrument_id else ""
 
 

{libfinance-0.1.1 → libfinance-0.1.2}/libfinance/subscribe/quote_api.py

@@ -20,7 +20,7 @@ quote_api.py — dynamics 实时行情订阅（纯 Python，XTP 风格，协议
 也可以 `login(token)` / `login(provider)` 自己提供票据，或 `connect("host:port,host:port")` 指定网关地址。
 
 代码是 libfinance 统一的 order_book_id（``600519.XSHG``），与 get_price、instruments 等函数同一种写法；
-一次订阅可混合交易所。后缀即交易所（rqdata 风格）：XSHG(上交所) / XSHE(深交所) / XBSE(北交所) 及期货交易所，
+一次订阅可混合交易所。后缀即交易所（order_book_id 的后缀）：XSHG(上交所) / XSHE(深交所) / XBSE(北交所) 及期货交易所，
 如 000001.XSHG 是上证指数、000001.XSHE 是平安银行。行情、回执与缺口通知都带 ``order_book_id``。
 
 断线自愈（7×24）：连接断开后自动重连（多个网关地址时立即切到下一个），自动重新登录，并按 seq

{libfinance-0.1.1 → libfinance-0.1.2}/libfinance/utils/cache.py

@@ -159,3 +159,19 @@ def warn_if_clamped(api_name, start_date):
         stacklevel=3,
     )
     return boundary
+
+
+def warn_if_truncated(api_name, count):
+    """当前权限一次只查前 max_count 个代码时给一句警告（服务端截断，不报错）。返回上限，没有限制则返回 None。"""
+    import warnings
+
+    limit = (limits_for(api_name) or {}).get("clamp_instrument_count") or {}
+    max_count = limit.get("max_count")
+    if not isinstance(max_count, int) or max_count <= 0 or count <= max_count:
+        return None
+    warnings.warn(
+        "{}: 当前权限一次最多 {} 个代码，传入的 {} 个只有前 {} 个会被查询；请分批调用。"
+        .format(api_name, max_count, count, max_count),
+        stacklevel=3,
+    )
+    return max_count

{libfinance-0.1.1 → libfinance-0.1.2}/libfinance.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libfinance
-Version: 0.1.1
+Version: 0.1.2
 Summary: libfinance is a modern finance API
 Description-Content-Type: text/markdown
 Requires-Dist: lz4
@@ -122,10 +122,11 @@ get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体
 | 分红 / 拆股 / 配股 | CN · US | `get_dividends` | 除权事件，价格跳空的来源 |
 | 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
 | 财务报表（PIT） | CN | `get_pit_financials_ex` | 按季度取，带修订历史 |
-| 财务衍生指标 | CN、US | `get_financial_metrics` | 按交易日的财务衍生指标（RQData get_factor 同形） |
+| 财务衍生指标 | 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` | 同花顺概念分类 |
+| 概念板块成分 | CN | `get_concept_weights` | THS 概念分类 |
 | 实时行情 | CN | `QuoteApi` | 订阅推送 |
 
 覆盖到哪一年、更新到哪一天，取决于你连的那个服务。**不要照抄文档里的日期**，用[数据新鲜度](https://libfinance.readthedocs.io/zh-cn/latest/data/freshness.html)里的两个函数自己查。
@@ -163,7 +164,7 @@ API 参考按合约信息和交易日历、行情信息、基本面信息、行
 | 目录 | 内容 |
 | --- | --- |
 | `contract/` | 各语言客户端共同遵守的契约：公开函数（名称、参数顺序与默认值、返回）与它们调用的服务端函数 |
+| `contract/conformance/` | 同一组调用分别经 Python 与 C++ 客户端发给同一个服务端，逐项比对答案 |
 | `python/` | Python 客户端（PyPI 上的 `libfinance`） |
 | `cpp/` | C++ 客户端 |
-| `conformance/` | 同一组调用分别经 Python 与 C++ 客户端发给同一个服务端，逐项比对答案 |
 | `docs/` | 文档（中英双语） |

{libfinance-0.1.1 → libfinance-0.1.2}/libfinance.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ libfinance/api/__init__.py
 libfinance/api/calendar.py
 libfinance/api/corporate_actions.py
 libfinance/api/exfactor.py
+libfinance/api/factors.py
 libfinance/api/financials.py
 libfinance/api/get_price.py
 libfinance/api/index_components.py

{libfinance-0.1.1 → libfinance-0.1.2}/test/test_client_api_contract.py

@@ -213,6 +213,10 @@ def test_all_instruments_takes_the_backend_types_and_sources(monkeypatch):
     ("get_financial_metrics", {"order_book_ids": "600000.XSHG", "fields": "roe_lf",
       "start_date": "2024-11-01", "end_date": 20241105},
      {"order_book_ids": ["600000.XSHG"], "fields": ["roe_lf"], "start_date": "2024-11-01", "end_date": "2024-11-05"}),
+    ("get_factor_exposure", {"order_book_ids": "600000.XSHG", "factor_names": "system/barra-cne5",
+      "start_date": "2026-09-01", "end_date": 20260910},
+     {"order_book_ids": ["600000.XSHG"], "factor_names": ["system/barra-cne5"], "start_date": "2026-09-01",
+      "end_date": "2026-09-10", "universe": None}),
     ("get_instrument_industry", {"order_book_ids": ["600000.XSHG"], "level": 3, "as_of": "2024-06-28"},
      {"order_book_ids": ["600000.XSHG"], "level": 3, "as_of": "2024-06-28"}),
     ("get_instrument_indices", {"order_book_ids": "600000.XSHG", "source": "CSI"},
@@ -350,8 +354,8 @@ def test_as_of_keeps_a_timestamp(monkeypatch):
 
 
 
-def test_financial_frames_get_rqdatas_index_whichever_server_answers(monkeypatch):
-    """The C++ server answers flat tables; the client indexes them as RQData does."""
+def test_financial_frames_are_indexed_whichever_server_answers(monkeypatch):
+    """The C++ server answers flat tables; the client indexes them by (order_book_id, date | quarter)."""
     import pandas as pd
     from libfinance.api import financials
 
@@ -369,3 +373,53 @@ def test_financial_frames_get_rqdatas_index_whichever_server_answers(monkeypatch
     assert metrics.index.names == ["order_book_id", "date"] and list(metrics.roe_lf) == [0.1, 0.2]
     pit = financials.get_pit_financials_ex("A", "assets", "2024q1", "2024q1")
     assert pit.index.names == ["order_book_id", "quarter"] and list(pit.columns) == ["info_date", "assets", "if_adjusted"]
+
+
+def test_factor_exposure_is_indexed_and_says_when_the_tier_cuts_it(monkeypatch):
+    """服务端回扁平表；客户端按 (order_book_id, date) 建索引、保持服务端的行序。免费层夹日期窗口、截断代码数时
+    服务端不报错，客户端各给一句警告——否则"没数据"和"档位不够"分不出来。"""
+    import pandas as pd
+    from libfinance.api import factors
+    from libfinance.utils import cache
+
+    calls = []
+
+    class Client:
+        def get_factor_exposure(self, **kwargs):
+            calls.append(kwargs)
+            return pd.DataFrame([{"order_book_id": "B", "date": "2026-09-10", "system/barra-cne5/SIZE": 1.4},
+                                 {"order_book_id": "A", "date": "2026-09-10", "system/barra-cne5/SIZE": 1.5}])
+
+    monkeypatch.setattr(factors, "get_client", lambda: Client())
+    monkeypatch.setattr(cache, "limits_for", lambda api: {"clamp_date_window": {"years": 1},
+                                                          "clamp_instrument_count": {"max_count": 2}})
+    with pytest.warns(UserWarning) as caught:
+        frame = factors.get_factor_exposure(["B", "A", "C"], ["system/barra-cne5"], "2000-01-04", "2026-09-10",
+                                            universe=["A", "B", "C"])
+    messages = [str(w.message) for w in caught]
+    assert any("可查区间的起点" in m for m in messages) and any("最多 2 个代码" in m for m in messages)
+    assert calls[0]["universe"] == ["A", "B", "C"]
+    assert frame.index.names == ["order_book_id", "date"]
+    assert list(frame.index.get_level_values(0)) == ["B", "A"]
+    assert list(frame.columns) == ["system/barra-cne5/SIZE"]
+    with pytest.raises(ValueError, match="after end_date"):
+        factors.get_factor_exposure("A", "system/qlib", "2026-09-10", "2026-09-01")
+    with pytest.raises(ValueError, match="factor_names"):
+        factors.get_factor_exposure("A", [], "2026-09-10", "2026-09-10")
+
+
+def test_factor_listings(monkeypatch):
+    from libfinance.api import factors
+
+    class Client:
+        def list_factor_libraries(self):
+            return [{"name": "system/barra-cne5", "version": "v2.0.0", "factors": 42, "description": ""}]
+
+        def list_factors(self, library=None):
+            return ["system/barra-cne5/SIZE"] if library == "system/barra-cne5" else []
+
+    monkeypatch.setattr(factors, "get_client", lambda: Client())
+    libraries = factors.list_factor_libraries()
+    assert list(libraries.columns) == ["name", "version", "factors", "description"]
+    assert libraries.factors.tolist() == [42]
+    assert factors.list_factors("system/barra-cne5") == ["system/barra-cne5/SIZE"]

libfinance-0.1.1/VERSION

@@ -1 +0,0 @@
-0.1.1