qka 2.4.2.dev2__py3-none-any.whl → 2.4.3.dev2__py3-none-any.whl

qka/__init__.py

@@ -13,7 +13,7 @@ except PackageNotFoundError:
 
 # 核心功能直接导入
 from qka.core.simulate import Simulate
-from qka.core.data import Data
+from qka.core.data import Data, set_tickflow_api_key
 from qka.core.accessor import DataAccessor
 from qka.core.backtest import Backtest
 from qka.core.strategy import Strategy
@@ -33,6 +33,8 @@ __all__ = [
     'Analysis', 'Segment', 'AlphaBeta',
     # 通达信数据源
     'set_tdx_root', 'get_tdx_root_info',
+    # TickFlow 凭据（进程级设一次）
+    'set_tickflow_api_key',
     # 子模块
     'core', 'utils'
 ]

qka/core/data.py

@@ -48,6 +48,51 @@ def _callable_source(fn):
         return None
 
 
+# ── TickFlow 凭据（进程级，设一次即可）──────────────────────────
+# 放在模块级而不是 `Data` 参数里：「用哪个凭据」是部署级配置，不该每构造一次
+# Data 就传一遍。优先级：set_tickflow_api_key() > 环境变量 > 免费档。
+_TICKFLOW_API_KEY: Optional[str] = None
+
+
+def set_tickflow_api_key(api_key: Optional[str]) -> None:
+    """设置 TickFlow API key（进程级，设一次即可）。
+
+    设了之后所有 `Data(source='tickflow')` 都走完整服务
+    （https://api.tickflow.org）；不设则走免费档
+    （https://free-api.tickflow.org），与既有行为完全一致。
+
+    优先级：本函数设的值 > 环境变量 ``TICKFLOW_API_KEY`` > 免费档。
+
+    Args:
+        api_key: 密钥；传 None 或空串表示清除，回到免费档。
+
+    Examples:
+        >>> from qka import Data, set_tickflow_api_key
+        >>> set_tickflow_api_key('tk_xxx')
+        >>> Data(symbols=['600519.SH']).get()      # 已走完整服务
+    """
+    global _TICKFLOW_API_KEY
+    _TICKFLOW_API_KEY = api_key or None
+    # 已经建好的客户端按旧 key 建的，作废掉 —— 否则「先建了免费档客户端、
+    # 后设 key」这条时间线会静默继续走免费档，既看不出来又难查。
+    Data._reset_tickflow_clients()
+
+
+def get_tickflow_api_key() -> Optional[str]:
+    """当前生效的 TickFlow key：函数设的优先，其次环境变量，都没有则 None。"""
+    return _TICKFLOW_API_KEY or os.environ.get('TICKFLOW_API_KEY') or None
+
+
+def _key_fingerprint(api_key: Optional[str]) -> str:
+    """key 的短摘要，用作客户端缓存的键。
+
+    不拿明文 key 当字典键 —— 免得它出现在内存转储或日志里。
+    """
+    if not api_key:
+        return ''
+    return hashlib.sha1(api_key.encode('utf-8')).hexdigest()[:12]
+
+
 # 当日日线数据「可能已经生成」的时刻（本地时间）。一天以它为界切成前后两个时段：
 # 17:00 之前，数据源手里最新的一根还是上一交易日，当天这根根本还没生成；
 # 17:00 之后，当天的已经出完了，要补也就这一次。
@@ -1662,24 +1707,44 @@ class Data():
 
     # ── TickFlow 数据源 ────────────────────────────────────────
 
-    _tf_client = None   # 进程级复用，避免重复初始化
+    _tf_clients = {}    # {key 摘要: 客户端} —— 进程级复用；按 key 分开存，不同 key 不互相串
     _tf_client_lock = threading.Lock()
 
+    @classmethod
+    def _reset_tickflow_clients(cls):
+        """丢掉已建好的 tickflow 客户端，下次按当前 key 重建。
+
+        由 `set_tickflow_api_key()` 调用：客户端一旦建好就缓存住，不清的话
+        「先建了免费档客户端、后设 key」会静默继续走免费档。
+        """
+        with cls._tf_client_lock:
+            cls._tf_clients.clear()
+
     @classmethod
     def _tickflow_client(cls):
