quantdb-sdk 0.2.5__tar.gz → 0.2.6__tar.gz

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.6}/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.6] - 2026-07-27
+
+### Fixed
+- **适配服务端 CDN 直连下载（302 跳转）**：异步客户端（httpx 默认不跟随重定向）此前在服务端开启 302 直连后所有下载/同步接口失效，现已修复。
+- **凭证保护**：同步客户端此前跟随 302 时会把 `X-API-Key` 透传给 CDN 域；现两个客户端统一改为「手动处理 302 + 无鉴权头裸请求直连 CDN」，凭证只发给 QuantDB 网关。
+- 302 响应中的 COS ETag 回填至 CDN 响应，保证进程内 ETag 缓存与 If-None-Match 304 逻辑不受影响。
+
 ## [0.2.5] - 2026-07-26
 
 ### Security

{quantdb_sdk-0.2.5/quantdb_sdk.egg-info → quantdb_sdk-0.2.6}/PKG-INFO

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

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.6}/pyproject.toml

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

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.6}/quantdb_sdk/async_client.py

@@ -5,6 +5,7 @@ import io
 import os
 import re
 import sqlite3
+from contextlib import asynccontextmanager
 from typing import Any, Dict, List, Optional, Literal
 
 import httpx
@@ -25,6 +26,9 @@ from .errors import (
     ValidationError,
 )
 
+# 维护提示：每次发版必须与 pyproject.toml 版本号同步
+_USER_AGENT = "QuantDB-Python-SDK/0.2.6"
+
 
 class AsyncQuantDBClient:
     """QuantDB 异步客户端。
@@ -41,7 +45,7 @@ class AsyncQuantDBClient:
     ):
         self.api_host = validate_api_host(api_host)
         self.timeout = timeout
-        headers = {"User-Agent": "QuantDB-Python-SDK/0.2.5"}
+        headers = {"User-Agent": _USER_AGENT}
         if api_key:
             headers["X-API-Key"] = api_key
         elif token:
@@ -53,17 +57,49 @@ class AsyncQuantDBClient:
             headers=headers,
             timeout=httpx.Timeout(timeout, connect=5.0),
         )
+        # 裸客户端：跟随 302 直连 CDN 用，不携带任何鉴权头，避免凭证泄露给 CDN 域。
+        self._bare_client = httpx.AsyncClient(
+            headers={"User-Agent": _USER_AGENT},
+            timeout=httpx.Timeout(timeout, connect=5.0),
+        )
         # 进程内 parquet ETag 缓存：同对象（ETag 未变）不重复下载，避免重复计费。
         self._cache: Dict[str, Dict[str, Any]] = {}
 
     async def close(self) -> None:
         """关闭底层 httpx 客户端。"""
         await self.client.aclose()
+        await self._bare_client.aclose()
 
     def clear_cache(self) -> None:
         """清空进程内 Parquet 缓存（强制下次重新下载最新数据）。"""
         self._cache.clear()
 
+    @asynccontextmanager
+    async def _download_stream(self, params: Dict[str, Any], headers: Optional[Dict[str, str]] = None):
+        """下载专用流式请求：手动处理服务端 302 CDN 直连跳转。
+
+        服务端开启 CDN 直连后，/api/v1/data/download 预扣流量成功时返回
+        302 -> CDN 签名 URL。httpx 默认不跟随重定向；这里用不带鉴权头的
+        裸客户端直连 Location，鉴权头不会泄露给 CDN 域。
+        """
+        async with self.client.stream(
+            "GET", f"{self.api_host}/api/v1/data/download", params=params, headers=headers
+        ) as resp:
+            if resp.status_code not in (301, 302, 303, 307, 308):
+                yield resp
+                return
+            location = resp.headers.get("Location", "")
+            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
+            yield cdn_resp
+
     @staticmethod
     def _validate_layout(layout: str) -> Literal["auto", "v1", "v2"]:
         if layout not in {"auto", "v1", "v2"}:
@@ -398,9 +434,7 @@ class AsyncQuantDBClient:
         if object_key:
             params["object_key"] = object_key
 
-        async with self.client.stream(
-            "GET", f"{self.api_host}/api/v1/data/download", params=params
-        ) as resp:
+        async with self._download_stream(params) as resp:
             if resp.status_code != 200:
                 body = await resp.aread()
                 # 构造一个完整的 httpx.Response 用于错误解析，然后立即抛出
@@ -467,9 +501,7 @@ class AsyncQuantDBClient:
         req_headers = {}
         if cached and cached.get("etag"):
             req_headers["If-None-Match"] = cached["etag"]
-        async with self.client.stream(
-            "GET", f"{self.api_host}/api/v1/data/download", params=params, headers=req_headers
-        ) as resp:
+        async with self._download_stream(params, headers=req_headers) as resp:
             if resp.status_code == 304 and cached:
                 return cached["df"]
             if resp.status_code != 200:
@@ -567,7 +599,7 @@ class AsyncQuantDBClient:
                         if old and old[0] == obj.get("etag") and old[1] == obj.get("sha256") and os.path.exists(old[3]) and (expected_size is None or os.path.getsize(old[3]) == expected_size): continue
                         os.makedirs(os.path.dirname(target), exist_ok=True)
                         tmp, digest = target + ".part", hashlib.sha256()
-                        async with self.client.stream("GET", f"{self.api_host}/api/v1/data/download", params={"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v2", "object_key": key}) as resp:
+                        async with self._download_stream({"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v2", "object_key": key}) as resp:
                             if resp.status_code != 200:
                                 body = await resp.aread(); self._check_response(httpx.Response(resp.status_code, content=body)); raise QuantDBError("下载失败")
                             try:
@@ -595,7 +627,7 @@ class AsyncQuantDBClient:
                 os.makedirs(os.path.dirname(target), exist_ok=True)
                 tmp, written_size = target + ".part", 0
                 try:
-                    async with self.client.stream("GET", f"{self.api_host}/api/v1/data/download", params={"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")}) as resp:
+                    async with self._download_stream({"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")}) as resp:
                         if resp.status_code != 200:
                             body = await resp.aread(); self._check_response(httpx.Response(resp.status_code, content=body)); raise QuantDBError("下载失败")
                         with open(tmp, "wb") as fh:

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.6}/quantdb_sdk/client.py

@@ -13,11 +13,11 @@ import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
-from ._utils import (
-    SYNC_DATASET_CATEGORIES, bytes_to_gb, check_download_size, default_download_dir,
-    max_download_bytes, parse_filename_from_content_disposition, safe_filename, safe_join,
-    validate_api_host,
-)
+from ._utils import (
+    SYNC_DATASET_CATEGORIES, bytes_to_gb, check_download_size, default_download_dir,
+    max_download_bytes, parse_filename_from_content_disposition, safe_filename, safe_join,
+    validate_api_host,
+)
 from .errors import (
     AuthError,
     InsufficientTrafficError,
@@ -28,6 +28,9 @@ from .errors import (
     ValidationError,
 )
 
+# 维护提示：每次发版必须与 pyproject.toml 版本号同步
+_USER_AGENT = "QuantDB-Python-SDK/0.2.6"
+
 
 class QuantDBClient:
     """QuantDB 同步客户端。
