quantdb-sdk 0.2.1__tar.gz → 0.2.2__tar.gz

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/CHANGELOG.md

@@ -3,6 +3,16 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [0.2.2] - 2026-07-26
+
+### Added
+- **全数据集增量同步**：`sync_dataset()` / `a_sync_dataset()` 覆盖基础、财务、ETF/可转债、行情、技术与 ML 子类；没有 V2 release 的数据集自动走 V1 Manifest。
+- **CLI 同步**：新增 `quantdb sync <api_key> <dataset> --save-dir <目录>`。
+
+### Fixed
+- **V1 强校验**：V1 Manifest 同步以 ETag + size 判断变更，并在原子落盘前验证实际字节数。
+- **同步/异步一致性**：异步 release 同步采用 `relative_path`，SQLite 同时记录对象大小，与同步客户端保持同构目录和恢复语义。
+
 ## [0.2.1] - 2026-07-26
 
 ### Fixed

{quantdb_sdk-0.2.1/quantdb_sdk.egg-info → quantdb_sdk-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.2.1
+Version: 0.2.2
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -104,6 +104,11 @@ history = client.download_file("1", "daily_forward", symbol="600519.SH", layout=
 
 # 以发布清单为 cursor 做原子化增量同步（含 V2 patch）
 result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
+
+# 财务、ETF/可转债等尚无 V2 release 的数据集自动按 V1 Manifest 增量同步，
+# 使用 ETag + size 校验；也可从命令行执行：
+# quantdb sync qdb_xxx balance --save-dir D:/quantdb-data
+financial = client.sync_dataset("balance", save_dir="D:/quantdb-data")
 ```
 
 ## 流量说明

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/README.md

@@ -67,6 +67,11 @@ history = client.download_file("1", "daily_forward", symbol="600519.SH", layout=
 
 # 以发布清单为 cursor 做原子化增量同步（含 V2 patch）
 result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
+
+# 财务、ETF/可转债等尚无 V2 release 的数据集自动按 V1 Manifest 增量同步，
+# 使用 ETag + size 校验；也可从命令行执行：
+# quantdb sync qdb_xxx balance --save-dir D:/quantdb-data
+financial = client.sync_dataset("balance", save_dir="D:/quantdb-data")
 ```
 
 ## 流量说明

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/pyproject.toml

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

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/quantdb_sdk/__init__.py

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

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/quantdb_sdk/__main__.py

@@ -39,6 +39,12 @@ def main() -> int:
     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（一般无需传入）")
+
     args = parser.parse_args()
 
     if not args.command:
@@ -66,6 +72,14 @@ def main() -> int:
             print(f"  订阅: {sub.get('status', 'none')}")
             return 0
 
+        if args.command == "sync":
+            result = client.sync_dataset(args.dataset, save_dir=args.save_dir, after_release=args.after_release)
+            print(f"同步完成: {result['dataset']} ({result['layout']})")
+            print(f"  新增/更新对象: {len(result['downloaded'])}")
+            if result.get("release_id"):
+                print(f"  Release: {result['release_id']}")
+            return 0
+
     except Exception as e:
         print(f"✗ 错误: {e}", file=sys.stderr)
         return 1

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/quantdb_sdk/_utils.py

@@ -5,9 +5,25 @@
 
 import os
 import re
+from typing import Dict
 from urllib.parse import unquote
 
 
+# ``sync_dataset`` 的统一数据集目录。V2 可用时走 release cursor；其余数据集
+# 自动使用 V1 Manifest 的 ETag + size 增量同步。
+SYNC_DATASET_CATEGORIES: Dict[str, str] = {
+    "daily_unadjusted": "1", "daily_forward": "1", "daily_backward": "1",
+    "index_daily": "1", "min1_kline": "1", "min5_kline": "1", "tick_data": "1",
+    "instrument_detail": "2", "sector_concept": "2", "index_weights": "2",
+    "trading_calendar": "2", "margin_trading": "2",
+    "balance": "3", "income": "3", "cashflow": "3", "capital": "3",
+    "holder_num": "3", "pershare_index": "3", "dividend_factors": "3",
+    "etf_pcf": "4", "convertible_bond": "4",
+    "valuation": "5", "technical_indicators": "5", "market_sentiment": "5",
+    "features_daily": "6", "l1_l2_factors": "6", "l2_factors": "6",
+}
+
+
 def default_download_dir() -> str:
     """返回默认下载目录。
 

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/quantdb_sdk/async_client.py

@@ -10,7 +10,7 @@ from typing import Any, Dict, List, Optional, Literal
 import httpx
 import pandas as pd
 
-from ._utils import bytes_to_gb, default_download_dir, parse_filename_from_content_disposition
+from ._utils import SYNC_DATASET_CATEGORIES, bytes_to_gb, default_download_dir, parse_filename_from_content_disposition
 from .errors import (
     AuthError,
     InsufficientTrafficError,
@@ -37,7 +37,7 @@ class AsyncQuantDBClient:
     ):
         self.api_host = api_host.rstrip("/")
         self.timeout = timeout
-        headers = {"User-Agent": "QuantDB-Python-SDK/0.2.1"}
+        headers = {"User-Agent": "QuantDB-Python-SDK/0.2.2"}
         if api_key:
             headers["X-API-Key"] = api_key
         elif token:
@@ -528,17 +528,13 @@ class AsyncQuantDBClient:
 
     async def a_sync_dataset(self, dataset: str, save_dir: Optional[str] = None, after_release: Optional[str] = None) -> Dict[str, Any]:
         """异步版 release 增量同步；状态格式与 ``sync_dataset`` 兼容。"""
-        category_map = {
-            "daily_unadjusted": "1", "daily_forward": "1", "daily_backward": "1", "index_daily": "1",
-            "min1_kline": "1", "min5_kline": "1", "margin_trading": "2", "valuation": "5",
-            "technical_indicators": "5", "market_sentiment": "5", "features_daily": "6",
-        }
-        if dataset not in category_map: raise ValidationError(f"不支持同步的数据集: {dataset}")
+        if dataset not in SYNC_DATASET_CATEGORIES: raise ValidationError(f"不支持同步的数据集: {dataset}")
         root = os.path.abspath(save_dir or default_download_dir()); os.makedirs(root, exist_ok=True)
         state = sqlite3.connect(os.path.join(root, "quantdb_sync.sqlite"))
-        state.execute("CREATE TABLE IF NOT EXISTS objects (key TEXT PRIMARY KEY, etag TEXT, sha256 TEXT, path TEXT, layout TEXT, dataset TEXT)")
+        state.execute("CREATE TABLE IF NOT EXISTS objects (key TEXT PRIMARY KEY, etag TEXT, sha256 TEXT, size INTEGER, path TEXT, layout TEXT, dataset TEXT)")
         cols = {row[1] for row in state.execute("PRAGMA table_info(objects)")}
         if "dataset" not in cols: state.execute("ALTER TABLE objects ADD COLUMN dataset TEXT")
+        if "size" not in cols: state.execute("ALTER TABLE objects ADD COLUMN size INTEGER")
         state.execute("CREATE TABLE IF NOT EXISTS releases (dataset TEXT PRIMARY KEY, release_id TEXT NOT NULL)")
         downloaded: List[str] = []
         try:
@@ -549,12 +545,14 @@ class AsyncQuantDBClient:
                 for release in releases:
                     for obj in release.get("objects", []):
                         key = self._normalise_release_key(obj["key"])
-                        target = os.path.join(root, *key.split("/"))
-                        old = state.execute("SELECT etag,sha256,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[2]): continue
+                        relative_path = obj.get("relative_path") or key
+                        target = os.path.join(root, *relative_path.split("/"))
+                        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
                         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": category_map[dataset], "sub_category": dataset, "layout": "v2", "object_key": key}) as resp:
+                        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:
                             if resp.status_code != 200:
                                 body = await resp.aread(); self._check_response(httpx.Response(resp.status_code, content=body)); raise QuantDBError("下载失败")
                             try:
@@ -563,24 +561,38 @@ class AsyncQuantDBClient:
                                         if chunk: fh.write(chunk); digest.update(chunk)
                                 actual = digest.hexdigest()
                                 if obj.get("sha256") and actual.lower() != obj["sha256"].lower(): raise ServerError("对象 SHA-256 校验失败")
+                                written_size = os.path.getsize(tmp)
+                                if expected_size is not None and written_size != expected_size: raise ServerError(f"对象大小校验失败：期望 {expected_size}，实际 {written_size}")
                                 os.replace(tmp, target)
                             except Exception:
                                 if os.path.exists(tmp): os.remove(tmp)
                                 raise
-                        state.execute("INSERT OR REPLACE INTO objects(key,etag,sha256,path,layout,dataset) VALUES(?,?,?,?,?,?)", (key, obj.get("etag"), actual, target, "v2_daily_partition", dataset)); downloaded.append(key)
+                        state.execute("INSERT OR REPLACE INTO objects(key,etag,sha256,size,path,layout,dataset) VALUES(?,?,?,?,?,?,?)", (key, obj.get("etag"), actual, written_size, target, "v2_daily_partition", dataset)); downloaded.append(key)
                     state.execute("INSERT OR REPLACE INTO releases(dataset,release_id) VALUES(?,?)", (dataset, release["release_id"])); state.commit()
                 return {"dataset": dataset, "layout": "v2_daily_partition", "downloaded": downloaded, "after_release": cursor, "release_id": releases[-1]["release_id"]}
             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": category_map[dataset], "sub_category": dataset, "layout": "v1"})).get("files", [])
+            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("/"))
-                old = state.execute("SELECT etag,path FROM objects WHERE key=?", (key,)).fetchone()
-                if old and old[0] == obj.get("etag") and os.path.exists(old[1]): continue
-                await self.a_download_file(category_map[dataset], dataset, symbol=obj.get("symbol"), save_dir=os.path.dirname(target), layout="v1")
-                # 下载文件名来自服务端，按清单目标路径归位以保证本地根目录同构。
-                source = os.path.join(os.path.dirname(target), os.path.basename(target))
-                if os.path.abspath(source) != os.path.abspath(target): os.replace(source, target)
-                state.execute("INSERT OR REPLACE INTO objects(key,etag,sha256,path,layout,dataset) VALUES(?,?,?,?,?,?)", (key, obj.get("etag"), "", target, "v1_symbol", dataset)); downloaded.append(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
+                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:
+                        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:
+                            async for chunk in resp.aiter_bytes(1024 * 1024):
+                                if chunk: fh.write(chunk)
+                    written_size = os.path.getsize(tmp)
+                    if expected_size is not None and written_size != expected_size: raise ServerError(f"对象大小校验失败：期望 {expected_size}，实际 {written_size}")
+                    os.replace(tmp, target)
+                except Exception:
+                    if os.path.exists(tmp): os.remove(tmp)
+                    raise
+                state.execute("INSERT OR REPLACE INTO objects(key,etag,sha256,size,path,layout,dataset) VALUES(?,?,?,?,?,?,?)", (key, obj.get("etag"), "", written_size, target, "v1_symbol", dataset)); downloaded.append(key)
             state.commit(); return {"dataset": dataset, "layout": "v1_symbol", "downloaded": downloaded, "after_release": cursor}
         finally:
             state.close()

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/quantdb_sdk/client.py

@@ -13,7 +13,7 @@ import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
-from ._utils import bytes_to_gb, default_download_dir, parse_filename_from_content_disposition
+from ._utils import SYNC_DATASET_CATEGORIES, bytes_to_gb, default_download_dir, parse_filename_from_content_disposition
 from .errors import (
     AuthError,
     InsufficientTrafficError,
@@ -48,7 +48,7 @@ class QuantDBClient:
         self.session = requests.Session()
         # User-Agent 中的版本与 pyproject.toml 同步，用于服务端日志归因
         # 维护提示：每次版本号变化必须同步改这里（init 里的 __version__ 走 metadata 自动同步）
-        self.session.headers.update({"User-Agent": "QuantDB-Python-SDK/0.2.1"})
+        self.session.headers.update({"User-Agent": "QuantDB-Python-SDK/0.2.2"})
 
         if api_key:
             self.headers = {"X-API-Key": api_key}
@@ -622,18 +622,14 @@ class QuantDBClient:
         root = os.path.abspath(save_dir or default_download_dir())
         os.makedirs(root, exist_ok=True)
         state = sqlite3.connect(os.path.join(root, "quantdb_sync.sqlite"))
-        state.execute("CREATE TABLE IF NOT EXISTS objects (key TEXT PRIMARY KEY, etag TEXT, sha256 TEXT, path TEXT, layout TEXT, dataset TEXT)")
+        state.execute("CREATE TABLE IF NOT EXISTS objects (key TEXT PRIMARY KEY, etag TEXT, sha256 TEXT, size INTEGER, path TEXT, layout TEXT, dataset TEXT)")
         cols = {row[1] for row in state.execute("PRAGMA table_info(objects)")}
         if "dataset" not in cols:
             state.execute("ALTER TABLE objects ADD COLUMN dataset TEXT")
+        if "size" not in cols:
+            state.execute("ALTER TABLE objects ADD COLUMN size INTEGER")
         state.execute("CREATE TABLE IF NOT EXISTS releases (dataset TEXT PRIMARY KEY, release_id TEXT NOT NULL)")
-        category_map = {
-            "daily_unadjusted": "1", "daily_forward": "1", "daily_backward": "1",
-            "index_daily": "1", "min1_kline": "1", "min5_kline": "1",
-            "margin_trading": "2", "valuation": "5", "technical_indicators": "5",
-            "market_sentiment": "5", "features_daily": "6",
-        }
-        if dataset not in category_map:
+        if dataset not in SYNC_DATASET_CATEGORIES:
             raise ValidationError(f"不支持同步的数据集: {dataset}")
 
         downloaded: List[str] = []
@@ -649,10 +645,11 @@ class QuantDBClient:
                         key = self._normalise_release_key(obj["key"])
                         relative_path = obj.get("relative_path") or key
                         target = os.path.join(root, *relative_path.split("/"))
-                        old = state.execute("SELECT etag, sha256, 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[2]):
+                        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": category_map[dataset], "sub_category": dataset, "layout": "v2", "object_key": key}, stream=True)
+                        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)
                         if resp.status_code != 200:
                             self._check_response(resp)
                         os.makedirs(os.path.dirname(target), exist_ok=True)
@@ -663,13 +660,16 @@ class QuantDBClient:
                                     if chunk:
                                         fh.write(chunk); digest.update(chunk)
                             actual = digest.hexdigest()
+                            written_size = os.path.getsize(tmp)
                             if obj.get("sha256") and actual.lower() != obj["sha256"].lower():
                                 raise ServerError("对象 SHA-256 校验失败")
+                            if expected_size is not None and written_size != expected_size:
+                                raise ServerError(f"对象大小校验失败：期望 {expected_size}，实际 {written_size}")
                             os.replace(tmp, target)
                         except Exception:
                             if os.path.exists(tmp): os.remove(tmp)
                             raise
-                        state.execute("INSERT OR REPLACE INTO objects(key,etag,sha256,path,layout,dataset) VALUES(?,?,?,?,?,?)", (key, obj.get("etag"), actual, target, "v2_daily_partition", dataset))
+                        state.execute("INSERT OR REPLACE INTO objects(key,etag,sha256,size,path,layout,dataset) VALUES(?,?,?,?,?,?,?)", (key, obj.get("etag"), actual, written_size, target, "v2_daily_partition", dataset))
                         downloaded.append(key)
                     # 仅在该 release 的所有对象成功落盘和校验后提交 cursor。
                     state.execute("INSERT OR REPLACE INTO releases(dataset,release_id) VALUES(?,?)", (dataset, release_id))
@@ -679,14 +679,15 @@ class QuantDBClient:
             if persisted:
                 return {"dataset": dataset, "layout": "v2_daily_partition", "downloaded": [], "after_release": cursor, "release_id": persisted[0]}
 
-            manifest = self._get("/api/v1/data/download/manifest", {"category_id": category_map[dataset], "sub_category": dataset, "layout": "v1"})
+            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 = os.path.join(root, *relative_path.split("/"))
-                old = state.execute("SELECT etag, path FROM objects WHERE key=?", (key,)).fetchone()
-                if old and old[0] == obj.get("etag") and os.path.exists(old[1]):
+                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": category_map[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")}, stream=True)
+                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)
                 if resp.status_code != 200: self._check_response(resp)
                 os.makedirs(os.path.dirname(target), exist_ok=True)
                 tmp = target + ".part"
@@ -694,11 +695,14 @@ class QuantDBClient:
                     with open(tmp, "wb") as fh:
                         for chunk in resp.iter_content(1024 * 1024):
                             if chunk: fh.write(chunk)
+                    written_size = os.path.getsize(tmp)
+                    if expected_size is not None and written_size != expected_size:
+                        raise ServerError(f"对象大小校验失败：期望 {expected_size}，实际 {written_size}")
                     os.replace(tmp, target)
                 except Exception:
                     if os.path.exists(tmp): os.remove(tmp)
                     raise
-                state.execute("INSERT OR REPLACE INTO objects(key,etag,sha256,path,layout,dataset) VALUES(?,?,?,?,?,?)", (key, obj.get("etag"), "", target, "v1_symbol", dataset))
+                state.execute("INSERT OR REPLACE INTO objects(key,etag,sha256,size,path,layout,dataset) VALUES(?,?,?,?,?,?,?)", (key, obj.get("etag"), "", written_size, target, "v1_symbol", dataset))
                 downloaded.append(key)
             state.commit()
             return {"dataset": dataset, "layout": "v1_symbol", "downloaded": downloaded, "after_release": cursor}

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2/quantdb_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.2.1
+Version: 0.2.2
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -104,6 +104,11 @@ history = client.download_file("1", "daily_forward", symbol="600519.SH", layout=
 
 # 以发布清单为 cursor 做原子化增量同步（含 V2 patch）
 result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
+
+# 财务、ETF/可转债等尚无 V2 release 的数据集自动按 V1 Manifest 增量同步，
+# 使用 ETag + size 校验；也可从命令行执行：
+# quantdb sync qdb_xxx balance --save-dir D:/quantdb-data
+financial = client.sync_dataset("balance", save_dir="D:/quantdb-data")
 ```
 
 ## 流量说明

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/tests/test_async_client.py

@@ -64,6 +64,19 @@ async def test_a_sync_dataset_uses_release_cursor(tmp_path):
     assert parse_qs(urlparse(str(route.calls[0].request.url)).query)["object_key"] == ["1_kline_data/daily_forward/dt=20260726/data.parquet"]
 
 
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_sync_financial_v1_validates_manifest_size(tmp_path):
+    payload = b"financial-parquet"
+    respx.get(f"{API_HOST}/api/v1/data/releases").mock(return_value=httpx.Response(200, json={"releases": []}))
+    respx.get(f"{API_HOST}/api/v1/data/download/manifest").mock(return_value=httpx.Response(200, json={"files": [{"key": "3_financial_data/balance/600000.SH.parquet", "relative_path": "3_financial_data/balance/600000.SH.parquet", "symbol": "600000.SH", "etag": "v1-etag", "size": len(payload)}]}))
+    respx.get(f"{API_HOST}/api/v1/data/download").mock(return_value=httpx.Response(200, content=payload))
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        result = await client.a_sync_dataset("balance", str(tmp_path))
+    assert result["layout"] == "v1_symbol"
+    assert (tmp_path / "3_financial_data" / "balance" / "600000.SH.parquet").read_bytes() == payload
+
+
 @pytest.mark.asyncio
 @respx.mock
 async def test_a_auth_error_raises_auth_error():

{quantdb_sdk-0.2.1 → quantdb_sdk-0.2.2}/tests/test_client.py

@@ -8,6 +8,7 @@ import pytest
 import responses
 
 from quantdb_sdk import AuthError, InsufficientTrafficError, QuantDBClient
+from quantdb_sdk.errors import ServerError
 
 
 API_HOST = "http://localhost:5000"
@@ -90,6 +91,35 @@ def test_sync_dataset_uses_release_cursor_and_object_key(tmp_path):
     assert params["object_key"] == ["1_kline_data/daily_forward/dt=20260726/data.parquet"]
 
 
+@responses.activate
+def test_sync_financial_v1_validates_manifest_size(tmp_path):
+    payload = b"financial-parquet"
+    responses.get(f"{API_HOST}/api/v1/data/releases", json={"releases": []}, status=200)
+    responses.get(
+        f"{API_HOST}/api/v1/data/download/manifest",
+        json={"files": [{"key": "3_financial_data/balance/600000.SH.parquet", "relative_path": "3_financial_data/balance/600000.SH.parquet", "symbol": "600000.SH", "etag": "v1-etag", "size": len(payload)}]},
+        status=200,
+    )
+    responses.get(f"{API_HOST}/api/v1/data/download", body=payload, status=200)
+    result = QuantDBClient(api_host=API_HOST, api_key="test-key").sync_dataset("balance", str(tmp_path))
+    assert result["layout"] == "v1_symbol"
+    assert (tmp_path / "3_financial_data" / "balance" / "600000.SH.parquet").read_bytes() == payload
+
+
+@responses.activate
+def test_sync_v1_size_failure_does_not_keep_partial_file(tmp_path):
+    responses.get(f"{API_HOST}/api/v1/data/releases", json={"releases": []}, status=200)
+    responses.get(
+        f"{API_HOST}/api/v1/data/download/manifest",
+        json={"files": [{"key": "3_financial_data/balance/600000.SH.parquet", "symbol": "600000.SH", "etag": "v1-etag", "size": 999}]},
+        status=200,
+    )
+    responses.get(f"{API_HOST}/api/v1/data/download", body=b"short", status=200)
+    with pytest.raises(ServerError):
+        QuantDBClient(api_host=API_HOST, api_key="test-key").sync_dataset("balance", str(tmp_path))
+    assert not list(tmp_path.rglob("*.part"))
+
+
 @responses.activate
 def test_auth_error_raises_auth_error():
     responses.get(