quantdb-sdk 0.2.7__tar.gz → 0.2.9__tar.gz

{quantdb_sdk-0.2.7 → quantdb_sdk-0.2.9}/CHANGELOG.md

@@ -3,6 +3,13 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [0.2.8] - 2026-07-30
+
+### Fixed
+- **CDN 直连下载 302 相对 URL 拼接**：服务端 CDN 直连模式（`QUANTDB_DOWNLOAD_REDIRECT`）的 Stage 1 302 返回相对 URL（`/api/v1/data/cdn-bridge?token=xxx`），同步/异步客户端此前直接将此相对路径作为请求 URL，导致 `requests`/`httpx` 无法解析（`MissingSchema`/`UnsupportedProtocol`），CDN 直连下载完全不可用。现在当 `Location` 以 `/` 开头时自动拼接 `api_host` 构造完整 URL。
+- **CDN 直连请求无重试**：cdn-bridge 和 CDN 签名 URL 请求此前使用裸 `requests.get()`/`httpx.stream()` 调用，无重试、无超时容错。一次 connect timeout 或网络抖动即导致整个 `sync_dataset` 中断（且预扣流量不退）。现在两跳均带 2 次重试（指数退避 1s/2s），捕获 `ConnectionError`/`Timeout`/`ReadError` 自动重试。
+- **302 重定向链路手动跟随**：此前只跟随第一跳 302，服务端两跳链路（`/download` → `/cdn-bridge?token=xxx` → CDN 签名 URL）的第二跳被忽略。现在统一用 `_follow_redirect_with_retry` 循环跟随最多 3 跳，ETag 逐跳透传。
+
 ## [0.2.7] - 2026-07-29
 
 ### Fixed

{quantdb_sdk-0.2.7/quantdb_sdk.egg-info → quantdb_sdk-0.2.9}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.2.7
+Version: 0.2.9
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
-Project-URL: Homepage, https://www.quantmindai.cn
-Project-URL: Documentation, https://www.quantmindai.cn/docs/sdk.html
+Project-URL: Homepage, https://quantdb.quantmind.cloud
+Project-URL: Documentation, https://quantdb.quantmind.cloud/docs/sdk.html
 Project-URL: Repository, https://github.com/quantdb/quantdb
 Project-URL: Changelog, https://github.com/quantdb/quantdb/blob/main/CHANGELOG.md
 Keywords: quant,finance,data,a-share,parquet
@@ -147,4 +147,4 @@ with ThreadPoolExecutor(max_workers=8) as pool:
 
 ## 文档
 
-完整文档请访问：https://www.quantmindai.cn/docs/sdk.html
+完整文档请访问：https://quantdb.quantmind.cloud/docs/sdk.html

{quantdb_sdk-0.2.7 → quantdb_sdk-0.2.9}/README.md

@@ -110,4 +110,4 @@ with ThreadPoolExecutor(max_workers=8) as pool:
 
 ## 文档
 
-完整文档请访问：https://www.quantmindai.cn/docs/sdk.html
+完整文档请访问：https://quantdb.quantmind.cloud/docs/sdk.html