@@ -45,14 +48,12 @@ class QuantDBClient:
         timeout: tuple = (5, 60),
         max_retries: int = 2,
     ):
-        self.api_host = validate_api_host(api_host)
+        self.api_host = validate_api_host(api_host)
         self.timeout = timeout
         self.token: Optional[str] = None
         self.headers: Dict[str, str] = {}
         self.session = requests.Session()
-        # User-Agent 中的版本与 pyproject.toml 同步，用于服务端日志归因
-        # 维护提示：每次版本号变化必须同步改这里（init 里的 __version__ 走 metadata 自动同步）
-        self.session.headers.update({"User-Agent": "QuantDB-Python-SDK/0.2.5"})
+        self.session.headers.update({"User-Agent": _USER_AGENT})
 
         if api_key:
             self.headers = {"X-API-Key": api_key}
@@ -98,6 +99,7 @@ class QuantDBClient:
         json: Optional[dict] = None,
         stream: bool = False,
         headers: Optional[dict] = None,
+        allow_redirects: bool = True,
     ) -> requests.Response:
         url = f"{self.api_host}{path}"
         resp = self.session.request(
@@ -108,6 +110,7 @@ class QuantDBClient:
             stream=stream,
             timeout=self.timeout,
             headers=headers,
+            allow_redirects=allow_redirects,
         )
         return resp
 
