hamuna-quant-cli 0.1.0.dev93__py3-none-any.whl

hamuna_quant_cli/live/loader.py

@@ -0,0 +1,121 @@
+"""hamuna_quant_cli.live.loader — strategy.py 加载 + 校验.
+
+可独立跑 (`python -m hamuna_quant_cli.live.loader --help` 不强依赖 akquant).
+"""
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import sys
+import types
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+
+# 策略可识别的函数式回调名 (functional mode) — 顺序无意义, 仅做存在性检查
+FUNCTIONAL_HOOKS = ("initialize", "on_bar", "on_order", "on_trade", "on_timer", "on_broker_connected")
+
+
+class StrategyLoadError(Exception):
+    """strategy.py 加载 / 校验失败."""
+
+
+@dataclass
+class StrategySpec:
+    mode: Literal["class", "functional"]
+    # class mode
+    strategy_cls: type | None = None
+    # functional mode
+    callbacks: dict[str, Any] | None = None
+    module: types.ModuleType | None = None  # 留着, 后续 run_live 之外的扩展用
+
+
+def _import_strategy_module(path: Path) -> types.ModuleType:
+    """用 importlib 加载 strategy.py (不污染 sys.modules)."""
+    if not path.is_file():
+        raise StrategyLoadError(f"策略文件不存在: {path}")
+    spec = importlib.util.spec_from_file_location(f"_hamuna_strategy_user_{path.stem}", path)
+    if spec is None or spec.loader is None:
+        raise StrategyLoadError(f"无法构造 import spec: {path}")
+    module = importlib.util.module_from_spec(spec)
+    # 用户顶层副作用 (网络请求/重 I/O) 应当避免 — 不在 loader 责任范围, 透传即可
+    try:
+        spec.loader.exec_module(module)
+    except Exception as e:
+        raise StrategyLoadError(f"strategy.py 顶层执行失败: {type(e).__name__}: {e}") from e
+    return module
+
+
+def _is_akquant_strategy_subclass(obj: Any) -> bool:
+    """宽松判定: 类是否继承自 akquant.Strategy.
+
+    用 duck typing 而不是直接 import akquant.Strategy 比较 — loader 必须能在
+    akquant 未装的环境跑通 (CI / stub 测试). 走 duck check: 类必须有 on_bar /
+    buy / sell 等 akquant 协议方法, 且其 MRO 中有 'Strategy' 这个名字.
+    """
+    if not inspect.isclass(obj):
+        return False
+    # MRO 中存在名为 'Strategy' 的基类 — 适配 `from akquant import Strategy` 与
+    # `import akquant; class X(akquant.Strategy)` 两种写法
+    has_strategy_base = any(base.__name__ == "Strategy" for base in obj.__mro__)
+    if not has_strategy_base:
+        return False
+    # duck check: 必须有协议方法 on_bar
+    return hasattr(obj, "on_bar") and callable(getattr(obj, "on_bar"))
+
+
+def load_strategy(path: Path, class_name: str = "Strategy") -> StrategySpec:
+    """加载 strategy.py → StrategySpec.
+
+    class_name: class mode 模式下优先要找的策略类名 (默认 `Strategy`).
+    优先 class mode; 若找不到目标类, fallback 到 functional mode (顶层函数 hook).
+    """
+    module = _import_strategy_module(path)
+
+    # —— class mode ——
+    # 找【模块内定义】的 akquant.Strategy 子类。老逻辑 getattr(module, 'Strategy')
+    # 会命中 `from akquant import Strategy` 挂到模块命名空间的【基类本身】
+    # (所有模板都这么写) → 用户类从来没被加载过, on_bar 全走基类空实现
+    # (2026-08-19 实测: live run 0 trades + compute_factors 检测恒 False)。
+    # 判定: __module__ == 用户模块名 (排除 akquant / 其它 import 的类)。
+    cls = None
+    if class_name:
+        cand = getattr(module, class_name, None)
+        if (cand is not None and _is_akquant_strategy_subclass(cand)
+                and getattr(cand, "__module__", None) == module.__name__):
+            cls = cand
+    if cls is None:
+        for name, obj in vars(module).items():
+            if (not name.startswith("_")
+                    and _is_akquant_strategy_subclass(obj)
+                    and getattr(obj, "__module__", None) == module.__name__):
+                cls = obj
+                break
+    if cls is not None:
+        return StrategySpec(mode="class", strategy_cls=cls, module=module)
+
+    # —— functional mode ——
+    callbacks: dict[str, Any] = {}
+    for hook in FUNCTIONAL_HOOKS:
+        fn = getattr(module, hook, None)
+        if fn is not None and callable(fn):
+            callbacks[hook] = fn
+
+    if not callbacks:
+        # 既找不到 class 也没找到函数式 hook — 列文件里有什么帮用户排错
+        declared = [n for n, o in vars(module).items() if not n.startswith("_") and (inspect.isclass(o) or callable(o))]
+        hint = f"文件里看到: {', '.join(declared[:8])}" if declared else "文件为空或全以下划线开头"
+        raise StrategyLoadError(
+            f"{path}: 未找到合法 strategy.\n"
+            f"  · class mode:    类 `{class_name}(akquant.Strategy)` 不存在或不是 akquant.Strategy 子类\n"
+            f"  · functional mode: 顶层函数 {', '.join(FUNCTIONAL_HOOKS)} 一个都没找到\n"
+            f"  · {hint}"
+        )
+
+    if "on_bar" not in callbacks:
+        raise StrategyLoadError(
+            f"{path}: functional mode 缺少 `on_bar(ctx, bar)` — akquant.run_live 必须有它"
+        )
+
+    return StrategySpec(mode="functional", callbacks=callbacks, module=module)