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

{quantdb_sdk-0.2.4 → quantdb_sdk-0.2.5}/CHANGELOG.md

@@ -3,6 +3,17 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [0.2.5] - 2026-07-26
+
+### Security
+- 下载响应文件名与 release/Manifest 相对路径均限制在指定下载目录内，防止路径穿越。
+- 公网 API Host 强制 HTTPS；CLI 改从环境变量读取 API Key，避免密钥出现在命令历史和进程参数中。
+- 下载增加单文件大小上限（默认 2 GiB，可通过 `QUANTDB_MAX_DOWNLOAD_BYTES` 配置）。
+- `query_local()` / `a_query_local()` 只接受 WHERE 条件，拒绝完整 SQL、JOIN 和外部表函数。
+
+### Documentation
+- 更新官网 SDK 文档：并发下载建议、V1/V2 选择、安全配置与异常处理。
+
 ## [0.2.4] - 2026-07-26
 
 ### Fixed

{quantdb_sdk-0.2.4 → quantdb_sdk-0.2.5}/MANIFEST.in

@@ -1,5 +1,5 @@
-include README.md
-include LICENSE
-include CHANGELOG.md
-include pyproject.toml
-recursive-include quantdb_sdk *.py *.typed
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+recursive-include quantdb_sdk *.py *.typed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.2.4
+Version: 0.2.5
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -111,6 +111,31 @@ result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
 financial = client.sync_dataset("balance", save_dir="D:/quantdb-data")
 ```
 
+### 加速批量下载：建议从 8 个工作线程开始
+
+`sync_dataset()` 单次调用会按发布顺序串行下载，以保证本地 SQLite 同步状态和 release cursor 一致。
+当需要下载多个独立标的或文件时，可由调用方并行调度；建议先使用 **8 个工作线程**，再结合网络带宽、磁盘写入能力和账户流量配额调整。
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from quantdb_sdk import QuantDBClient
+
+API_KEY = "qdb_xxx..."
+symbols = ["600519.SH", "000001.SZ", "600036.SH"]
+
+def download_one(symbol: str) -> str:
+    # 每个 worker 使用独立客户端，避免跨线程共享 HTTP Session。
+    with_client = QuantDBClient(api_key=API_KEY)
+    return with_client.download_file(
+        "1", "daily_forward", symbol=symbol, save_dir="D:/quantdb-data"
+    )
+
+with ThreadPoolExecutor(max_workers=8) as pool:
+    files = list(pool.map(download_one, symbols))
+```
+
+不要对相同 `save_dir` 并行调用多个 `sync_dataset()`：它们会共同写入 `quantdb_sync.sqlite`，可能产生锁竞争。批量同步本身仍建议一次一个数据集执行。
+
 ## 流量说明
 
 免费注册用户获赠 100 MB 一次性体验流量；订阅用户每月含 30 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。

{quantdb_sdk-0.2.4 → quantdb_sdk-0.2.5}/README.md

@@ -73,8 +73,33 @@ result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
 # quantdb sync qdb_xxx balance --save-dir D:/quantdb-data
 financial = client.sync_dataset("balance", save_dir="D:/quantdb-data")
 ```
+
+### 加速批量下载：建议从 8 个工作线程开始
+
+`sync_dataset()` 单次调用会按发布顺序串行下载，以保证本地 SQLite 同步状态和 release cursor 一致。
+当需要下载多个独立标的或文件时，可由调用方并行调度；建议先使用 **8 个工作线程**，再结合网络带宽、磁盘写入能力和账户流量配额调整。
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from quantdb_sdk import QuantDBClient
+
+API_KEY = "qdb_xxx..."
+symbols = ["600519.SH", "000001.SZ", "600036.SH"]
+
+def download_one(symbol: str) -> str:
+    # 每个 worker 使用独立客户端，避免跨线程共享 HTTP Session。
+    with_client = QuantDBClient(api_key=API_KEY)
+    return with_client.download_file(
+        "1", "daily_forward", symbol=symbol, save_dir="D:/quantdb-data"
+    )
+
+with ThreadPoolExecutor(max_workers=8) as pool:
+    files = list(pool.map(download_one, symbols))
+```
+
+不要对相同 `save_dir` 并行调用多个 `sync_dataset()`：它们会共同写入 `quantdb_sync.sqlite`，可能产生锁竞争。批量同步本身仍建议一次一个数据集执行。
 