@@ -115,6 +118,38 @@ class QuantDBClient:
         resp = self._request("GET", path, params=params)
         return self._check_response(resp)
 
+    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 域，故禁用自动跟随，改用不带鉴权头的裸请求直连。
+        """
+        resp = self._request(
+            "GET", "/api/v1/data/download", params=params, stream=True,
+            headers=headers, allow_redirects=False,
+        )
+        if resp.status_code not in (301, 302, 303, 307, 308):
+            return resp
+        location = resp.headers.get("Location", "")
+        etag = resp.headers.get("ETag", "")
+        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
+        return cdn_resp
+
     def _post(self, path: str, json: Optional[dict] = None) -> dict:
         resp = self._request("POST", path, json=json)
         return self._check_response(resp)
@@ -486,38 +521,36 @@ class QuantDBClient:
         if object_key:
             params["object_key"] = object_key
 
-        resp = self._request(
-            "GET", "/api/v1/data/download", params=params, stream=True
-        )
+        resp = self._download_stream(params)
         if resp.status_code != 200:
             self._check_response(resp)
 
         fallback = f"{sub_category}.parquet"
         if symbol:
             fallback = f"{sub_category}_{symbol}.parquet"
-        filename = safe_filename(
-            parse_filename_from_content_disposition(resp.headers.get("Content-Disposition", ""), fallback),
-            safe_filename(fallback),
-        )
+        filename = safe_filename(
+            parse_filename_from_content_disposition(resp.headers.get("Content-Disposition", ""), fallback),
+            safe_filename(fallback),
+        )
 
         save_path = os.path.join(save_dir, filename)
         tmp_path = save_path + ".part"
-        maximum = max_download_bytes()
-        check_download_size(resp.headers.get("Content-Length"), maximum)
-        written = 0
-        try:
-            with open(tmp_path, "wb") as f:
-                for chunk in resp.iter_content(chunk_size=8192):
-                    if chunk:
-                        written += len(chunk)
-                        if written > maximum:
-                            raise ServerError(f"下载文件超过大小限制（{maximum} 字节）")
-                        f.write(chunk)
-            os.replace(tmp_path, save_path)
-        except Exception:
-            if os.path.exists(tmp_path):
-                os.remove(tmp_path)
-            raise
+        maximum = max_download_bytes()
+        check_download_size(resp.headers.get("Content-Length"), maximum)
+        written = 0
+        try:
+            with open(tmp_path, "wb") as f:
+                for chunk in resp.iter_content(chunk_size=8192):
+                    if chunk:
+                        written += len(chunk)
+                        if written > maximum:
+                            raise ServerError(f"下载文件超过大小限制（{maximum} 字节）")
+                        f.write(chunk)
+            os.replace(tmp_path, save_path)
+        except Exception:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+            raise
         return os.path.abspath(save_path)
 
     def load_as_df(
@@ -554,7 +587,7 @@ class QuantDBClient:
         headers = {}
         if cached and cached.get("etag"):
             headers["If-None-Match"] = cached["etag"]
-        resp = self._request("GET", "/api/v1/data/download", params=params, headers=headers, stream=True)
+        resp = self._download_stream(params, headers=headers)
         if resp.status_code == 304 and cached:
             return cached["df"]
         if resp.status_code != 200:
@@ -563,16 +596,16 @@ class QuantDBClient:
         # 命中缓存（ETag 未变）：复用已解析的 df，不重复消耗解析
         if cached and etag and cached.get("etag") == etag:
             return cached["df"]
-        maximum = max_download_bytes()
-        check_download_size(resp.headers.get("Content-Length"), maximum)
-        payload, written = io.BytesIO(), 0
-        for chunk in resp.iter_content(chunk_size=1024 * 1024):
-            if chunk:
-                written += len(chunk)
-                if written > maximum:
-                    raise ServerError(f"下载文件超过大小限制（{maximum} 字节）")
-                payload.write(chunk)
-        df = pd.read_parquet(payload)
+        maximum = max_download_bytes()
+        check_download_size(resp.headers.get("Content-Length"), maximum)
+        payload, written = io.BytesIO(), 0
+        for chunk in resp.iter_content(chunk_size=1024 * 1024):
+            if chunk:
+                written += len(chunk)
+                if written > maximum:
+                    raise ServerError(f"下载文件超过大小限制（{maximum} 字节）")
+                payload.write(chunk)
+        df = pd.read_parquet(payload)
         if etag:
             self._cache[cache_key] = {"etag": etag, "df": df}
         return df
@@ -589,12 +622,12 @@ class QuantDBClient:
 
         若文件不存在会先自动下载。
 
-        ``sql`` 仅接受 WHERE 条件字符串；SDK 固定查询下载的单个 Parquet 文件。
+        ``sql`` 仅接受 WHERE 条件字符串；SDK 固定查询下载的单个 Parquet 文件。
 
         安全限制：
             - 不允许分号（;），防止多语句注入
             - 不允许注释（-- 或 /* */），防止注释注入
-            - 不允许子查询、JOIN、外部表函数或任何数据修改语句
+            - 不允许子查询、JOIN、外部表函数或任何数据修改语句
         """
         file_path = self.download_file(
             category_id=category_id,
@@ -611,19 +644,19 @@ class QuantDBClient:
 
         # 安全检查：拒绝危险字符和关键字
         dangerous_keywords = [
-            ";", "--", "/*", "*/", "select", "from", "join", "union", "drop",
-            "delete", "insert", "update", "alter", "create", "exec", "execute",
-            "attach", "copy", "pragma", "install", "load", "read_", "http", "glob",
+            ";", "--", "/*", "*/", "select", "from", "join", "union", "drop",
+            "delete", "insert", "update", "alter", "create", "exec", "execute",
+            "attach", "copy", "pragma", "install", "load", "read_", "http", "glob",
         ]
         sql_upper = sql.upper()
         for kw in dangerous_keywords:
             if kw in sql_upper:
                 raise ValidationError(
                     f"SQL 包含危险关键字 '{kw}'，已被拒绝。"
-                    "query_local 仅支持针对已下载文件的 WHERE 条件。"
-                )
-        sql = f"SELECT * FROM '{clean_path}' WHERE {sql}"
-        return duckdb.query(sql).df()
+                    "query_local 仅支持针对已下载文件的 WHERE 条件。"
+                )
+        sql = f"SELECT * FROM '{clean_path}' WHERE {sql}"
+        return duckdb.query(sql).df()
 
     def get_local_warehouse(self, save_dir: Optional[str] = None) -> "DuckDBWarehouse":
         """获取 DuckDB 本地数据仓库实例，用于离线多表 SQL JOIN 查询。"""
