quantdb-sdk 0.4.6__tar.gz → 0.4.8__tar.gz

{quantdb_sdk-0.4.6 → quantdb_sdk-0.4.8}/CHANGELOG.md

@@ -3,6 +3,34 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## \[0.4.8] - 2026-10-27
+
+### Fixed
+
+- **`quantdb usage` 在中文 Windows 控制台崩溃**：`余额` 一行输出的是窄人民币符号 U+00A5，而 Windows 中文控制台默认编码是 GBK/cp936，**GBK 中不存在该字符**（GBK 用 0x80 表示），`print` 抛 `UnicodeEncodeError: 'gbk' codec can't encode character '\xa5'`，命令以异常收场、后续输出（订阅状态等）全部丢失。
+  修复两处：① 金额改用**全角人民币符号 U+FFE5**（GBK 可编码，中文终端显示正常）；② CLI 入口新增 `_configure_stdout()`，把 stdout/stderr 的编码错误处理降级为 `replace`——以后任何不可编码字符只会显示为 `?`，不再中断命令。
+
+### Added
+
+- 新增回归测试 `tests/test_cli_encoding.py`（仓库根 `tests/`，不进 wheel）：
+  - 扫描 SDK 全部源码的**字符串字面量**，断言每个字符都能被 GBK 编码——防止再次引入不可编码字符；
+  - 在 GBK 编码的 stdout 下渲染用量输出，断言不抛异常；
+  - 断言 `_configure_stdout()` 确实把编码错误处理改为 `replace`。
+
+## \[0.4.7] - 2026-10-27
+
+### Fixed
+
+- **适配下载 302 单跳直连**：服务端已取消「一次性下载令牌 + `/api/v1/data/cdn-bridge` 中转」链路，`/api/v1/data/download` 预扣成功后直接 302 到 CDN 签名 URL（单跳）。同步/异步客户端原有的两跳跟随假设已相应调整：
+  - 新增 **CDN 专用裸会话**（`QuantDBClient._cdn_session`）：直连 CDN 时**不携带 API Key / JWT**，避免鉴权头泄露到 CDN 域；同一会话跨文件复用 TLS 连接，避免逐文件新建连接反复握手。
+  - 手动跟随重定向并保留每跳的 connect timeout 重试，网络抖动不会中断整个同步。
+
+### Changed
+
+- 直连 CDN 模式**签发即按对象大小计费、不再退款**（服务端无法观测直连传输的真实字节，退款只能依赖客户端自报，不可信）。需要按真实传输计费、断点续传可退款的用户，应在请求头发送 `X-QuantDB-Delivery: proxy` 走网关代理模式（网关可观测字节并按未发送部分退款）。
+
+> 兼容性：0.4.7 对接 2026-10-27 上线的服务端版本；旧服务端（两跳 cdn-bridge）仍可正常同步，无需回退。
+
 ## \[0.4.6] - 2026-10-27
 
 ### Fixed

