xtquant-share 1.2.41__tar.gz → 1.3.1__tar.gz

{xtquant_share-1.2.41/xtquant_share.egg-info → xtquant_share-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtquant-share
-Version: 1.2.41
+Version: 1.3.1
 Summary: Xtreme Quant Share - eXtreme transparent sharing proxy for XtQuant on macOS/Linux
 Author-email: Jason Hu <63170682@qq.com>
 License-Expression: GPL-3.0-only
@@ -28,12 +28,16 @@ License-File: LICENSE
 Requires-Dist: rpyc>=6.0
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: psutil>=5.9
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: black>=23.0; extra == "dev"
 Requires-Dist: flake8>=6.0; extra == "dev"
 Provides-Extra: datadir
 Requires-Dist: pandas>=1.0; extra == "datadir"
+Requires-Dist: pyarrow>=6.0; extra == "datadir"
+Provides-Extra: bigqmt
+Requires-Dist: xtquant-big-convert[redis]; extra == "bigqmt"
 Dynamic: license-file
 
 # 极限量化 (xqshare)
@@ -47,6 +51,7 @@ Dynamic: license-file
 - ✅ **断线重连** - 自动检测断线并重连，指数退避策略
 - ✅ **心跳保活** - 定期心跳检测，保持连接活跃
 - ✅ **异步回调** - 支持交易事件（on_stock_*）与行情 tick 订阅回调（`xtdata.register_quote_callback` + `subscribe_whole_quote`）
+- ✅ **无感切换** - 大QMT ↔ miniQMT 无感切换（行情侧），自动探测 miniQMT 可用性，不可用自动切 bigqmt 通道（复用 xtquant_big_convert）
 - ✅ **完整日志** - API调用日志，记录函数名、参数、耗时
 - ✅ **零学习成本** - 无需记忆新 API
 
@@ -90,6 +95,8 @@ pip install -e .
 pip install rpyc
 ```
 
+> **datadir 文件解析功能**需要额外依赖：`pip install "xqshare[datadir]"`（含 `pandas` + `pyarrow`，其中 `pyarrow` 用于因子库 feather 文件解析）。
+
 ## 快速启动
 
 ### 启动前准备
@@ -316,6 +323,17 @@ with XtQuantRemote("21.214.136.216", client_secret="my-secret") as xt:
     # 获取单个板块成分股
     bank_stocks = xt.datadir.sector("申万行业", "SW1银行")
     print(f"银行板块：{len(bank_stocks)} 只")
+
+    # 列出可用因子表
+    classes = xt.datadir.factor_classes()  # ['factor_growth', 'factor_metrics', ...]
+
+    # 读取因子库数据（feather 文件，需服务端装 pyarrow）
+    factor_df = xt.datadir.factors(
+        "factor_growth",
+        symbols=["600000.SH"],
+        start_date="20240101",
+        end_date="20241231",
+    )
 ```
 
 ### 全局便捷方式
@@ -338,6 +356,7 @@ df = xqshare.datadir.kline("600000.SH", "1d")
 | 支持实时行情 | ✅ 支持 | ❌ 不支持 |
 | 支持历史 K 线 | ✅ 支持 | ✅ 支持 |
 | 支持板块成分股 | ✅ 支持 | ✅ 支持 |
+| 支持因子库 | 在线接口 | ✅ 支持（feather 解析，需 `pyarrow`） |
 | 适用场景 | 实时/在线场景 | 离线/备用/批量场景 |
 
 ### datadir 不可用时的处理
@@ -503,6 +522,36 @@ xt = XtQuantRemote("21.214.136.216", log_level="DEBUG")
 | --key | SSL 私钥文件 | - |
 | --log-level | 日志级别 | INFO |
 
+### 下载超时
+
+盘后券商（如平安 QMT）挂起时，`download_*` 类调用会在服务端永久阻塞 worker 线程，
+堵死后续所有下载请求。服务端对下载类调用统一加了超时隔离（独立 daemon 线程 + 超时等待），
+超过阈值后放弃等待并抛 `TimeoutError`，避免挂起堵死后续请求。
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `XQSHARE_DOWNLOAD_TIMEOUT` | `600` | `download_*` 调用超时阈值（秒） |
+
+> 注意：超时后底层 xtquant C 库调用无法被 Python 强制中断，挂起的 daemon 线程会残留，
+> 直到 QMT/xqshare 进程重启才回收。详见 [doc/download-timeout-gap.md](doc/download-timeout-gap.md)。
+
+### 通道切换（大QMT ↔ miniQMT 无感切换）
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `XQSHARE_BIGQMT_ENABLED` | `false` | 是否启用 bigqmt 通道（mini 不可用时的路由候选） |
+| `XQSHARE_BIGQMT_ALLOW_ORDER` | `false` | 是否允许 bigqmt 通道下单（双重门禁之一） |
+| `XQSHARE_FORCE_CHANNEL` | 空 | 强制通道：空=自动探测，可选 `mini` / `bigqmt` |
+| `XQSHARE_PROBE_INTERVAL` | `30` | 健康探测间隔（秒） |
+| `BIGQMT_ACCOUNT_ID` | — | 大QMT 资金账号（透传给 bigqmt 桥接） |
+| `BIGQMT_REDIS_HOST` | — | Redis 主机 |
+| `BIGQMT_REDIS_PORT` | — | Redis 端口 |
+| `BIGQMT_REDIS_DB` | — | Redis DB 编号 |
+| `BIGQMT_REDIS_PASSWORD` | — | Redis 密码（可选） |
+| `BIGQMT_REDIS_USERNAME` | — | Redis 用户名（可选） |
+
+> 通道抽象层设计见 [doc/channel-abstraction.md](doc/channel-abstraction.md)，大QMT 端部署见 [doc/bigqmt-bridge-deploy.md](doc/bigqmt-bridge-deploy.md)。
+
 ---
 
 ## 认证机制

{xtquant_share-1.2.41 → xtquant_share-1.3.1}/README.md

@@ -9,6 +9,7 @@
 - ✅ **断线重连** - 自动检测断线并重连，指数退避策略
 - ✅ **心跳保活** - 定期心跳检测，保持连接活跃
 - ✅ **异步回调** - 支持交易事件（on_stock_*）与行情 tick 订阅回调（`xtdata.register_quote_callback` + `subscribe_whole_quote`）
+- ✅ **无感切换** - 大QMT ↔ miniQMT 无感切换（行情侧），自动探测 miniQMT 可用性，不可用自动切 bigqmt 通道（复用 xtquant_big_convert）
 - ✅ **完整日志** - API调用日志，记录函数名、参数、耗时
 - ✅ **零学习成本** - 无需记忆新 API
 
@@ -52,6 +53,8 @@ pip install -e .
 pip install rpyc
 ```
 
+> **datadir 文件解析功能**需要额外依赖：`pip install "xqshare[datadir]"`（含 `pandas` + `pyarrow`，其中 `pyarrow` 用于因子库 feather 文件解析）。
+
 ## 快速启动
 
 ### 启动前准备
@@ -278,6 +281,17 @@ with XtQuantRemote("21.214.136.216", client_secret="my-secret") as xt:
     # 获取单个板块成分股
     bank_stocks = xt.datadir.sector("申万行业", "SW1银行")
     print(f"银行板块：{len(bank_stocks)} 只")
+
+    # 列出可用因子表
+    classes = xt.datadir.factor_classes()  # ['factor_growth', 'factor_metrics', ...]
+
+    # 读取因子库数据（feather 文件，需服务端装 pyarrow）
+    factor_df = xt.datadir.factors(
+        "factor_growth",
+        symbols=["600000.SH"],
+        start_date="20240101",
+        end_date="20241231",
+    )
 ```
 
 ### 全局便捷方式
@@ -300,6 +314,7 @@ df = xqshare.datadir.kline("600000.SH", "1d")
 | 支持实时行情 | ✅ 支持 | ❌ 不支持 |
 | 支持历史 K 线 | ✅ 支持 | ✅ 支持 |
 | 支持板块成分股 | ✅ 支持 | ✅ 支持 |
+| 支持因子库 | 在线接口 | ✅ 支持（feather 解析，需 `pyarrow`） |
 | 适用场景 | 实时/在线场景 | 离线/备用/批量场景 |
 
 ### datadir 不可用时的处理
@@ -465,6 +480,36 @@ xt = XtQuantRemote("21.214.136.216", log_level="DEBUG")
 | --key | SSL 私钥文件 | - |
 | --log-level | 日志级别 | INFO |
 
+### 下载超时
+
+盘后券商（如平安 QMT）挂起时，`download_*` 类调用会在服务端永久阻塞 worker 线程，
+堵死后续所有下载请求。服务端对下载类调用统一加了超时隔离（独立 daemon 线程 + 超时等待），
+超过阈值后放弃等待并抛 `TimeoutError`，避免挂起堵死后续请求。
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `XQSHARE_DOWNLOAD_TIMEOUT` | `600` | `download_*` 调用超时阈值（秒） |
+
+> 注意：超时后底层 xtquant C 库调用无法被 Python 强制中断，挂起的 daemon 线程会残留，
+> 直到 QMT/xqshare 进程重启才回收。详见 [doc/download-timeout-gap.md](doc/download-timeout-gap.md)。
+
+### 通道切换（大QMT ↔ miniQMT 无感切换）
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `XQSHARE_BIGQMT_ENABLED` | `false` | 是否启用 bigqmt 通道（mini 不可用时的路由候选） |
+| `XQSHARE_BIGQMT_ALLOW_ORDER` | `false` | 是否允许 bigqmt 通道下单（双重门禁之一） |
+| `XQSHARE_FORCE_CHANNEL` | 空 | 强制通道：空=自动探测，可选 `mini` / `bigqmt` |
+| `XQSHARE_PROBE_INTERVAL` | `30` | 健康探测间隔（秒） |
+| `BIGQMT_ACCOUNT_ID` | — | 大QMT 资金账号（透传给 bigqmt 桥接） |
+| `BIGQMT_REDIS_HOST` | — | Redis 主机 |
+| `BIGQMT_REDIS_PORT` | — | Redis 端口 |
+| `BIGQMT_REDIS_DB` | — | Redis DB 编号 |
+| `BIGQMT_REDIS_PASSWORD` | — | Redis 密码（可选） |
+| `BIGQMT_REDIS_USERNAME` | — | Redis 用户名（可选） |
+
+> 通道抽象层设计见 [doc/channel-abstraction.md](doc/channel-abstraction.md)，大QMT 端部署见 [doc/bigqmt-bridge-deploy.md](doc/bigqmt-bridge-deploy.md)。
+
 ---
 
 ## 认证机制

{xtquant_share-1.2.41 → xtquant_share-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xtquant-share"
-version = "1.2.41"
+version = "1.3.1"
 description = "Xtreme Quant Share - eXtreme transparent sharing proxy for XtQuant on macOS/Linux"
 readme = "README.md"
 license = "GPL-3.0-only"
@@ -42,6 +42,7 @@ dependencies = [
     "rpyc>=6.0",
     "python-dotenv>=1.0",
     "pyyaml>=6.0",
+    "psutil>=5.9",
 ]
 
 [project.optional-dependencies]
@@ -52,6 +53,10 @@ dev = [
 ]
 datadir = [
     "pandas>=1.0",
+    "pyarrow>=6.0",
+]
+bigqmt = [
+    "xtquant-big-convert[redis]",
 ]
 
 [project.scripts]

xtquant_share-1.3.1/tests/test_channels_bigqmt.py

@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+"""大QMT 通道封装（bigqmt.py）单元测试：回调适配 + 下单闸门。"""
+import pytest
+
+from xqshare.channels.bigqmt import (
+    BIGQMT_AVAILABLE,
+    BigQmtCallbackAdapter,
+    BigQmtChannel,
+    _GuardedTrader,
+    _SyntheticEvent,
+    order_allowed,
+)
+
+
+class TestOrderAllowed:
+    def test_default_false(self, monkeypatch):
+        monkeypatch.delenv("XQSHARE_BIGQMT_ALLOW_ORDER", raising=False)
+        assert order_allowed() is False
+
+    def test_true(self, monkeypatch):
+        monkeypatch.setenv("XQSHARE_BIGQMT_ALLOW_ORDER", "true")
+        assert order_allowed() is True
+
+
+class TestGuardedTrader:
+    def test_read_passthrough(self):
+        trader = _SyntheticEvent(query_stock_asset=lambda acc: "asset")
+        guarded = _GuardedTrader(trader)
+        assert guarded.query_stock_asset("acc") == "asset"
+
+    def test_write_blocked_when_disallowed(self, monkeypatch):
+        monkeypatch.setenv("XQSHARE_BIGQMT_ALLOW_ORDER", "false")
+        trader = _SyntheticEvent()
+        guarded = _GuardedTrader(trader)
+        with pytest.raises(RuntimeError):
+            guarded.order_stock("acc", "600000.SH", 23, 100, 11, 10.0, "s", "r")
+
+    def test_cancel_blocked_when_disallowed(self, monkeypatch):
+        monkeypatch.setenv("XQSHARE_BIGQMT_ALLOW_ORDER", "false")
+        trader = _SyntheticEvent()
+        guarded = _GuardedTrader(trader)
+        with pytest.raises(RuntimeError):
+            guarded.cancel_order_stock("acc", "SYS1")
+
+    def test_write_allowed_when_enabled(self, monkeypatch):
+        monkeypatch.setenv("XQSHARE_BIGQMT_ALLOW_ORDER", "true")
+        trader = _SyntheticEvent(order_stock=lambda *a, **k: "orderid")
+        guarded = _GuardedTrader(trader)
+        assert guarded.order_stock("acc", "600000.SH", 23, 100, 11, 10.0, "s", "r") == "orderid"
+
+
+class TestCallbackAdapter:
+    def _make(self):
+        from unittest.mock import MagicMock
+        server_cb = MagicMock()
+        adapter = BigQmtCallbackAdapter(server_cb, account_id="ACC123")
+        return adapter, server_cb
+
+    def test_on_stock_order_passthrough(self):
+        adapter, server_cb = self._make()
+        order = _SyntheticEvent(account_id="ACC123", stock_code="600000.SH")
+        adapter.on_stock_order(order)
+        server_cb.on_stock_order.assert_called_once_with(order)
+
+    def test_on_stock_trade_passthrough(self):
+        adapter, server_cb = self._make()
+        trade = _SyntheticEvent(account_id="ACC123")
+        adapter.on_stock_trade(trade)
+        server_cb.on_stock_trade.assert_called_once_with(trade)
+
+    def test_on_order_error_synthesizes_junk_order(self):
+        adapter, server_cb = self._make()
+        err = _SyntheticEvent(
+            stock_code="600000.SH", order_sysid="SYS1", order_id="SYS1",
+            strategy_name="s", order_remark="r", error_msg="拒单",
+        )
+        adapter.on_order_error(err)
+        server_cb.on_stock_order.assert_called_once()
+        order = server_cb.on_stock_order.call_args[0][0]
+        assert order.account_id == "ACC123"
+        assert order.stock_code == "600000.SH"
+        assert order.order_status == 57
+        assert order.status_msg == "拒单"
+
+    def test_on_cancel_error_synthesizes_junk_order(self):
+        adapter, server_cb = self._make()
+        err = _SyntheticEvent(order_sysid="SYS2", error_msg="撤单被拒")
+        adapter.on_cancel_error(err)
+        server_cb.on_stock_order.assert_called_once()
+        order = server_cb.on_stock_order.call_args[0][0]
+        assert order.order_status == 57
+        assert "撤单失败" in order.status_msg
+
+    def test_on_account_status_not_forwarded(self):
+        adapter, server_cb = self._make()
+        adapter.on_account_status(_SyntheticEvent(account_id="ACC123", status=1))
+        server_cb.on_stock_order.assert_not_called()
+        server_cb.on_stock_trade.assert_not_called()
+
+    def test_on_async_response_not_forwarded(self):
+        adapter, server_cb = self._make()
+        adapter.on_order_stock_async_response(_SyntheticEvent(seq=1))
+        server_cb.on_stock_order.assert_not_called()
+
+
+class TestBigQmtChannel:
+    def test_enabled_false_when_lib_missing(self, monkeypatch):
+        monkeypatch.setenv("XQSHARE_BIGQMT_ENABLED", "true")
+        if BIGQMT_AVAILABLE:
+            pytest.skip("xtquant_big_convert 已安装，跳过未安装场景")
+        assert BigQmtChannel.enabled() is False
+
+    def test_enabled_requires_flag(self, monkeypatch):
+        monkeypatch.delenv("XQSHARE_BIGQMT_ENABLED", raising=False)
+        assert BigQmtChannel.enabled() is False
+
+    def test_data_source_none_when_disabled(self, monkeypatch):
+        monkeypatch.delenv("XQSHARE_BIGQMT_ENABLED", raising=False)
+        assert BigQmtChannel.data_source() is None
+
+    def test_ping_false_when_disabled(self, monkeypatch):
+        monkeypatch.delenv("XQSHARE_BIGQMT_ENABLED", raising=False)
+        assert BigQmtChannel.ping() is False
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

xtquant_share-1.3.1/tests/test_channels_health.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""通道健康探测（health.py）单元测试。"""
+import pytest
+
+from xqshare.channels.health import ChannelHealth, HealthProbe
+
+
+class TestChannelHealth:
+    def test_mode_mini_priority(self):
+        h = ChannelHealth(mini_available=True, bigqmt_available=True)
+        assert h.mode == "mini"
+
+    def test_mode_bigqmt(self):
+        h = ChannelHealth(mini_available=False, bigqmt_available=True)
+        assert h.mode == "bigqmt"
+
+    def test_mode_none(self):
+        h = ChannelHealth()
+        assert h.mode == "none"
+
+    def test_to_dict(self):
+        h = ChannelHealth(mini_available=True, checked_at=123.0, detail={"a": 1})
+        d = h.to_dict()
+        assert d["mode"] == "mini"
+        assert d["mini_available"] is True
+        assert d["bigqmt_available"] is False
+        assert d["checked_at"] == 123.0
+        assert d["detail"] == {"a": 1}
+
+
+class TestHealthProbe:
+    def test_probe_delegates(self):
+        probe = HealthProbe(
+            mini_probe_func=lambda: True,
+            bigqmt_probe_func=lambda: False,
+        )
+        h = probe.probe()
+        assert h.mini_available is True
+        assert h.bigqmt_available is False
+        assert h.mode == "mini"
+        assert h.checked_at > 0
+
+    def test_probe_exception_swallowed(self):
+        def boom():
+            raise RuntimeError("probe failed")
+
+        probe = HealthProbe(mini_probe_func=boom, bigqmt_probe_func=lambda: False)
+        h = probe.probe()
+        assert h.mini_available is False
+        assert h.mode == "none"
+
+    def test_probe_both_true_mode_mini(self):
+        probe = HealthProbe(
+            mini_probe_func=lambda: True,
+            bigqmt_probe_func=lambda: True,
+        )
+        h = probe.probe()
+        assert h.mini_available is True
+        assert h.bigqmt_available is True
+        assert h.mode == "mini"  # mini 优先
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

xtquant_share-1.3.1/tests/test_channels_router.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+"""通道路由（router.py）单元测试：抖动保护 + 路由决策 + 强制通道。"""
+import pytest
+
+from xqshare.channels.health import ChannelHealth, HealthProbe
+from xqshare.channels.router import ChannelRouter
+
+
+class FakeProbe:
+    """按队列顺序返回预设探测结果。"""
+
+    def __init__(self, results):
+        self._results = list(results)
+
+    def probe(self):
+        return self._results.pop(0)
+
+
+def _health(mini, bigqmt):
+    return ChannelHealth(mini_available=mini, bigqmt_available=bigqmt, checked_at=1.0)
+
+
+class TestJitterProtection:
+    def test_switch_after_threshold(self):
+        router = ChannelRouter(
+            probe=FakeProbe([_health(False, True), _health(False, True)]),
+            switch_threshold=2,
+        )
+        router._probe_once()
+        assert router.snapshot()["mode"] == "mini"  # 第一次，未达阈值
+        router._probe_once()
+        assert router.snapshot()["mode"] == "bigqmt"  # 第二次，切换
+
+    def test_no_switch_on_single_flap(self):
+        router = ChannelRouter(
+            probe=FakeProbe([_health(False, True), _health(True, False)]),
+            switch_threshold=2,
+        )
+        router._probe_once()
+        router._probe_once()
+        assert router.snapshot()["mode"] == "mini"  # 抖动，未切换
+
+    def test_switch_back(self):
+        router = ChannelRouter(
+            probe=FakeProbe([
+                _health(False, True), _health(False, True),  # mini -> bigqmt
+                _health(True, False), _health(True, False),  # bigqmt -> mini
+            ]),
+            switch_threshold=2,
+        )
+        router._probe_once()
+        router._probe_once()
+        assert router.snapshot()["mode"] == "bigqmt"
+        router._probe_once()
+        router._probe_once()
+        assert router.snapshot()["mode"] == "mini"
+
+
+class TestSnapshot:
+    def test_snapshot_structure(self):
+        router = ChannelRouter(probe=FakeProbe([_health(True, False)]), switch_threshold=1)
+        router._probe_once()
+        snap = router.snapshot()
+        assert set(snap.keys()) == {
+            "mode", "mini_available", "bigqmt_available", "checked_at", "detail",
+        }
+        assert snap["mode"] == "mini"
+        assert snap["mini_available"] is True
+
+
+class TestTraderMode:
+    def test_trader_mode_follows_current_mode(self):
+        router = ChannelRouter(
+            probe=FakeProbe([_health(False, True), _health(False, True)]),
+            switch_threshold=2,
+        )
+        router._probe_once()
+        router._probe_once()
+        assert router.trader_mode() == "bigqmt"
+
+    def test_trader_mode_default_mini(self):
+        router = ChannelRouter(probe=FakeProbe([_health(False, False)]), switch_threshold=1)
+        router._probe_once()
+        assert router.trader_mode() == "mini"  # 双通道不可用回落 mini
+
+
+class TestForceChannel:
+    def test_force_bigqmt_trader_mode(self, monkeypatch):
+        monkeypatch.setenv("XQSHARE_FORCE_CHANNEL", "bigqmt")
+        router = ChannelRouter(probe=FakeProbe([_health(True, False)]), switch_threshold=1)
+        router._probe_once()
+        assert router.trader_mode() == "bigqmt"
+
+    def test_force_mini_trader_mode(self, monkeypatch):
+        monkeypatch.setenv("XQSHARE_FORCE_CHANNEL", "mini")
+        router = ChannelRouter(probe=FakeProbe([_health(False, True)]), switch_threshold=1)
+        router._probe_once()
+        assert router.trader_mode() == "mini"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

xtquant_share-1.3.1/tests/test_qmt_datadir_factor.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+"""qmt_datadir 因子库（factor.py）单元测试。"""
+import os
+
+import pandas as pd
+import pytest
+
+pyarrow = pytest.importorskip("pyarrow")
+import pyarrow as pa
+import pyarrow.feather as feather
+
+from xqshare.qmt_datadir import (
+    QmtDataReader,
+    read_factor,
+    list_factor_classes,
+)
+
+# 2024-01-01 / 2024-01-02 / 2024-01-03 的毫秒时间戳（UTC）
+_TS = {
+    '20240101': 1704067200000,
+    '20240102': 1704153600000,
+    '20240103': 1704240000000,
+}
+
+
+def _write_feather(path, times_ms, stocks, values):
+    table = pa.table({
+        '_time':  pa.array(times_ms, type=pa.int64()),
+        '_stock': pa.array(stocks, type=pa.string()),
+        'value':  pa.array(values, type=pa.float64()),
+    })
+    feather.write_feather(table, path)
+
+
+def _make_datadir(tmp_path, factor_class='factor_growth',
+                  times=None, stocks=None, values=None):
+    """构造最小 datadir：EP/{factor_class}_Xdat2/data.fe"""
+    times = times or [_TS['20240101'], _TS['20240102'], _TS['20240103']]
+    stocks = stocks or ['600000.SH', '000001.SZ', '600000.SH']
+    values = values or [1.0, 2.0, 3.0]
+    xdat2 = tmp_path / 'EP' / f'{factor_class}_Xdat2'
+    xdat2.mkdir(parents=True)
+    _write_feather(str(xdat2 / 'data.fe'), times, stocks, values)
+    return str(tmp_path)
+
+
+class TestReadFactor:
+    def test_basic_schema_normalize(self, tmp_path):
+        """_time→date、_stock→symbol 标准化，值保留"""
+        data_dir = _make_datadir(tmp_path)
+        df = read_factor(data_dir, 'factor_growth')
+        assert list(df.columns)[:2] == ['symbol', 'date']
+        assert df['symbol'].tolist() == ['600000.SH', '000001.SZ', '600000.SH']
+        assert df['value'].tolist() == [1.0, 2.0, 3.0]
+        # date 应为 datetime
+        assert pd.api.types.is_datetime64_any_dtype(df['date'])
+
+    def test_symbols_filter_full_code(self, tmp_path):
+        data_dir = _make_datadir(tmp_path)
+        df = read_factor(data_dir, 'factor_growth', symbols=['000001.SZ'])
+        assert df['symbol'].unique().tolist() == ['000001.SZ']
+
+    def test_symbols_filter_pure_code(self, tmp_path):
+        """纯 6 位代码也能匹配（兼容 600000 → 600000.SH/SZ）"""
+        data_dir = _make_datadir(tmp_path)
+        df = read_factor(data_dir, 'factor_growth', symbols=['600000'])
+        assert df['symbol'].unique().tolist() == ['600000.SH']
+
+    def test_date_filter(self, tmp_path):
+        data_dir = _make_datadir(tmp_path)
+        df = read_factor(data_dir, 'factor_growth',
+                         start_date='20240102', end_date='20240103')
+        dates = pd.to_datetime(df['date']).dt.strftime('%Y%m%d').unique().tolist()
+        assert dates == ['20240102', '20240103']
+
+    def test_missing_feather_raises(self, tmp_path):
+        """data.fe 不存在时抛 FileNotFoundError"""
+        ep = tmp_path / 'EP'
+        ep.mkdir()
+        with pytest.raises(FileNotFoundError):
+            read_factor(str(tmp_path), 'factor_growth')
+
+
+class TestListFactorClasses:
+    def test_lists_both_kinds(self, tmp_path):
+        """同时识别 _Xdat2（已下载）和 _Xdat（仅定义）"""
+        ep = tmp_path / 'EP'
+        (ep / 'factor_growth_Xdat2').mkdir(parents=True)
+        (ep / 'factor_metrics_Xdat').mkdir(parents=True)
+        classes = list_factor_classes(str(tmp_path))
+        assert classes == ['factor_growth', 'factor_metrics']
+
+    def test_empty_when_no_ep(self, tmp_path):
+        assert list_factor_classes(str(tmp_path)) == []
+
+
+class TestReaderMethods:
+    def test_reader_factors(self, tmp_path):
+        data_dir = _make_datadir(tmp_path)
+        reader = QmtDataReader(data_dir)
+        df = reader.factors('factor_growth', symbols=['000001.SZ'])
+        assert df['symbol'].unique().tolist() == ['000001.SZ']
+
+    def test_reader_factor_classes(self, tmp_path):
+        ep = tmp_path / 'EP'
+        (ep / 'beta_Xdat2').mkdir(parents=True)
+        reader = QmtDataReader(str(tmp_path))
+        assert reader.factor_classes() == ['beta']
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])