-## 流量说明
+## 流量说明
 
 免费注册用户获赠 100 MB 一次性体验流量；订阅用户每月含 30 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。
 

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

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

{quantdb_sdk-0.2.4 → quantdb_sdk-0.2.5}/quantdb_sdk/__init__.py

@@ -5,7 +5,7 @@ try:
     # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
     __version__ = version("quantdb-sdk")
 except ImportError:
-    __version__ = "0.2.4"
+    __version__ = "0.2.5"
 
 from .async_client import AsyncQuantDBClient
 from .client import DuckDBWarehouse, QuantDBClient

{quantdb_sdk-0.2.4 → quantdb_sdk-0.2.5}/quantdb_sdk/__main__.py

@@ -3,10 +3,11 @@
 提供快速验证和诊断功能：
   python -m quantdb --version
   python -m quantdb --help
-  python -m quantdb check <api_key>  # 验证 API Key 是否有效
+  QUANTDB_API_KEY=qdb_xxx quantdb check  # 验证 API Key 是否有效
 """
 
 import argparse
+import os
 import sys
 
 from . import __version__
@@ -28,19 +29,21 @@ def main() -> int:
         default="https://quantdb.quantmind.cloud",
         help="API 服务地址 (默认: https://quantdb.quantmind.cloud)",
     )
+    parser.add_argument(
+        "--api-key-env",
+        default="QUANTDB_API_KEY",
+        help="保存 API Key 的环境变量名 (默认: QUANTDB_API_KEY)",
+    )
 
     subparsers = parser.add_subparsers(dest="command", help="可用命令")
 
     # check 命令：验证 API Key
     check_parser = subparsers.add_parser("check", help="验证 API Key 是否有效")
-    check_parser.add_argument("api_key", help="要验证的 API Key")
 
     # usage 命令：查询用量
     usage_parser = subparsers.add_parser("usage", help="查询账户用量和订阅状态")
-    usage_parser.add_argument("api_key", help="API Key")
 
     sync_parser = subparsers.add_parser("sync", help="以 release/Manifest 增量同步一个数据集")
-    sync_parser.add_argument("api_key", help="API Key")
     sync_parser.add_argument("dataset", help="数据集，如 daily_forward、balance、etf_pcf")
     sync_parser.add_argument("--save-dir", default=None, help="本地同步根目录")
     sync_parser.add_argument("--after-release", default=None, help="覆盖本地 release cursor（一般无需传入）")
@@ -51,8 +54,12 @@ def main() -> int:
         parser.print_help()
         return 0
 
+    api_key = os.getenv(args.api_key_env)
+    if not api_key:
+        parser.error(f"请先设置 API Key 环境变量 {args.api_key_env}")
+
     try:
-        client = QuantDBClient(api_host=args.api_host, api_key=args.api_key)
+        client = QuantDBClient(api_host=args.api_host, api_key=api_key)
 
         if args.command == "check":
             me = client.get_me()

{quantdb_sdk-0.2.4 → quantdb_sdk-0.2.5}/quantdb_sdk/_utils.py

@@ -5,8 +5,8 @@
 
 import os
 import re
-from typing import Dict
-from urllib.parse import unquote
+from typing import Dict, Optional
+from urllib.parse import unquote, urlparse
 
 
 # ``sync_dataset`` 的统一数据集目录。V2 可用时走 release cursor；其余数据集
@@ -72,6 +72,58 @@ def parse_filename_from_content_disposition(value: str, fallback: str) -> str:
     return fallback
 
 
+def safe_filename(filename: str, fallback: str = "download.parquet") -> str:
+    """Return one safe filename, using *fallback* for untrusted input."""
+    candidate = filename.strip()
+    if (not candidate or candidate in {".", ".."} or "/" in candidate
+            or "\\" in candidate or "\x00" in candidate
+            or re.match(r"^[A-Za-z]:", candidate)):
+        return fallback
+    return candidate
+
+
+def safe_join(root: str, relative_path: str) -> str:
+    """Join an untrusted manifest path and prove it remains below *root*."""
+    if (not isinstance(relative_path, str) or not relative_path or "\\" in relative_path
+            or relative_path.startswith("/") or re.match(r"^[A-Za-z]:", relative_path)):
+        raise ValueError("发布清单包含非法路径")
+    parts = relative_path.split("/")
+    if any(part in {"", ".", ".."} for part in parts):
+        raise ValueError("发布清单包含路径穿越")
+    root_abs = os.path.abspath(root)
+    target = os.path.abspath(os.path.join(root_abs, *parts))
+    if os.path.commonpath([root_abs, target]) != root_abs:
+        raise ValueError("发布清单路径超出同步目录")
+    return target
+
+
+def validate_api_host(api_host: str) -> str:
+    """Require HTTPS except for local development/test loopback endpoints."""
+    host = api_host.rstrip("/")
+    parsed = urlparse(host)
+    if parsed.scheme == "https" and parsed.netloc:
+        return host
+    if parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}:
+        return host
+    raise ValueError("api_host 必须为 HTTPS 地址；仅 localhost 可使用 HTTP")
+
+
+def max_download_bytes() -> int:
+    """Configured response cap; default 2 GiB protects memory and disk."""
+    try:
+        value = int(os.getenv("QUANTDB_MAX_DOWNLOAD_BYTES", str(2 * 1024 ** 3)))
+    except ValueError as exc:
+        raise ValueError("QUANTDB_MAX_DOWNLOAD_BYTES 必须是正整数") from exc
+    if value <= 0:
+        raise ValueError("QUANTDB_MAX_DOWNLOAD_BYTES 必须大于 0")
+    return value
+
+
+def check_download_size(content_length: Optional[str], maximum: int) -> None:
+    if content_length and content_length.isdigit() and int(content_length) > maximum:
+        raise ValueError(f"下载文件超过大小限制（{maximum} 字节）")
+
+
 def bytes_to_gb(n: int) -> float:
     """将字节数转换为 GB（1024 进制）。
 

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