{quantdb_sdk-0.4.6/quantdb_sdk.egg-info → quantdb_sdk-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.4.6
+Version: 0.4.8
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT

{quantdb_sdk-0.4.6 → quantdb_sdk-0.4.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantdb-sdk"
-version = "0.4.6"
+version = "0.4.8"
 description = "QuantDB 量化数据平台官方 Python SDK"
 readme = "README.md"
 license = {text = "MIT"}

{quantdb_sdk-0.4.6 → quantdb_sdk-0.4.8}/quantdb_sdk/__main__.py

@@ -63,7 +63,42 @@ def cmd_datasets(name: Optional[str] = None) -> int:
     return 0
 
 
+def _configure_stdout() -> None:
+    """让 CLI 在非 UTF-8 控制台（中文 Windows 默认 GBK/cp936）下不因不可编码字符崩溃。
+
+    Windows 中文控制台的默认编码是 GBK，而窄人民币符号 U+00A5 在 GBK 中**不存在**
+    （GBK 用 0x80 表示该符号），直接 print 会抛
+    ``UnicodeEncodeError: 'gbk' codec can't encode character '\\xa5'``，
+    导致整条命令以异常收场、后续输出全部丢失。
+
+    这里把 stdout/stderr 的编码错误处理改成 replace：无法编码的字符降级为 '?'，
+    命令本身不再中断。配合正文中改用全角 ￥（U+FFE5，GBK 可编码），
+    中文 Windows 终端可正常显示金额。
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")  # type: ignore[attr-defined]
+        except Exception:  # pragma: no cover - 老版本/非 TextIOWrapper 忽略
+            pass
+
+
+def print_usage(usage: dict) -> None:
+    """打印账户用量（抽成独立函数便于单测覆盖非 UTF-8 控制台场景）。"""
+    print("账户用量:")
+    print(f"  套餐:   已用 {usage['plan_used_gb']:.2f} GB / {usage['plan_total_gb']:.2f} GB"
+          f"（剩余 {usage['plan_remaining_gb']:.2f} GB）")
+    print(f"  流量包: 已用 {usage['package_used_gb']:.2f} GB / {usage['package_total_gb']:.2f} GB"
+          f"（剩余 {usage['package_remaining_gb']:.2f} GB）")
+    print(f"  合计:   已用 {usage['used_gb']:.2f} GB / {usage['total_gb']:.2f} GB"
+          f"（剩余 {usage['remaining_gb']:.2f} GB）")
+    # 全角人民币符号 U+FFE5：GBK 可编码；窄符号 U+00A5 在 GBK 中不存在会崩溃
+    print(f"  余额: ￥{usage['balance_yuan']:.2f}")
+    sub = usage.get("subscription", {})
+    print(f"  订阅: {sub.get('status', 'none')}")
+
+
 def main() -> int:
+    _configure_stdout()
     parser = argparse.ArgumentParser(
         prog="quantdb",
         description="QuantDB 量化数据平台官方 Python SDK",
@@ -158,16 +193,7 @@ def main() -> int:
 
         if args.command == "usage":
             usage = client.get_usage()
-            print(f"账户用量:")
-            print(f"  套餐:   已用 {usage['plan_used_gb']:.2f} GB / {usage['plan_total_gb']:.2f} GB"
-                  f"（剩余 {usage['plan_remaining_gb']:.2f} GB）")
-            print(f"  流量包: 已用 {usage['package_used_gb']:.2f} GB / {usage['package_total_gb']:.2f} GB"
-                  f"（剩余 {usage['package_remaining_gb']:.2f} GB）")
-            print(f"  合计:   已用 {usage['used_gb']:.2f} GB / {usage['total_gb']:.2f} GB"
-                  f"（剩余 {usage['remaining_gb']:.2f} GB）")
-            print(f"  余额: ¥{usage['balance_yuan']:.2f}")
-            sub = usage.get("subscription", {})
-            print(f"  订阅: {sub.get('status', 'none')}")
+            print_usage(usage)
             return 0
 
         if args.command == "sync":

{quantdb_sdk-0.4.6 → quantdb_sdk-0.4.8}/quantdb_sdk/async_client.py

@@ -28,7 +28,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.6"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.8"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -139,8 +139,8 @@ class AsyncQuantDBClient:
         裸客户端直连 Location，鉴权头不会泄露给 CDN 域。
 
         重定向链路（CDN 直连模式）：
-          /download 302→ /cdn-bridge?token=xxx 302→ https://cdn.xxx/key?sign=...
-        两跳均手动跟随，每跳带重试（connect timeout 网络抖动容错）。
+          /download 302→ https://cdn.xxx/key?sign=...（单跳）
+        手动跟随，每跳带重试（connect timeout 网络抖动容错）。
         """
         async with self.client.stream(
             "GET", f"{self.api_host}/api/v1/data/download", params=params, headers=headers
@@ -166,9 +166,8 @@ class AsyncQuantDBClient:
     ) -> httpx.Response:
         """手动跟随 302 重定向链路，每跳带重试。
 
-        cdn-bridge 和 CDN 直连请求均通过此方法，connect timeout 网络抖动
-        时自动重试，避免一次性 token（90s 有效期）场景下单次抖动导致整个
-        sync 中断。
+        CDN 直连请求通过此方法，connect timeout 网络抖动时自动重试，避免
+        单次抖动导致整个 sync 中断。
 
         返回已进入 stream 模式的 httpx.Response，调用方需用 async with 管理。
         """

{quantdb_sdk-0.4.6 → quantdb_sdk-0.4.8}/quantdb_sdk/client.py

@@ -32,7 +32,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.6"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.8"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -75,6 +75,9 @@ class QuantDBClient:
         self.headers: Dict[str, str] = {}
         self.session = requests.Session()
         self.session.headers.update({"User-Agent": _USER_AGENT})
+        # CDN 直连专用会话：不携带 API Key / JWT，且跨文件复用 TLS 连接（逐文件新建连接会反复握手）。
+        self._cdn_session = requests.Session()
+        self._cdn_session.headers.update({"User-Agent": _USER_AGENT})
 
         if api_key:
             self.headers = {"X-API-Key": api_key}
@@ -168,13 +171,10 @@ class QuantDBClient:
     def _download_stream(self, params: dict, headers: Optional[dict] = None) -> requests.Response:
         """下载专用流式请求：手动处理服务端 302 CDN 直连跳转。
 
-        服务端开启 CDN 直连后，/api/v1/data/download 预扣流量成功时返回
-        302 -> CDN 签名 URL。requests 自动跟随会把自定义 X-API-Key 头
-        透传给 CDN 域，故禁用自动跟随，改用不带鉴权头的裸请求直连。
-
-        重定向链路（CDN 直连模式）：
-          /download 302→ /cdn-bridge?token=xxx 302→ https://cdn.xxx/key?sign=...
-        两跳均手动跟随，每跳带重试（connect timeout 网络抖动容错）。
+        服务端开启 CDN 直连后，/api/v1/data/download 预扣流量成功时直接返回
+        302 -> CDN 签名 URL（单跳）。requests 自动跟随会把自定义 X-API-Key 头
+        透传给 CDN 域，故禁用自动跟随，改用不带鉴权头的 CDN 专用会话直连。
+        每跳带重试（connect timeout 网络抖动容错）。
         """
         resp = self._request(
             "GET", "/api/v1/data/download", params=params, stream=True,
@@ -200,21 +200,15 @@ class QuantDBClient:
     ) -> requests.Response:
         """手动跟随 302 重定向链路，每跳带重试。
 
-        cdn-bridge 和 CDN 直连请求均通过此方法，connect timeout 网络抖动
-        时自动重试，避免一次性 token（90s 有效期）场景下单次抖动导致整个
-        sync 中断。
+        CDN 直连请求通过此方法，connect timeout 网络抖动时自动重试，避免
+        单次抖动导致整个 sync 中断。
         """
         current_etag = etag
         for _ in range(max_hops):
             last_exc = None
             for attempt in range(retries + 1):
                 try:
-                    cdn_resp = requests.get(
-                        url,
-                        stream=True,
-                        timeout=self.timeout,
-                        headers={"User-Agent": _USER_AGENT},
-                    )
+                    cdn_resp = self._cdn_session.get(url, stream=True, timeout=self.timeout)
                     break
                 except (requests.ConnectionError, requests.Timeout) as exc:
                     last_exc = exc

{quantdb_sdk-0.4.6 → quantdb_sdk-0.4.8/quantdb_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.4.6
+Version: 0.4.8
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT

{quantdb_sdk-0.4.6 → quantdb_sdk-0.4.8}/quantdb_sdk.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ quantdb_sdk/examples/demo_05_read_local_data.py
 quantdb_sdk/examples/demo_06_tick_and_factors.py
 quantdb_sdk/examples/demo_07_data_hub.py
 tests/test_async_client.py
+tests/test_cli_encoding.py
 tests/test_client.py
 tests/test_data_hub.py
 tests/test_hub_models.py

quantdb_sdk-0.4.8/tests/test_cli_encoding.py

@@ -0,0 +1,92 @@
+"""CLI 输出编码回归测试。
+
+背景：Windows 中文控制台默认编码是 GBK/cp936，而 U+00A5（窄人民币符号）在 GBK
+中不存在，`print` 会抛 UnicodeEncodeError，导致命令以异常收场、后续输出全部丢失
+（0.4.8 修复：改用全角 U+FFE5 + stdout 错误处理降级为 replace）。
+
+本文件放在仓库根的 tests/ 下（不在 quantdb_sdk 包内），不会被打进 wheel。
+"""
+
+import io
+import pathlib
+import sys
+import tokenize
+
+import pytest
+
+SDK_DIR = pathlib.Path(__file__).resolve().parents[1] / "quantdb_sdk"
+
+
+def _string_literal_chars(path: pathlib.Path):
+    """收集源码中所有字符串字面量（含 docstring）里出现过的字符。"""
+    source = path.read_text(encoding="utf-8")
+    chars = set()
+    for token in tokenize.generate_tokens(io.StringIO(source).readline):
+        if token.type == tokenize.STRING:
+            chars.update(token.string)
+    return chars
+
+
+def test_sdk_string_literals_are_gbk_encodable():
+    """所有会被打印的字符串都必须能被 GBK 编码，否则中文 Windows 控制台会崩溃。"""
+    offenders = []
+    for path in sorted(SDK_DIR.rglob("*.py")):
+        for ch in _string_literal_chars(path):
+            try:
+                ch.encode("gbk")
+            except UnicodeEncodeError:
+                offenders.append((path.relative_to(SDK_DIR.parent).as_posix(), hex(ord(ch))))
+    assert not offenders, (
+        "以下字符在 GBK 控制台无法编码（会崩溃 CLI 输出）: "
+        + ", ".join(f"{f}:{cp}" for f, cp in offenders)
+    )
+
+
+def test_print_usage_under_gbk_stdout(monkeypatch, capsys):
+    """在 GBK 编码的 stdout 下打印用量，不得抛 UnicodeEncodeError。"""
+    from quantdb_sdk.__main__ import print_usage
+
+    buffer = io.BytesIO()
+    gbk_stdout = io.TextIOWrapper(buffer, encoding="gbk", errors="strict")
+    monkeypatch.setattr(sys, "stdout", gbk_stdout)
+
+    print_usage({
+        "plan_used_gb": 50.0, "plan_total_gb": 50.0, "plan_remaining_gb": 0.0,
+        "package_used_gb": 15.8, "package_total_gb": 110.0, "package_remaining_gb": 94.2,
+        "used_gb": 50.0, "total_gb": 160.0, "remaining_gb": 94.2,
+        "balance_yuan": 12.34,
+        "subscription": {"status": "active"},
+    })
+    gbk_stdout.flush()
+
+    out = buffer.getvalue().decode("gbk")
+    assert "账户用量" in out
+    assert "12.34" in out
+
+
+def test_configure_stdout_downgrades_encoding_errors(monkeypatch):
+    """_configure_stdout 应把 stdout/stderr 的编码错误处理改为 replace。"""
+    from quantdb_sdk.__main__ import _configure_stdout
+
+    buffer = io.BytesIO()
+    stream = io.TextIOWrapper(buffer, encoding="gbk", errors="strict")
+    monkeypatch.setattr(sys, "stdout", stream)
+    monkeypatch.setattr(sys, "stderr", stream)
+
+    _configure_stdout()
+
+    assert stream.errors == "replace"
+    # 不可编码字符应降级为 '?' 而不是抛异常
+    stream.write("\u00a5")
+    stream.flush()
+    assert "?" in buffer.getvalue().decode("gbk")
+
+
+def test_main_version_smoke():
+    """--version 走 argparse 的 version action，不应因控制台编码崩溃。"""
+    from quantdb_sdk.__main__ import main
+
+    with pytest.raises(SystemExit) as exc:
+        sys.argv = ["quantdb", "--version"]
+        main()
+    assert exc.value.code == 0