{quantdb_sdk-0.2.7 → quantdb_sdk-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantdb-sdk"
-version = "0.2.7"
+version = "0.2.9"
 description = "QuantDB 量化数据平台官方 Python SDK"
 readme = "README.md"
 license = {text = "MIT"}
@@ -53,8 +53,8 @@ dev = [
 ]
 
 [project.urls]
-Homepage = "https://www.quantmindai.cn"
-Documentation = "https://www.quantmindai.cn/docs/sdk.html"
+Homepage = "https://quantdb.quantmind.cloud"
+Documentation = "https://quantdb.quantmind.cloud/docs/sdk.html"
 Repository = "https://github.com/quantdb/quantdb"
 Changelog = "https://github.com/quantdb/quantdb/blob/main/CHANGELOG.md"
 

{quantdb_sdk-0.2.7 → quantdb_sdk-0.2.9}/quantdb_sdk/async_client.py

@@ -1,5 +1,6 @@
 """QuantDB 异步 Python SDK（基于 httpx）。"""
 
+import asyncio
 import hashlib
 import io
 import os
@@ -27,7 +28,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.2.7"
+_USER_AGENT = "QuantDB-Python-SDK/0.2.8"
 
 
 class AsyncQuantDBClient:
@@ -81,6 +82,10 @@ class AsyncQuantDBClient:
         服务端开启 CDN 直连后，/api/v1/data/download 预扣流量成功时返回
         302 -> CDN 签名 URL。httpx 默认不跟随重定向；这里用不带鉴权头的
         裸客户端直连 Location，鉴权头不会泄露给 CDN 域。
+
+        重定向链路（CDN 直连模式）：
+          /download 302→ /cdn-bridge?token=xxx 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
@@ -92,14 +97,68 @@ class AsyncQuantDBClient:
             etag = resp.headers.get("ETag", "")
             if not location:
                 raise ServerError("下载重定向缺少 Location 头")
-        async with self._bare_client.stream("GET", location) as cdn_resp:
-            if cdn_resp.status_code != 200:
-                raise ServerError(f"CDN 直连下载失败：HTTP {cdn_resp.status_code}")
-            # 网关 302 响应携带 COS ETag；若 CDN 响应缺失则回填，保证缓存逻辑一致。
-            if etag and not cdn_resp.headers.get("ETag"):
-                cdn_resp.headers["ETag"] = etag
+            # 服务端 302 可能返回相对 URL（如 /api/v1/data/cdn-bridge?token=xxx），
+            # 需拼接 api_host 构造完整 URL，否则 httpx 无法解析。
+            if location.startswith("/"):
+                location = f"{self.api_host}{location}"
+        # 手动跟随重定向链路（最多 3 跳），每跳带重试
+        cdn_resp = await self._follow_redirect_with_retry(location, etag, max_hops=3)
+        async with cdn_resp:
             yield cdn_resp
 
+    async def _follow_redirect_with_retry(
+        self, url: str, etag: str, max_hops: int = 3, retries: int = 2,
+    ) -> httpx.Response:
+        """手动跟随 302 重定向链路，每跳带重试。
+
+        cdn-bridge 和 CDN 直连请求均通过此方法，connect timeout 网络抖动
+        时自动重试，避免一次性 token（90s 有效期）场景下单次抖动导致整个
+        sync 中断。
+
+        返回已进入 stream 模式的 httpx.Response，调用方需用 async with 管理。
+        """
+        import asyncio
+        current_etag = etag
+        for _ in range(max_hops):
+            last_exc: Exception | None = None
+            cdn_resp: httpx.Response | None = None
+            for attempt in range(retries + 1):
+                try:
+                    # httpx stream() 是 async context manager，需 __aenter__ 进入
+                    ctx = self._bare_client.stream("GET", url)
+                    cdn_resp = await ctx.__aenter__()
+                    # 触发实际连接（访问 status_code 即触发 head 读取）
+                    _ = cdn_resp.status_code
+                    break
+                except (httpx.ConnectError, httpx.ConnectTimeout, httpx.ReadError, httpx.ReadTimeout) as exc:
+                    if cdn_resp is not None:
+                        await cdn_resp.aclose()
+                        cdn_resp = None
+                    last_exc = exc
+                    if attempt < retries:
+                        await asyncio.sleep(1.0 * (attempt + 1))
+            else:
+                raise ServerError(f"CDN 直连下载失败（重试 {retries} 次后仍网络错误）：{last_exc}")
+            if cdn_resp.status_code not in (200, 301, 302, 303, 307, 308):
+                await cdn_resp.aclose()
+                raise ServerError(f"CDN 直连下载失败：HTTP {cdn_resp.status_code}")
+            if cdn_resp.status_code == 200:
+                # ETag 回填：网关 302 携带的 COS ETag → CDN 响应缺失时补上
+                if current_etag and not cdn_resp.headers.get("ETag"):
+                    cdn_resp.headers["ETag"] = current_etag
+                return cdn_resp
+            # 继续跟随 302
+            next_url = cdn_resp.headers.get("Location", "")
+            next_etag = cdn_resp.headers.get("ETag", current_etag)
+            await cdn_resp.aclose()
+            if not next_url:
+                raise ServerError("重定向缺少 Location 头")
+            if next_url.startswith("/"):
+                next_url = f"{self.api_host}{next_url}"
+            url = next_url
+            current_etag = next_etag
+        raise ServerError("重定向链路过深（超过 3 跳）")
+
     @staticmethod
     def _validate_layout(layout: str) -> Literal["auto", "v1", "v2"]:
         if layout not in {"auto", "v1", "v2"}:

{quantdb_sdk-0.2.7 → quantdb_sdk-0.2.9}/quantdb_sdk/client.py

@@ -6,6 +6,7 @@ import os
 import re
 import sqlite3
 import glob
+import time
 from typing import Any, Dict, List, Optional, Literal
 
 import pandas as pd
@@ -29,7 +30,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.2.7"
+_USER_AGENT = "QuantDB-Python-SDK/0.2.8"
 
 
 class QuantDBClient:
@@ -124,6 +125,10 @@ class QuantDBClient:
         服务端开启 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 网络抖动容错）。
         """
         resp = self._request(
             "GET", "/api/v1/data/download", params=params, stream=True,
@@ -136,20 +141,61 @@ class QuantDBClient:
         resp.close()
         if not location:
             raise ServerError("下载重定向缺少 Location 头")
-        cdn_resp = requests.get(
-            location,
-            stream=True,
-            timeout=self.timeout,
-            headers={"User-Agent": _USER_AGENT},
-        )
-        if cdn_resp.status_code != 200:
-            cdn_resp.close()
-            raise ServerError(f"CDN 直连下载失败：HTTP {cdn_resp.status_code}")
-        # 网关 302 响应携带 COS ETag；若 CDN 响应缺失则回填，保证客户端缓存逻辑一致。
-        if etag and not cdn_resp.headers.get("ETag"):
-            cdn_resp.headers["ETag"] = etag
+        # 服务端 302 可能返回相对 URL（如 /api/v1/data/cdn-bridge?token=xxx），
+        # 需拼接 api_host 构造完整 URL，否则 requests.get 无法解析。
+        if location.startswith("/"):
+            location = f"{self.api_host}{location}"
+        # 手动跟随重定向链路（最多 3 跳），每跳带重试
+        cdn_resp = self._follow_redirect_with_retry(location, etag, max_hops=3)
         return cdn_resp
 
+    def _follow_redirect_with_retry(
+        self, url: str, etag: str, max_hops: int = 3, retries: int = 2,
+    ) -> requests.Response:
+        """手动跟随 302 重定向链路，每跳带重试。
+
+        cdn-bridge 和 CDN 直连请求均通过此方法，connect timeout 网络抖动
+        时自动重试，避免一次性 token（90s 有效期）场景下单次抖动导致整个
+        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},
+                    )
+                    break
+                except (requests.ConnectionError, requests.Timeout) as exc:
+                    last_exc = exc
+                    if attempt < retries:
+                        time.sleep(1.0 * (attempt + 1))
+            else:
+                raise ServerError(f"CDN 直连下载失败（重试 {retries} 次后仍网络错误）：{last_exc}")
+            if cdn_resp.status_code not in (200, 301, 302, 303, 307, 308):
+                cdn_resp.close()
+                raise ServerError(f"CDN 直连下载失败：HTTP {cdn_resp.status_code}")
+            if cdn_resp.status_code == 200:
+                # ETag 回填：网关 302 携带的 COS ETag → CDN 响应缺失时补上
+                if current_etag and not cdn_resp.headers.get("ETag"):
+                    cdn_resp.headers["ETag"] = current_etag
+                return cdn_resp
+            # 继续跟随 302
+            next_url = cdn_resp.headers.get("Location", "")
+            next_etag = cdn_resp.headers.get("ETag", current_etag)
+            cdn_resp.close()
+            if not next_url:
+                raise ServerError("重定向缺少 Location 头")
+            if next_url.startswith("/"):
+                next_url = f"{self.api_host}{next_url}"
+            url = next_url
+            current_etag = next_etag
+        raise ServerError("重定向链路过深（超过 3 跳）")
+
     def _post(self, path: str, json: Optional[dict] = None) -> dict:
         resp = self._request("POST", path, json=json)
         return self._check_response(resp)

{quantdb_sdk-0.2.7 → quantdb_sdk-0.2.9/quantdb_sdk.egg-info}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.2.7
+Version: 0.2.9
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
-Project-URL: Homepage, https://www.quantmindai.cn
-Project-URL: Documentation, https://www.quantmindai.cn/docs/sdk.html
+Project-URL: Homepage, https://quantdb.quantmind.cloud
+Project-URL: Documentation, https://quantdb.quantmind.cloud/docs/sdk.html
 Project-URL: Repository, https://github.com/quantdb/quantdb
 Project-URL: Changelog, https://github.com/quantdb/quantdb/blob/main/CHANGELOG.md
 Keywords: quant,finance,data,a-share,parquet
@@ -147,4 +147,4 @@ with ThreadPoolExecutor(max_workers=8) as pool:
 
 ## 文档
 
-完整文档请访问：https://www.quantmindai.cn/docs/sdk.html
+完整文档请访问：https://quantdb.quantmind.cloud/docs/sdk.html