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

hamuna_quant_cli/runtime/cache.py

@@ -0,0 +1,255 @@
+"""strategy_cli.runtime.cache: 本地缓存 (ADR-015 ~/.hamuna/data_cache)。
+
+格式:
+- K 线 (大体积, 频繁): parquet
+- 其他 (基本面/股本/股东/StockCode): JSON
+
+TTL 按 endpoint 粒度; 文件 mtime 超 TTL 视为 miss。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+# 默认缓存根: ~/.hamuna/data_cache (符合 ADR-015 §303)
+_CACHE_ROOT = Path.home() / '.hamuna' / 'data_cache'
+
+# endpoint 粒度 TTL (秒)
+# K 线 = 准实时 (5min); 财务 = 当日有效 (1d); StockCode = 当日有效 (1d)
+_TTL: dict[str, int] = {
+    'StockBars':     300,        # 5 min
+    'RealTime':      60,         # 1 min
+    'StockHq':       300,
+    'StockFinancial': 86400,     # 1 day
+    'StockAnnualReport': 86400,
+    'StockQuarterlyReport': 86400,
+    'StockShareholder': 86400,
+    'StockShareCapital': 86400,
+    'StockBasicInfo': 86400,
+    'StockBond':     86400,
+    'ETFInfo':       86400,
+    'StockCode':     86400,
+}
+
+_PARQUET_ENDPOINTS = {'StockBars', 'RealTime', 'StockHq'}
+
+
+def cache_dir(endpoint: str) -> Path:
+    p = _CACHE_ROOT / endpoint
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def cache_key(params: dict[str, Any]) -> str:
+    """参数 dict → 稳定 hash (sorted keys, urlencoded-style)."""
+    items = sorted((k, str(v)) for k, v in params.items() if v is not None)
+    raw = '&'.join(f'{k}={v}' for k, v in items)
+    return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def is_fresh(path: Path, endpoint: str) -> bool:
+    if not path.exists():
+        return False
+    ttl = _TTL.get(endpoint, 3600)
+    return (time.time() - path.stat().st_mtime) < ttl
+
+
+def read(endpoint: str, params: dict[str, Any]) -> dict | list | None:
+    """命中返回解析后 dict/list; miss/过期返回 None。"""
+    key = cache_key(params)
+    if endpoint in _PARQUET_ENDPOINTS:
+        path = cache_dir(endpoint) / f'{key}.parquet'
+        if not is_fresh(path, endpoint):
+            return None
+        return _read_parquet(path)
+    path = cache_dir(endpoint) / f'{key}.json'
+    if not is_fresh(path, endpoint):
+        return None
+    with path.open(encoding='utf-8') as f:
+        return json.load(f)
+
+
+def write(endpoint: str, params: dict[str, Any], data: dict | list) -> None:
+    key = cache_key(params)
+    if endpoint in _PARQUET_ENDPOINTS and isinstance(data, list):
+        path = cache_dir(endpoint) / f'{key}.parquet'
+        _write_parquet(path, data)
+    else:
+        path = cache_dir(endpoint) / f'{key}.json'
+        path.write_text(json.dumps(data, ensure_ascii=False, indent=2),
+                        encoding='utf-8')
+
+
+def clear(endpoint: str | None = None) -> int:
+    """清除缓存; endpoint=None 清除全部。返回删除文件数。"""
+    n = 0
+    targets = [_CACHE_ROOT / endpoint] if endpoint else [_CACHE_ROOT]
+    for d in targets:
+        if not d.exists():
+            continue
+        for p in d.glob('**/*'):
+            if p.is_file():
+                p.unlink()
+                n += 1
+    return n
+
+
+# ---- 回测数据集 (无 TTL, 历史数据不变) ----
+
+# 数据集根: ~/.hamuna/data_cache/datasets/<code>_<DateType>_fq<FuQuanType>.parquet
+# 与 5min 缓存 (StockBars/<hash>.parquet) 分开 — 数据集是"回测专用完整历史",
+# 不随单次请求 TTL 过期。key 只含 (code, DateType, FuQuanType), 窗口内切片由读取方做。
+_DATASET_DIR = _CACHE_ROOT / 'datasets'
+
+# 回测数据集最小 bar 数 — 用户规约 "至少 3 年 1000 根"。A 股年约 240 交易日,
+# 3 年 ≈ 750 根, 到不了 1000; 故以 1000 根为硬门槛 (约 4.1 年), 自然覆盖 3 年。
+# 转债例外: 历史天然短 (2017 后起量, 多数上市 1-2 年), 硬套 1000 根会让几乎
+# 全部转债每次回测都重建数据集 (慢到不可用)。转债用 240 根 (约 1 年)。
+DATASET_MIN_BARS = 1000
+DATASET_MIN_BARS_CB = 240
+
+# 短样本数据集 TTL (秒): 次新股/新转债历史天然不足 DATASET_MIN_BARS, 若"不足即 miss"
+# 会导致每次回测都重建 (实测 889 只转债里 296 只 <240 根, 反复重建 ~74s)。
+# 构建过一次就临时复用, TTL 到期重建以拉取新累积的历史 — 短样本数据在上市初期
+# 会变长, 不能像达标样本那样无 TTL 永久复用。
+DATASET_SHORT_TTL = 7 * 86400  # 7 天
+
+
+def _is_convertible(stock_code: str) -> bool:
+    bare = stock_code.split('.')[0]
+    return bare.startswith(('11', '12'))
+
+
+def _min_bars(stock_code: str, date_type: str = 'D') -> int:
+    """按品种+周期取最小 bar 门槛。
+
+    分钟 (DateType M*) 不走根数门槛 — 分钟 dataset 构建目标 = 回测窗口本身,
+    存在即用, 窗口切片由调用方做。日线才用根数门槛 (保证"至少3年/1年"样本)。
+    """
+    if date_type.startswith('M'):
+        return 1
+    if _is_convertible(stock_code):
+        return DATASET_MIN_BARS_CB
+    return DATASET_MIN_BARS
+
+
+def _dataset_path(stock_code: str, date_type: str, fu_quan_type: int) -> Path:
+    """code 含后缀 → 剥 (dataset 内部统一裸 6 位, 与容维一致)。"""
+    bare = stock_code.split('.')[0]
+    return _DATASET_DIR / f'{bare}_{date_type}_fq{fu_quan_type}.parquet'
+
+
+def bundle_path(universe_code: str, date_type: str = 'D') -> Path:
+    """server 内置数据集整包落盘缓存 (无 TTL, 历史不变)。
+
+    布局: <data_cache>/datasets/__bundle__<universe>_<DateType>.parquet
+    与单股 dataset (裸 6 位前缀) 区分 — __bundle__ 前缀不会撞股票代码。
+    整包下载一次, 同进程内多只股票从同一份抽取, 不重复下载/解析。
+    """
+    return _DATASET_DIR / f'__bundle__{universe_code}_{date_type}.parquet'
+
+
+def read_dataset(stock_code: str, date_type: str, fu_quan_type: int,
+                 start: str, end: str) -> list[dict] | None:
+    """读取数据集切片。数据集根数足够 → 返升序窗口切片;否则 None (视为 miss, 重建)。
+
+    "存在"判定只看数据集根数 >= DATASET_MIN_BARS。切片过滤后为空 (如 start/end
+    恰为非交易日) 是正常结果, 不代表数据集缺失 — 若把空切片当 miss, 回测逐 bar
+    调非交易日窗口会反复触发重建 (每次卡几秒网络)。
+
+    无 TTL — 历史 K 线不变。性能: 全量 parquet 用 lru_cache 进程内缓存,
+    切片在内存做 — 回测逐 bar 请求不再反复读盘/pyarrow 加载。
+    """
+    path = _dataset_path(stock_code, date_type, fu_quan_type)
+    if not path.exists():
+        return None
+    rows = list(_read_dataset_full(stock_code, date_type, fu_quan_type))
+    if len(rows) < _min_bars(stock_code, date_type):
+        # 短样本 (次新股/新转债历史不足) 不立即重建: 用 TTL 临时复用,
+        # 避免每次回测都重新翻页构建 (296 只转债反复重建 ~74s)。到期重建拉新历史。
+        if _is_convertible(stock_code) and time.time() - path.stat().st_mtime < DATASET_SHORT_TTL:
+            pass  # 临时复用短样本
+        else:
+            return None
+    if start:
+        # 日线 bar 有 date (YYYYMMDD); 分钟 bar 有 datetime (YYYYMMDDHHMM), 切片按前 8 位
+        date_of = lambda r: r.get('date') or r.get('datetime', '')[:8]  # noqa: E731
+        # 覆盖检查: 缓存最末日期 < 请求 start → 缓存陈旧 (e.g. 之前构建时只拉到旧数据,
+        # 后来回测窗口更新), 视为 miss 重建。次新/停更标的例外: 上游日线已到尽头
+        # (历史只到某日后停更, e.g. 转债摘牌/退市), 构建拉到最早一根后上游无更多数据,
+        # last < start 是正常结果, 每次重建只会拉到同样的旧数据 — 若不放行会死循环重建。
+        if _dataset_is_complete(stock_code, date_type, fu_quan_type, rows):
+            pass  # 已拉满上游 (最早根就是 dataset 首根) → 放行, 不再重建
+        else:
+            last = date_of(rows[-1])
+            if last < start:
+                return None
+        rows = [r for r in rows if start <= date_of(r) <= end]
+    return rows  # 可为空 list (非交易日切片); 调用方不应据此重建
+
+
+# 上游已拉满标记: dataset 构建拉到最早一根 (次新/停更标的) 时写一个侧车文件。
+# 若无此标记, 覆盖检查对这类标的永远 last < start → 死循环重建 (实测 128044 8x)。
+_COMPLETE_SUFFIX = '.complete'
+
+
+def _complete_path(stock_code: str, date_type: str, fu_quan_type: int) -> Path:
+    return Path(str(_dataset_path(stock_code, date_type, fu_quan_type)) + _COMPLETE_SUFFIX)
+
+
+def _dataset_is_complete(stock_code: str, date_type: str, fu_quan_type: int,
+                         rows: list[dict]) -> bool:
+    """数据集是否已拉满上游 (构建时翻页无更早数据即视为完整)。
+
+    无 complete 标记 → False (回落旧覆盖检查)。标记由 build_bars_dataset 在
+    翻页 `not fresh: break` (上游无更早数据) 时写入。
+    """
+    if not rows:
+        return False
+    return _complete_path(stock_code, date_type, fu_quan_type).exists()
+
+
+from functools import lru_cache  # noqa: E402  (import 放函数后, 保持文件顶部简洁)
+
+
+@lru_cache(maxsize=64)
+def _read_dataset_full(stock_code: str, date_type: str, fu_quan_type: int) -> tuple:
+    """读全量数据集 parquet → tuple (可 hash, 供 lru_cache)。调用方转回 list。"""
+    path = _dataset_path(stock_code, date_type, fu_quan_type)
+    rows = _read_parquet(path)
+    return tuple(rows)
+
+
+def write_dataset(stock_code: str, date_type: str, fu_quan_type: int,
+                  rows: list[dict]) -> None:
+    """写入/覆盖数据集 (升序 bars)。"""
+    _DATASET_DIR.mkdir(parents=True, exist_ok=True)
+    path = _dataset_path(stock_code, date_type, fu_quan_type)
+    _write_parquet(path, rows)
+
+
+# ---- parquet (依赖 pyarrow/pandas, 可选) ----
+
+def _read_parquet(path: Path) -> list[dict]:
+    try:
+        import pandas as pd
+    except ImportError:
+        return []
+    if not path.exists() or path.stat().st_size == 0:
+        # 0 字节/不存在 → 损坏或半截写入 (build 中断/磁盘满) → 当 miss, 调用方重建。
+        # 若让 pd.read_parquet 抛 ArrowInvalid, 回测逐 bar 读同一文件会硬崩 (实测 001358)。
+        return []
+    return pd.read_parquet(path).to_dict(orient='records')
+
+
+def _write_parquet(path: Path, data: list[dict]) -> None:
+    try:
+        import pandas as pd
+    except ImportError:
+        path.write_text(json.dumps(data, ensure_ascii=False, indent=2),
+                        encoding='utf-8')
+        return
+    pd.DataFrame(data).to_parquet(path)