-        """惰性创建并复用 TickFlow 客户端（当前走免费服务，无需 api_key）。"""
-        if cls._tf_client is None:
+        """惰性创建并复用 TickFlow 客户端。
+
+        有 key 走完整服务（api.tickflow.org），没有就走免费档
+        （free-api.tickflow.org）。key 是**建客户端这一刻**现取的，
+        所以设 key 的时机不必早于 import（见 `set_tickflow_api_key`）。
+        """
+        key = get_tickflow_api_key()
+        cache_key = _key_fingerprint(key)
+        client = cls._tf_clients.get(cache_key)
+        if client is None:
             with cls._tf_client_lock:
-                if cls._tf_client is None:
+                client = cls._tf_clients.get(cache_key)
+                if client is None:
                     from tickflow import TickFlow
-                    # TickFlow.free() 会往 stdout 打一段带 emoji 的「免费档」说明。
+                    # free() 会往 stdout 打一段带 emoji 的「免费档」说明。
                     # stdout 被重定向到文件、且编码非 UTF-8 时（如打包版把后端输出
                     # 写入 GBK 日志），print emoji 会抛 UnicodeEncodeError 而中断下载，
                     # 故创建期间丢弃其标准输出。（redirect_stdout 改的是全局 sys.stdout，
                     # 并发首次创建会互相覆盖，故用锁串行化。）
                     with contextlib.redirect_stdout(io.StringIO()):
-                        cls._tf_client = TickFlow.free()
-        return cls._tf_client
+                        client = TickFlow(api_key=key) if key else TickFlow.free()
+                    cls._tf_clients[cache_key] = client
+        return client
 
     @staticmethod
     def _split_symbol(symbol: str):

qka/skills/qka/references/data.md

@@ -106,6 +106,42 @@ datadir/factors/{因子名}/{symbol}.parquet      # 单列，日期索引
 
 **作用范围**：只作用于默认（`lazy=False`）路径；`lazy=True`（回测走的那条）行为不变。不传 `factor_cache` 时，一切跟没有这个功能一样：不读、不写、不建目录。
 
+### TickFlow 凭据
+
+TickFlow 有两个入口，qka 按「有没有 key」自动选：
+
+| 有没有 key | 走的入口 | 域名 |
+|---|---|---|
+| 有 | 完整服务 | `https://api.tickflow.org` |
+| 没有 | 免费档 | `https://free-api.tickflow.org` |
+
+不设 key 时与旧版行为完全一致（免费档提供日线、标的元信息、交易所、池子查询、复权因子；实时行情与分钟线是完整服务的能力）。
+
+设 key 的方式是**进程级、设一次即可** —— 不用每次构造 `Data` 都传：
+
+```python
+from qka import Data, set_tickflow_api_key
+
+set_tickflow_api_key('tk_xxx')       # 设一次，之后所有 source='tickflow' 的取数都生效
+data = Data(symbols=['600519.SH'])   # 不用再传任何东西
+data.get()
+
+set_tickflow_api_key(None)           # 清除，回到免费档
+```
+
+优先级：**`set_tickflow_api_key()` > 环境变量 `TICKFLOW_API_KEY` > 免费档**（显式盖过隐式）。
+
+不想改代码的话，部署时设环境变量即可：
+
+```bash
+export TICKFLOW_API_KEY=tk_xxx
+```
+
+两点实现细节，用的时候心里有数：
+
+- 读 key 的时机是**建客户端那一刻**，不是 `import` 时 —— 所以设 key 不必早于 `import qka`。
+- 换 key（或从免费档切到 key）时，已建好的客户端会**自动作废重建**，不会继续沿用旧入口。
+
 ### 通达信数据源
 
 `source='tdx'` 走本机安装的「支持 TQ 策略」通达信客户端（在进程内 `import tqcenter`，由客户端与本机 `TdxW.exe` 通信）。前提与边界：