@@ -656,12 +689,12 @@ class QuantDBClient:
                     for obj in release.get("objects", []):
                         key = self._normalise_release_key(obj["key"])
                         relative_path = obj.get("relative_path") or key
-                        target = safe_join(root, relative_path)
+                        target = safe_join(root, relative_path)
                         expected_size = obj.get("size")
                         old = state.execute("SELECT etag, sha256, size, path FROM objects WHERE key=?", (key,)).fetchone()
                         if old and old[0] == obj.get("etag") and old[1] == obj.get("sha256") and os.path.exists(old[3]) and (expected_size is None or os.path.getsize(old[3]) == expected_size):
                             continue
-                        resp = self._request("GET", "/api/v1/data/download", params={"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v2", "object_key": key}, stream=True)
+                        resp = self._download_stream({"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v2", "object_key": key})
                         if resp.status_code != 200:
                             self._check_response(resp)
                         os.makedirs(os.path.dirname(target), exist_ok=True)
@@ -694,12 +727,12 @@ class QuantDBClient:
             manifest = self._get("/api/v1/data/download/manifest", {"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1"})
             for obj in manifest.get("files", []):
                 key, relative_path = obj["key"], obj.get("relative_path") or obj["key"]
-                target = safe_join(root, relative_path)
+                target = safe_join(root, relative_path)
                 expected_size = obj.get("size")
                 old = state.execute("SELECT etag, size, path FROM objects WHERE key=?", (key,)).fetchone()
                 if old and old[0] == obj.get("etag") and os.path.exists(old[2]) and (expected_size is None or os.path.getsize(old[2]) == expected_size):
                     continue
-                resp = self._request("GET", "/api/v1/data/download", params={"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")}, stream=True)
+                resp = self._download_stream({"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")})
                 if resp.status_code != 200: self._check_response(resp)
                 os.makedirs(os.path.dirname(target), exist_ok=True)
                 tmp = target + ".part"

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.6/quantdb_sdk.egg-info}/PKG-INFO

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