@@ -10,7 +10,11 @@ from typing import Any, Dict, List, Optional, Literal
 import httpx
 import pandas as pd
 
-from ._utils import SYNC_DATASET_CATEGORIES, bytes_to_gb, default_download_dir, parse_filename_from_content_disposition
+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,
@@ -35,9 +39,9 @@ class AsyncQuantDBClient:
         token: Optional[str] = None,
         timeout: float = 60.0,
     ):
-        self.api_host = api_host.rstrip("/")
+        self.api_host = validate_api_host(api_host)
         self.timeout = timeout
-        headers = {"User-Agent": "QuantDB-Python-SDK/0.2.4"}
+        headers = {"User-Agent": "QuantDB-Python-SDK/0.2.5"}
         if api_key:
             headers["X-API-Key"] = api_key
         elif token:
@@ -411,15 +415,26 @@ class AsyncQuantDBClient:
             fallback = f"{sub_category}.parquet"
             if symbol:
                 fallback = f"{sub_category}_{symbol}.parquet"
-            filename = parse_filename_from_content_disposition(cd, fallback)
+            filename = safe_filename(parse_filename_from_content_disposition(cd, fallback), safe_filename(fallback))
 
             save_path = os.path.join(save_dir, filename)
             tmp_path = save_path + ".part"