{qka-2.4.2.dev2.dist-info → qka-2.4.3.dev2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qka
-Version: 2.4.2.dev2
+Version: 2.4.3.dev2
 Summary: QKA（快量化 / Quant Kit for A-shares）- 简洁易用的 A 股量化回测框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Repository, https://github.com/zsrl/qka

{qka-2.4.2.dev2.dist-info → qka-2.4.3.dev2.dist-info}/RECORD

@@ -1,11 +1,11 @@
-qka/__init__.py,sha256=2EgIGy3W2NFvxniqHKpCYRhRIOSGRrkEa94gr3UEezo,1087
+qka/__init__.py,sha256=xFkw3C-0TzeNkr5hPtz-0ZWwLao3cihUAUCXSE8FO1c,1183
 qka/cli.py,sha256=12ZkbSZmE7hSmz5_O67gOXVKROIdymCQevnNfEOApd8,466
 qka/core/__init__.py,sha256=kVhvzSA915MXOk9axq9T-COlv3OeTPfv2avX58WxElE,578
 qka/core/accessor.py,sha256=iEZrteVe8nqv3s5Va2l3Vz50N2S6X0IOElKq9Ik3Wno,2893
 qka/core/analysis.py,sha256=EXCO4qhzd2av5Yb4jihcNji1V-VFPOceUHKtg-q8bLs,11142
 qka/core/backtest.py,sha256=kzMAFbyGFvGE--Qypiot6wAp0jTiEsOPbaPd8Zs3o1M,13541
 qka/core/broker.py,sha256=FxeHh9qZ9M6FNFLd8EXwztA4kmC9zZzkrXin2hdVFa4,9662
-qka/core/data.py,sha256=KjjE7ltK7R5Yyxc63BQiPwwK5hQhg_yBVbn3CEUieXo,86796
+qka/core/data.py,sha256=j5QNO_LbgU84mxC5rSIhyeaB-bL9HgTZUy5AelBYnVY,89607
 qka/core/indicator.py,sha256=OId8bgYFCzDgjPr27rb6zHYxkPYX0XrjlWylGSQ2KCU,6447
 qka/core/report.py,sha256=TaZoxWk7ZIPLhA9Ss9UOmxWY2ymzKJRUnxSzmyPcBTI,22386
 qka/core/simulate.py,sha256=bdThckUFj0Y3GyAj5ahLIGv3HetJFTbyxbEcX2SUKn0,2915
@@ -18,11 +18,11 @@ qka/skills/qka/SKILL.md,sha256=lddd_JvGZ0x4JBlz_IB1cd4ScHRZ30-IC9SWI9Tjbvw,2132
 qka/skills/qka/references/analysis.md,sha256=GdFbK3fa8sFgvcxJ1xzkToF4QwsCFXf_EgKb9bbRgwo,3587
 qka/skills/qka/references/backtest.md,sha256=ZXL58zpuYHAJglPNk52an4fP3i0Ggnpuf0pg0QlbPk4,4803
 qka/skills/qka/references/broker.md,sha256=wr62v1asRM-wBdsADIsB406eXm_ENYcrwGMANQobaa0,1083
-qka/skills/qka/references/data.md,sha256=dspj4yqK0oZP5vFGAdfQRvGmk4RQupAr4L4DsByUQ-I,27472
+qka/skills/qka/references/data.md,sha256=6mL44eGOk_xXLqQ62Wmv1DFYcXn3kayYWYWMd8-hFOk,28857
 qka/skills/qka/references/sizing.md,sha256=3SsX2ddQoHjE177dberW0Q7wYxW-M_2DG_-sV3CCo9A,656
 qka/skills/qka/references/strategy.md,sha256=-6xa_oigTTj77Siity5bTC5MbdF3UKfld9imnevlAAc,4455
-qka-2.4.2.dev2.dist-info/METADATA,sha256=AXXFmn0jkeEh0KLSljcNeCjMVpHYnJrt3haeozdWUzE,7545
-qka-2.4.2.dev2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-qka-2.4.2.dev2.dist-info/entry_points.txt,sha256=quG9zg-rOKKtbg-6FiXkoxkUUTMltMBD0hZ0QUnJ6RM,37
-qka-2.4.2.dev2.dist-info/licenses/LICENSE,sha256=3iIG35SnJNF11yIzm3vxa2QUvy9SS5rktM3O1DL2vqM,1075
-qka-2.4.2.dev2.dist-info/RECORD,,
+qka-2.4.3.dev2.dist-info/METADATA,sha256=bOyyD3-Bjjlh5EzzCUtfEWKg69KNpvzgWiGTBhMadto,7545
+qka-2.4.3.dev2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+qka-2.4.3.dev2.dist-info/entry_points.txt,sha256=quG9zg-rOKKtbg-6FiXkoxkUUTMltMBD0hZ0QUnJ6RM,37
+qka-2.4.3.dev2.dist-info/licenses/LICENSE,sha256=3iIG35SnJNF11yIzm3vxa2QUvy9SS5rktM3O1DL2vqM,1075
+qka-2.4.3.dev2.dist-info/RECORD,,