-            with open(tmp_path, "wb") as f:
-                async for chunk in resp.aiter_bytes(chunk_size=8192):
-                    if chunk:
-                        f.write(chunk)
-            os.replace(tmp_path, save_path)
+            maximum = max_download_bytes()
+            check_download_size(resp.headers.get("Content-Length"), maximum)
+            written = 0
+            try:
+                with open(tmp_path, "wb") as f:
+                    async for chunk in resp.aiter_bytes(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)
 
     async def a_load_as_df(
@@ -452,17 +467,27 @@ class AsyncQuantDBClient:
         req_headers = {}
         if cached and cached.get("etag"):
             req_headers["If-None-Match"] = cached["etag"]
-        resp = await self.client.get(
-            f"{self.api_host}/api/v1/data/download", params=params, headers=req_headers
-        )
-        if resp.status_code == 304 and cached:
-            return cached["df"]
-        if resp.status_code != 200:
-            self._check_response(resp)
-        etag = resp.headers.get("ETag") or ""
-        if cached and etag and cached.get("etag") == etag:
-            return cached["df"]
-        df = pd.read_parquet(io.BytesIO(resp.content))
+        async with self.client.stream(
+            "GET", f"{self.api_host}/api/v1/data/download", params=params, headers=req_headers
+        ) as resp:
+            if resp.status_code == 304 and cached:
+                return cached["df"]
+            if resp.status_code != 200:
+                body = await resp.aread()
+                self._check_response(httpx.Response(resp.status_code, content=body))
+            etag = resp.headers.get("ETag") or ""
+            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
+            async for chunk in resp.aiter_bytes(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
@@ -480,13 +505,12 @@ class AsyncQuantDBClient:
         若文件不存在会先自动下载。
 
         sql 支持两种写法：
-            1. 完整 SELECT 语句（必须包含 FROM 子句，表名会被替换为 parquet 路径）
-            2. 纯 WHERE 条件字符串（不含 FROM 时自动拼装为 SELECT * FROM <path> WHERE <条件>）
+            1. 仅支持纯 WHERE 条件字符串，SDK 固定查询已下载的 Parquet 文件
 
         安全限制：
             - 不允许分号（;），防止多语句注入
             - 不允许注释（-- 或 /* */），防止注释注入
-            - 不允许 UNION / DROP / DELETE / INSERT / UPDATE / ALTER / CREATE / EXEC / EXECUTE
+            - 不允许子查询、JOIN、外部表函数或任何数据修改语句
         """
         file_path = await self.a_download_file(
             category_id=category_id,
@@ -503,27 +527,18 @@ class AsyncQuantDBClient:
 
         # 安全检查：拒绝危险字符和关键字
         dangerous_keywords = [
-            ";", "--", "/*", "*/", "union", "drop", "delete",
-            "insert", "update", "alter", "create", "exec", "execute",
+            ";", "--", "/*", "*/", "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}'，已被拒绝。"
-                    "a_query_local 仅支持 SELECT 查询，不支持数据修改或联合查询。"
+                    "a_query_local 仅支持针对已下载文件的 WHERE 条件。"
                 )
-
-        if "FROM" in sql_upper:
-            sql = re.sub(
-                r"FROM\s+[`\"\']?\w+[`\"\']?",
-                f"FROM '{clean_path}'",
-                sql,
-                count=1,
-                flags=re.IGNORECASE,
-            )
-        else:
-            sql = f"SELECT * FROM '{clean_path}' WHERE {sql}"
+        sql = f"SELECT * FROM '{clean_path}' WHERE {sql}"
         return duckdb.query(sql).df()
 
     async def a_sync_dataset(self, dataset: str, save_dir: Optional[str] = None, after_release: Optional[str] = None) -> Dict[str, Any]:
@@ -546,7 +561,7 @@ class AsyncQuantDBClient:
                     for obj in release.get("objects", []):
                         key = self._normalise_release_key(obj["key"])
                         relative_path = obj.get("relative_path") or key
-                        target = os.path.join(root, *relative_path.split("/"))
+                        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
@@ -573,7 +588,7 @@ class AsyncQuantDBClient:
             if persisted: return {"dataset": dataset, "layout": "v2_daily_partition", "downloaded": [], "after_release": cursor, "release_id": persisted[0]}
             files = (await self._get("/api/v1/data/download/manifest", {"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1"})).get("files", [])
             for obj in files:
-                key, target = obj["key"], os.path.join(root, *(obj.get("relative_path") or obj["key"]).split("/"))
+                key, target = obj["key"], safe_join(root, obj.get("relative_path") or obj["key"])
                 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