quantdb-sdk 0.1.4__tar.gz → 0.2.0__tar.gz

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0}/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.0] - 2026-07-26
+
+### Added
+- **V1/V2 布局兼容**：同步与异步客户端的下载、Manifest、DataFrame、K 线和 Tick 接口均支持 `layout="auto" | "v1" | "v2"`。
+- **V2 release 增量同步**：`sync_dataset()` / `a_sync_dataset()` 使用发布 cursor，同步 daily 与 patch 对象；文件 SHA-256 校验和原子落盘成功后才推进 cursor。
+
+### Changed
+- `query_kline()` 在给出日期范围时优先 V2 日切片；V2 覆盖缺日时自动模式整体回退 V1，显式 V2 则返回覆盖错误。未给日期范围时保持 V1 全历史行为。
+- 下载接口支持 ETag 条件请求；服务端命中 `304 Not Modified` 时不传输对象正文、不扣下载流量。
+
 ## [0.1.4] - 2026-07-25
 
 ### Fixed

{quantdb_sdk-0.1.4/quantdb_sdk.egg-info → quantdb_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.1.4
+Version: 0.2.0
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -88,6 +88,24 @@ client = QuantDBClient(username="admin", password="admin123")
 - **账户管理**：查询用户信息、用量、API Key、订阅与订单。
 - **异步客户端**：基于 httpx，适用于 asyncio 量化框架。
 
+## V1 / V2 数据布局
+
+COS 同时保留 V1（按股票历史文件）和 V2（按交易日全市场分区）。所有下载相关接口均可传入
+`layout="auto" | "v1" | "v2"`。默认 `auto` 的规则是：给出 K 线日期范围时优先 V2；若任一
+交易日没有 V2 分区，则整次请求回退 V1，绝不混合两种口径；未给日期范围时读取 V1 全历史文件。
+
+```python
+# 按日期范围优先 V2；覆盖不完整时自动回退 V1
+df = client.query_kline("600519.SH", start_date="2026-07-01", end_date="2026-07-24")
+
+# 强制指定物理布局；layout="v2" 缺日时会明确报错
+latest = client.download_file("1", "daily_forward", trade_date="2026-07-24", layout="v2")
+history = client.download_file("1", "daily_forward", symbol="600519.SH", layout="v1")
+
+# 以发布清单为 cursor 做原子化增量同步（含 V2 patch）
+result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
+```
+
 ## 流量说明
 
 免费注册用户获赠 100 MB 一次性体验流量；订阅用户每月含 30 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0}/README.md

@@ -43,13 +43,31 @@ print(df.head())
 client = QuantDBClient(username="admin", password="admin123")
 ```
 
-## 核心功能
+## 核心功能
 
 - **数据查询**：K 线、Tick 通过下载 Parquet 切片后客户端解析（消耗流量）；股票列表、交易日历、元数据走网关 JSON（不计流量）。
 - **数据下载**：Parquet 文件下载或直读 DataFrame，计入订阅流量。
 - **本地分析**：基于 DuckDB 对本地 Parquet 执行 SQL。
 - **账户管理**：查询用户信息、用量、API Key、订阅与订单。
-- **异步客户端**：基于 httpx，适用于 asyncio 量化框架。
+- **异步客户端**：基于 httpx，适用于 asyncio 量化框架。
+
+## V1 / V2 数据布局
+
+COS 同时保留 V1（按股票历史文件）和 V2（按交易日全市场分区）。所有下载相关接口均可传入
+`layout="auto" | "v1" | "v2"`。默认 `auto` 的规则是：给出 K 线日期范围时优先 V2；若任一
+交易日没有 V2 分区，则整次请求回退 V1，绝不混合两种口径；未给日期范围时读取 V1 全历史文件。
+
+```python
+# 按日期范围优先 V2；覆盖不完整时自动回退 V1
+df = client.query_kline("600519.SH", start_date="2026-07-01", end_date="2026-07-24")
+
+# 强制指定物理布局；layout="v2" 缺日时会明确报错
+latest = client.download_file("1", "daily_forward", trade_date="2026-07-24", layout="v2")
+history = client.download_file("1", "daily_forward", symbol="600519.SH", layout="v1")
+
+# 以发布清单为 cursor 做原子化增量同步（含 V2 patch）
+result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
+```
 
 ## 流量说明
 

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0}/pyproject.toml

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

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0}/quantdb_sdk/__init__.py

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

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0}/quantdb_sdk/async_client.py

@@ -1,9 +1,11 @@
 """QuantDB 异步 Python SDK（基于 httpx）。"""
 
+import hashlib
 import io
 import os
 import re
-from typing import Any, Dict, List, Optional
+import sqlite3
+from typing import Any, Dict, List, Optional, Literal
 
 import httpx
 import pandas as pd
@@ -35,7 +37,7 @@ class AsyncQuantDBClient:
     ):
         self.api_host = api_host.rstrip("/")
         self.timeout = timeout
-        headers = {"User-Agent": "QuantDB-Python-SDK/0.1.4"}
+        headers = {"User-Agent": "QuantDB-Python-SDK/0.2.0"}
         if api_key:
             headers["X-API-Key"] = api_key
         elif token:
@@ -58,6 +60,30 @@ class AsyncQuantDBClient:
         """清空进程内 Parquet 缓存（强制下次重新下载最新数据）。"""
         self._cache.clear()
 
+    @staticmethod
+    def _validate_layout(layout: str) -> Literal["auto", "v1", "v2"]:
+        if layout not in {"auto", "v1", "v2"}:
+            raise ValidationError("layout 仅支持 auto、v1 或 v2")
+        return layout  # type: ignore[return-value]
+
+    @staticmethod
+    def _normalise_kline(df: pd.DataFrame, start_date: Optional[str], end_date: Optional[str], fields: str, limit: Optional[int]) -> pd.DataFrame:
+        if "time" in df.columns:
+            dt = pd.to_datetime(df["time"], errors="coerce")
+        elif "trade_date" in df.columns:
+            dt = pd.to_datetime(df["trade_date"], errors="coerce")
+        else:
+            dt = pd.Series(pd.NaT, index=df.index)
+        mask = pd.Series(True, index=df.index)
+        if start_date: mask &= dt >= pd.to_datetime(start_date)
+        if end_date: mask &= dt <= pd.to_datetime(end_date)
+        result = df.loc[mask].copy()
+        result["trade_date"] = dt.loc[mask].dt.strftime("%Y-%m-%d")
+        result = result.drop(columns=["time"], errors="ignore").sort_values("trade_date", kind="stable").drop_duplicates("trade_date", keep="last")
+        wanted = [x.strip() for x in fields.split(",") if x.strip()]
+        result = result[["trade_date"] + [x for x in wanted if x in result.columns]]
+        return (result.tail(limit) if limit is not None else result).reset_index(drop=True)
+
     async def __aenter__(self) -> "AsyncQuantDBClient":
         return self
 
@@ -206,31 +232,31 @@ class AsyncQuantDBClient:
         end_date: Optional[str] = None,
         fields: str = "open,high,low,close,volume,amount",
         limit: Optional[int] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
     ) -> pd.DataFrame:
         """查询 K 线数据（下载 COS parquet 切片后客户端解析，消耗下载流量，异步）。"""
+        layout = self._validate_layout(layout)
         sub_category = f"daily_{adj_type}"
-        df = await self.a_load_as_df("1", sub_category, symbol)
-        # 日期过滤：K线 parquet 的日期列为 'time'，对外以 'trade_date' 暴露。
-        if "time" in df.columns:
-            dt = pd.to_datetime(df["time"], errors="coerce")
-            if dt.dt.tz is not None:
-                dt = dt.dt.tz_convert(None)
-            mask = pd.Series(True, index=df.index)
-            if start_date:
-                mask &= dt >= pd.to_datetime(start_date)
-            if end_date:
-                mask &= dt <= pd.to_datetime(end_date)
-            df = df[mask].copy()
-            df["trade_date"] = dt[mask].dt.strftime("%Y-%m-%d")
-            df = df.drop(columns=["time"])
-        field_list = [f.strip() for f in fields.split(",") if f.strip()]
-        cols = [c for c in field_list if c in df.columns]
-        keep = (["trade_date"] if "trade_date" in df.columns else []) + cols
-        keep = list(dict.fromkeys(keep))
-        df = df[keep]
-        if limit is not None:
-            df = df.tail(limit)
-        return df.reset_index(drop=True)
+        if layout == "v1" or (layout == "auto" and not (start_date or end_date)):
+            return self._normalise_kline(await self.a_load_as_df("1", sub_category, symbol, layout="v1"), start_date, end_date, fields, limit)
+        files = await self.a_query_manifest("1", sub_category, layout="v2")
+        selected = [f for f in files if (not start_date or f.get("trade_date", "") >= start_date) and (not end_date or f.get("trade_date", "") <= end_date)]
+        calendar = await self.a_query_calendar(start_date, end_date)
+        expected = set()
+        if not calendar.empty:
+            date_col = next((c for c in ("trade_date", "date", "cal_date") if c in calendar.columns), None)
+            open_col = next((c for c in ("is_open", "is_trading_day", "open") if c in calendar.columns), None)
+            if date_col:
+                rows = calendar if not open_col else calendar[calendar[open_col].astype(str).isin(["1", "True", "true"])]
+                expected = set(pd.to_datetime(rows[date_col], errors="coerce").dropna().dt.strftime("%Y-%m-%d"))
+        if not selected or (expected and not expected.issubset({f.get("trade_date") for f in selected})):
+            if layout == "auto":
+                return self._normalise_kline(await self.a_load_as_df("1", sub_category, symbol, layout="v1"), start_date, end_date, fields, limit)
+            raise NotFoundError("V2 日切片在请求日期范围内覆盖不完整；请改用 layout='auto' 或 'v1'")
+        frames = [await self.a_load_as_df("1", sub_category, symbol, trade_date=f["trade_date"], layout="v2") for f in selected]
+        df = pd.concat(frames, ignore_index=True, sort=False)
+        if "symbol" in df.columns: df = df[df["symbol"].astype(str).str.upper() == symbol.upper()].copy()
+        return self._normalise_kline(df, start_date, end_date, fields, limit)
 
     async def a_query_tick(
         self,
@@ -240,9 +266,10 @@ class AsyncQuantDBClient:
         end_ts: Optional[str] = None,
         fields: str = "last_price,open,high,low,last_close,volume,amount",
         limit: Optional[int] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
     ) -> pd.DataFrame:
         """查询 Tick 分笔数据（下载 COS parquet 切片后客户端解析，消耗下载流量，异步）。"""
-        df = await self.a_load_as_df("1", "tick_data", symbol, trade_date=trade_date)
+        df = await self.a_load_as_df("1", "tick_data", symbol, trade_date=trade_date, layout=layout)
         ts_col = "ts" if "ts" in df.columns else ("time" if "time" in df.columns else None)
         if ts_col and (start_ts or end_ts):
             ts = pd.to_datetime(df[ts_col], errors="coerce")
@@ -292,11 +319,13 @@ class AsyncQuantDBClient:
         category_id: str,
         sub_category: str,
         trade_date: Optional[str] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
     ) -> List[Dict[str, Any]]:
         params: Dict[str, Any] = {
             "category_id": category_id,
             "sub_category": sub_category,
         }
+        params["layout"] = self._validate_layout(layout)
         if trade_date:
             params["trade_date"] = trade_date
         data = await self._get("/api/v1/data/download/manifest", params)
@@ -342,6 +371,8 @@ class AsyncQuantDBClient:
         symbol: Optional[str] = None,
         save_dir: Optional[str] = None,
         trade_date: Optional[str] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
+        object_key: Optional[str] = None,
     ) -> str:
         if save_dir is None:
             save_dir = default_download_dir()
@@ -353,8 +384,11 @@ class AsyncQuantDBClient:
         }
         if symbol:
             params["symbol"] = symbol
+        params["layout"] = self._validate_layout(layout)
         if trade_date:
             params["trade_date"] = trade_date
+        if object_key:
+            params["object_key"] = object_key
 
         async with self.client.stream(
             "GET", f"{self.api_host}/api/v1/data/download", params=params
@@ -376,10 +410,12 @@ class AsyncQuantDBClient:
             filename = parse_filename_from_content_disposition(cd, fallback)
 
             save_path = os.path.join(save_dir, filename)
-            with open(save_path, "wb") as f:
+            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)
         return os.path.abspath(save_path)
 
     async def a_load_as_df(
@@ -388,20 +424,26 @@ class AsyncQuantDBClient:
         sub_category: str,
         symbol: Optional[str] = None,
         trade_date: Optional[str] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
+        object_key: Optional[str] = None,
     ) -> pd.DataFrame:
         """远端 Parquet 切片加载到内存 DataFrame（消耗下载流量，异步）。
 
         带进程内 ETag 缓存：同对象（ETag 未变）不重复下载，避免重复计费。
         """
-        cache_key = f"{category_id}/{sub_category}/{symbol}/{trade_date}"
+        layout = self._validate_layout(layout)
+        cache_key = f"{category_id}/{sub_category}/{symbol}/{trade_date}/{layout}/{object_key or ''}"
         params: Dict[str, Any] = {
             "category_id": category_id,
             "sub_category": sub_category,
         }
         if symbol:
             params["symbol"] = symbol
+        params["layout"] = layout
         if trade_date:
             params["trade_date"] = trade_date
+        if object_key:
+            params["object_key"] = object_key
         cached = self._cache.get(cache_key)
         req_headers = {}
         if cached and cached.get("etag"):
@@ -479,3 +521,61 @@ class AsyncQuantDBClient:
         else:
             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]:
+        """异步版 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}")
+        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)")
+        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")
+        state.execute("CREATE TABLE IF NOT EXISTS releases (dataset TEXT PRIMARY KEY, release_id TEXT NOT NULL)")
+        downloaded: List[str] = []
+        try:
+            persisted = state.execute("SELECT release_id FROM releases WHERE dataset=?", (dataset,)).fetchone()
+            cursor = after_release if after_release is not None else (persisted[0] if persisted else "")
+            releases = (await self._get("/api/v1/data/releases", {"datasets": dataset, "after_release": cursor})).get("releases", [])
+            if releases:
+                for release in releases:
+                    for obj in release.get("objects", []):
+                        key, target = obj["key"], os.path.join(root, *obj["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
+                        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:
+                            if resp.status_code != 200:
+                                body = await resp.aread(); self._check_response(httpx.Response(resp.status_code, content=body)); raise QuantDBError("下载失败")
+                            try:
+                                with open(tmp, "wb") as fh:
+                                    async for chunk in resp.aiter_bytes(1024 * 1024):
+                                        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 校验失败")
+                                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 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", [])
+            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)
+            state.commit(); return {"dataset": dataset, "layout": "v1_symbol", "downloaded": downloaded, "after_release": cursor}
+        finally:
+            state.close()

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0}/quantdb_sdk/client.py

@@ -1,9 +1,12 @@
 """QuantDB 同步 Python SDK。"""
 
+import hashlib
 import io
 import os
 import re
-from typing import Any, Dict, List, Optional
+import sqlite3
+import glob
+from typing import Any, Dict, List, Optional, Literal
 
 import pandas as pd
 import requests
@@ -45,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.1.4"})
+        self.session.headers.update({"User-Agent": "QuantDB-Python-SDK/0.2.0"})
 
         if api_key:
             self.headers = {"X-API-Key": api_key}
@@ -155,6 +158,39 @@ class QuantDBClient:
         """
         self._cache.clear()
 
+    @staticmethod
+    def _validate_layout(layout: str) -> Literal["auto", "v1", "v2"]:
+        if layout not in {"auto", "v1", "v2"}:
+            raise ValidationError("layout 仅支持 auto、v1 或 v2")
+        return layout  # type: ignore[return-value]
+
+    @staticmethod
+    def _normalise_kline(df: pd.DataFrame, start_date: Optional[str], end_date: Optional[str], fields: str, limit: Optional[int]) -> pd.DataFrame:
+        """统一 V1/V2 日线结果并在客户端按标的、日期与字段过滤。"""
+        if "time" in df.columns:
+            dt = pd.to_datetime(df["time"], errors="coerce")
+            if getattr(dt.dt, "tz", None) is not None:
+                dt = dt.dt.tz_convert(None)
+        elif "trade_date" in df.columns:
+            dt = pd.to_datetime(df["trade_date"], errors="coerce")
+        else:
+            dt = pd.Series(pd.NaT, index=df.index)
+        mask = pd.Series(True, index=df.index)
+        if start_date:
+            mask &= dt >= pd.to_datetime(start_date)
+        if end_date:
+            mask &= dt <= pd.to_datetime(end_date)
+        result = df.loc[mask].copy()
+        result["trade_date"] = dt.loc[mask].dt.strftime("%Y-%m-%d")
+        result = result.drop(columns=["time"], errors="ignore")
+        result = result.sort_values("trade_date", kind="stable").drop_duplicates("trade_date", keep="last")
+        wanted = [x.strip() for x in fields.split(",") if x.strip()]
+        columns = ["trade_date"] + [x for x in wanted if x in result.columns]
+        result = result.loc[:, list(dict.fromkeys(columns))]
+        if limit is not None:
+            result = result.tail(limit)
+        return result.reset_index(drop=True)
+
     # ========== 账户信息 ==========
 
     def get_me(self) -> Dict[str, Any]:
@@ -253,37 +289,42 @@ class QuantDBClient:
         end_date: Optional[str] = None,
         fields: str = "open,high,low,close,volume,amount",
         limit: Optional[int] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
     ) -> pd.DataFrame:
         """查询 K 线数据（下载 COS parquet 切片后客户端解析，消耗下载流量）。
 
-        下载整个 symbol 的日线 parquet，按 start_date/end_date 过滤日期、按 fields 选列。
-        limit 非 None 时只返回尾部 limit 行。
+        ``auto`` 在提供日期范围时优先 V2 全市场日分区；如 V2 覆盖不完整，
+        整次回退 V1 股票历史文件。未提供日期范围时直接使用 V1，以保持旧版
+        ``query_kline`` 的全历史语义。显式 ``v2`` 不会静默回退。
         """
+        layout = self._validate_layout(layout)
         sub_category = f"daily_{adj_type}"
-        df = self.load_as_df("1", sub_category, symbol)
-        # 日期过滤：K线 parquet 的日期列为 'time'（采集端 01_kline.py 统一命名）。
-        # 对外仍以 'trade_date' 暴露（YYYY-MM-DD），便于用户按日期理解。
-        if "time" in df.columns:
-            dt = pd.to_datetime(df["time"], errors="coerce")
-            if dt.dt.tz is not None:
-                dt = dt.dt.tz_convert(None)
-            mask = pd.Series(True, index=df.index)
-            if start_date:
-                mask &= dt >= pd.to_datetime(start_date)
-            if end_date:
-                mask &= dt <= pd.to_datetime(end_date)
-            df = df[mask].copy()
-            df["trade_date"] = dt[mask].dt.strftime("%Y-%m-%d")
-            df = df.drop(columns=["time"])
-        # 字段过滤：保留 trade_date + 选中字段
-        field_list = [f.strip() for f in fields.split(",") if f.strip()]
-        cols = [c for c in field_list if c in df.columns]
-        keep = (["trade_date"] if "trade_date" in df.columns else []) + cols
-        keep = list(dict.fromkeys(keep))
-        df = df[keep]
-        if limit is not None:
-            df = df.tail(limit)
-        return df.reset_index(drop=True)
+        has_range = bool(start_date or end_date)
+        if layout == "v1" or (layout == "auto" and not has_range):
+            return self._normalise_kline(self.load_as_df("1", sub_category, symbol, layout="v1"), start_date, end_date, fields, limit)
+
+        files = self.query_manifest("1", sub_category, layout="v2")
+        selected = [f for f in files if (not start_date or f.get("trade_date", "") >= start_date) and (not end_date or f.get("trade_date", "") <= end_date)]
+        # 日历是 V2 完整性的权威。无法得到日历或任一开市日缺分区时，auto 回退 V1；v2 明确报错。
+        calendar = self.query_calendar(start_date, end_date)
+        expected = set()
+        if not calendar.empty:
+            date_col = next((c for c in ("trade_date", "date", "cal_date") if c in calendar.columns), None)
+            open_col = next((c for c in ("is_open", "is_trading_day", "open") if c in calendar.columns), None)
+            if date_col:
+                rows = calendar if not open_col else calendar[calendar[open_col].astype(str).isin(["1", "True", "true"])]
+                expected = set(pd.to_datetime(rows[date_col], errors="coerce").dropna().dt.strftime("%Y-%m-%d"))
+        found = {f.get("trade_date") for f in selected}
+        complete = bool(selected) and (not expected or expected.issubset(found))
+        if not complete:
+            if layout == "auto":
+                return self._normalise_kline(self.load_as_df("1", sub_category, symbol, layout="v1"), start_date, end_date, fields, limit)
+            raise NotFoundError("V2 日切片在请求日期范围内覆盖不完整；请改用 layout='auto' 或 'v1'")
+        frames = [self.load_as_df("1", sub_category, symbol, trade_date=f["trade_date"], layout="v2") for f in selected]
+        df = pd.concat(frames, ignore_index=True, sort=False)
+        if "symbol" in df.columns:
+            df = df[df["symbol"].astype(str).str.upper() == symbol.upper()].copy()
+        return self._normalise_kline(df, start_date, end_date, fields, limit)
 
     def query_tick(
         self,
@@ -293,13 +334,14 @@ class QuantDBClient:
         end_ts: Optional[str] = None,
         fields: str = "last_price,open,high,low,last_close,volume,amount",
         limit: Optional[int] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
     ) -> pd.DataFrame:
         """查询 Tick 分笔数据（下载 COS parquet 切片后客户端解析，消耗下载流量）。
 
         下载 trade_date 当日该 symbol 的 tick parquet，按 start_ts/end_ts 过滤时间、按 fields 选列。
         start_ts/end_ts 可传完整时间戳或 "HH:MM:SS"（自动补 trade_date 日期）。
         """
-        df = self.load_as_df("1", "tick_data", symbol, trade_date=trade_date)
+        df = self.load_as_df("1", "tick_data", symbol, trade_date=trade_date, layout=layout)
         # 时间过滤
         ts_col = "ts" if "ts" in df.columns else ("time" if "time" in df.columns else None)
         if ts_col and (start_ts or end_ts):
@@ -353,12 +395,14 @@ class QuantDBClient:
         category_id: str,
         sub_category: str,
         trade_date: Optional[str] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
     ) -> List[Dict[str, Any]]:
         """查询 COS 可下载文件清单。"""
         params: Dict[str, Any] = {
             "category_id": category_id,
             "sub_category": sub_category,
         }
+        params["layout"] = self._validate_layout(layout)
         if trade_date:
             params["trade_date"] = trade_date
         data = self._get("/api/v1/data/download/manifest", params)
@@ -410,10 +454,12 @@ class QuantDBClient:
         symbol: Optional[str] = None,
         save_dir: Optional[str] = None,
         trade_date: Optional[str] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
+        object_key: Optional[str] = None,
     ) -> str:
         """流式下载原始 Parquet 切片到本地，返回保存路径（消耗下载流量）。
 
-        trade_date 仅对 tick_data 子分类有效（按交易日下载 {SYM}_{YYYYMMDD}.parquet）。
+        ``object_key`` 仅供 release 增量同步使用；服务端会校验它属于请求的数据集前缀。
         """
         if save_dir is None:
             save_dir = default_download_dir()
@@ -425,8 +471,11 @@ class QuantDBClient:
         }
         if symbol:
             params["symbol"] = symbol
+        params["layout"] = self._validate_layout(layout)
         if trade_date:
             params["trade_date"] = trade_date
+        if object_key:
+            params["object_key"] = object_key
 
         resp = self._request(
             "GET", "/api/v1/data/download", params=params, stream=True
@@ -442,10 +491,12 @@ class QuantDBClient:
         )
 
         save_path = os.path.join(save_dir, filename)
-        with open(save_path, "wb") as f:
+        tmp_path = save_path + ".part"
+        with open(tmp_path, "wb") as f:
             for chunk in resp.iter_content(chunk_size=8192):
                 if chunk:
                     f.write(chunk)
+        os.replace(tmp_path, save_path)
         return os.path.abspath(save_path)
 
     def load_as_df(
@@ -454,6 +505,8 @@ class QuantDBClient:
         sub_category: str,
         symbol: Optional[str] = None,
         trade_date: Optional[str] = None,
+        layout: Literal["auto", "v1", "v2"] = "auto",
+        object_key: Optional[str] = None,
     ) -> pd.DataFrame:
         """将远端 Parquet 切片直接加载到内存 DataFrame（不落盘，消耗下载流量）。
 
@@ -462,18 +515,20 @@ class QuantDBClient:
         带进程内 ETag 缓存：同一对象（ETag 未变）不重复下载，避免对同一 symbol
         多次查询时重复消耗流量。
         """
-        cache_key = f"{category_id}/{sub_category}/{symbol}/{trade_date}"
+        layout = self._validate_layout(layout)
+        cache_key = f"{category_id}/{sub_category}/{symbol}/{trade_date}/{layout}/{object_key or ''}"
         params: Dict[str, Any] = {
             "category_id": category_id,
             "sub_category": sub_category,
         }
         if symbol:
             params["symbol"] = symbol
+        params["layout"] = layout
         if trade_date:
             params["trade_date"] = trade_date
-        # 若已有缓存，带 If-None-Match 让服务端在对象未变时返回 304（不计流量下载 body）。
-        # 注：当前网关透传 COS ETag，但未实现 304；若服务端不支持 304，仍会返回 200
-        # 全量 body，此时用响应 ETag 命中本地缓存跳过重复解析。
+        if object_key:
+            params["object_key"] = object_key
+        # 若已有缓存，带 If-None-Match；服务端 ETag 命中时返回 304，不扣下载流量。
         cached = self._cache.get(cache_key)
         headers = {}
         if cached and cached.get("etag"):
@@ -557,6 +612,125 @@ class QuantDBClient:
         """获取 DuckDB 本地数据仓库实例，用于离线多表 SQL JOIN 查询。"""
         return DuckDBWarehouse(client=self, save_dir=save_dir)
 
+    def sync_dataset(self, dataset: str, save_dir: Optional[str] = None, after_release: Optional[str] = None) -> Dict[str, Any]:
+        """按 release 增量同步 V2；无可用 V2 release 时回退 V1 Manifest。"""
+        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)")
+        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")
+        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:
+            raise ValidationError(f"不支持同步的数据集: {dataset}")
+
+        downloaded: List[str] = []
+        try:
+            persisted = state.execute("SELECT release_id FROM releases WHERE dataset=?", (dataset,)).fetchone()
+            cursor = after_release if after_release is not None else (persisted[0] if persisted else "")
+            release_data = self._get("/api/v1/data/releases", {"datasets": dataset, "after_release": cursor})
+            releases = release_data.get("releases", [])
+            if releases:
+                for release in releases:
+                    release_id = release["release_id"]
+                    for obj in release.get("objects", []):
+                        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]):
+                            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)
+                        if resp.status_code != 200:
+                            self._check_response(resp)
+                        os.makedirs(os.path.dirname(target), exist_ok=True)
+                        tmp, digest = target + ".part", hashlib.sha256()
+                        try:
+                            with open(tmp, "wb") as fh:
+                                for chunk in resp.iter_content(1024 * 1024):
+                                    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 校验失败")
+                            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)
+                    # 仅在该 release 的所有对象成功落盘和校验后提交 cursor。
+                    state.execute("INSERT OR REPLACE INTO releases(dataset,release_id) VALUES(?,?)", (dataset, 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]}
+
+            manifest = self._get("/api/v1/data/download/manifest", {"category_id": category_map[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]):
+                    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)
+                if resp.status_code != 200: self._check_response(resp)
+                os.makedirs(os.path.dirname(target), exist_ok=True)
+                tmp = target + ".part"
+                try:
+                    with open(tmp, "wb") as fh:
+                        for chunk in resp.iter_content(1024 * 1024):
+                            if chunk: fh.write(chunk)
+                    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))
+                downloaded.append(key)
+            state.commit()
+            return {"dataset": dataset, "layout": "v1_symbol", "downloaded": downloaded, "after_release": cursor}
+        finally:
+            state.close()
+
+    def mount_local_dataset(self, dataset: str, save_dir: Optional[str] = None, view_name: Optional[str] = None) -> "DuckDBWarehouse":
+        """挂载本地 V1/V2 同构数据集；V2 patch 与 daily 文件均参与去重。"""
+        warehouse = self.get_local_warehouse(save_dir)
+        root = os.path.abspath(save_dir or default_download_dir()).replace("\\", "/")
+        views = {"daily_forward":"1_kline_data/daily_forward", "valuation":"5_technical_derived/valuation", "technical_indicators":"5_technical_derived/technical_indicators", "market_sentiment":"5_technical_derived/market_sentiment", "features_daily":"6_ml_datasets/features_daily"}
+        if dataset not in views: raise ValidationError(f"不支持的 V2 数据集: {dataset}")
+        name = view_name or re.sub(r"[^a-zA-Z0-9_]", "_", dataset)
+        state_path = os.path.join(root.replace("/", os.sep), "quantdb_sync.sqlite")
+        files: List[str] = []
+        if os.path.exists(state_path):
+            conn = sqlite3.connect(state_path)
+            try:
+                files = [row[0] for row in conn.execute("SELECT path FROM objects WHERE dataset=? AND path IS NOT NULL", (dataset,)) if os.path.exists(row[0])]
+            finally:
+                conn.close()
+        if not files:
+            daily = f"{root}/{views[dataset]}/dt=*/data.parquet"
+            v1 = f"{root}/{views[dataset]}/*.parquet"
+            files = glob.glob(daily) or glob.glob(v1)
+        if not files: raise NotFoundError(f"本地尚未同步数据集: {dataset}")
+        quoted = ", ".join("'" + p.replace("'", "''") + "'" for p in files)
+        relation = f"read_parquet([{quoted}], union_by_name=true)"
+        columns = {row[0] for row in warehouse.conn.execute(f"DESCRIBE SELECT * FROM {relation}").fetchall()}
+        if {"symbol", "time"}.issubset(columns):
+            order = "coalesce(release_id, '') DESC" if "release_id" in columns else "0"
+            warehouse.conn.execute(f"CREATE OR REPLACE VIEW {name} AS SELECT * EXCLUDE (rn) FROM (SELECT *, row_number() OVER (PARTITION BY symbol, time ORDER BY {order}) rn FROM {relation}) WHERE rn=1")
+        else:
+            warehouse.conn.execute(f"CREATE OR REPLACE VIEW {name} AS SELECT * FROM {relation}")
+        warehouse._views[name] = f"{dataset}"
+        return warehouse
+
 
 class DuckDBWarehouse:
     """DuckDB 本地仓库管理，支持自动下载数据并注册为 DuckDB 视图，方便多表复杂 SQL 查询。"""

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0/quantdb_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.1.4
+Version: 0.2.0
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -88,6 +88,24 @@ client = QuantDBClient(username="admin", password="admin123")
 - **账户管理**：查询用户信息、用量、API Key、订阅与订单。
 - **异步客户端**：基于 httpx，适用于 asyncio 量化框架。
 
+## V1 / V2 数据布局
+
+COS 同时保留 V1（按股票历史文件）和 V2（按交易日全市场分区）。所有下载相关接口均可传入
+`layout="auto" | "v1" | "v2"`。默认 `auto` 的规则是：给出 K 线日期范围时优先 V2；若任一
+交易日没有 V2 分区，则整次请求回退 V1，绝不混合两种口径；未给日期范围时读取 V1 全历史文件。
+
+```python
+# 按日期范围优先 V2；覆盖不完整时自动回退 V1
+df = client.query_kline("600519.SH", start_date="2026-07-01", end_date="2026-07-24")
+
+# 强制指定物理布局；layout="v2" 缺日时会明确报错
+latest = client.download_file("1", "daily_forward", trade_date="2026-07-24", layout="v2")
+history = client.download_file("1", "daily_forward", symbol="600519.SH", layout="v1")
+
+# 以发布清单为 cursor 做原子化增量同步（含 V2 patch）
+result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
+```
+
 ## 流量说明
 
 免费注册用户获赠 100 MB 一次性体验流量；订阅用户每月含 30 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0}/tests/test_async_client.py

@@ -1,6 +1,7 @@
 """QuantDB 异步 SDK 单元测试（使用 respx mock HTTP）。"""
 
 import io
+from urllib.parse import parse_qs, urlparse
 
 import httpx
 import pandas as pd
@@ -40,6 +41,29 @@ async def test_a_query_kline():
     assert route.called
 
 
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_query_kline_without_range_forces_v1_layout():
+    route = respx.get(f"{API_HOST}/api/v1/data/download").mock(return_value=httpx.Response(200, content=_kline_parquet()))
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        await client.a_query_kline("600519.SH")
+    assert parse_qs(urlparse(str(route.calls[0].request.url)).query)["layout"] == ["v1"]
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_sync_dataset_uses_release_cursor(tmp_path):
+    payload = b"release-parquet"
+    digest = __import__("hashlib").sha256(payload).hexdigest()
+    respx.get(f"{API_HOST}/api/v1/data/releases").mock(return_value=httpx.Response(200, json={"releases": [{"release_id": "20260726_180000", "objects": [{"key": "1_kline_data/daily_forward/dt=20260726/data.parquet", "etag": "etag-1", "sha256": digest}]}]}))
+    route = 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("daily_forward", str(tmp_path))
+    assert result["layout"] == "v2_daily_partition"
+    assert (tmp_path / "1_kline_data" / "daily_forward" / "dt=20260726" / "data.parquet").read_bytes() == payload
+    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_auth_error_raises_auth_error():

{quantdb_sdk-0.1.4 → quantdb_sdk-0.2.0}/tests/test_client.py

@@ -1,6 +1,7 @@
 """QuantDB 同步 SDK 单元测试（使用 responses mock HTTP）。"""
 
 import io
+from urllib.parse import parse_qs, urlparse
 
 import pandas as pd
 import pytest
@@ -42,6 +43,53 @@ def test_query_kline():
     assert len(df) == 2
 
 
+@responses.activate
+def test_query_kline_without_range_forces_v1_layout():
+    responses.get(f"{API_HOST}/api/v1/data/download", body=_kline_parquet(), status=200)
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    client.query_kline("600519.SH")
+    params = parse_qs(urlparse(responses.calls[0].request.url).query)
+    assert params["layout"] == ["v1"]
+
+
+@responses.activate
+def test_query_kline_range_reads_all_v2_days():
+    responses.get(
+        f"{API_HOST}/api/v1/data/download/manifest",
+        json={"files": [{"trade_date": "2025-01-02"}, {"trade_date": "2025-01-03"}]}, status=200,
+    )
+    responses.get(
+        f"{API_HOST}/api/v1/data/calendar",
+        json={"data": [{"trade_date": "2025-01-02", "is_open": 1}, {"trade_date": "2025-01-03", "is_open": 1}]}, status=200,
+    )
+    def download_cb(request):
+        date = parse_qs(urlparse(request.url).query)["trade_date"][0]
+        buf = io.BytesIO()
+        pd.DataFrame({"symbol": ["600519.SH"], "time": [date], "open": [1.0], "close": [2.0]}).to_parquet(buf)
+        return 200, {"ETag": date}, buf.getvalue()
+    responses.add_callback(responses.GET, f"{API_HOST}/api/v1/data/download", callback=download_cb)
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    df = client.query_kline("600519.SH", start_date="2025-01-02", end_date="2025-01-03")
+    assert df["trade_date"].tolist() == ["2025-01-02", "2025-01-03"]
+
+
+@responses.activate
+def test_sync_dataset_uses_release_cursor_and_object_key(tmp_path):
+    payload = b"release-parquet"
+    digest = __import__("hashlib").sha256(payload).hexdigest()
+    responses.get(
+        f"{API_HOST}/api/v1/data/releases",
+        json={"releases": [{"release_id": "20260726_180000", "objects": [{"key": "1_kline_data/daily_forward/dt=20260726/data.parquet", "etag": "etag-1", "sha256": digest}]}]}, status=200,
+    )
+    responses.get(f"{API_HOST}/api/v1/data/download", body=payload, status=200)
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    result = client.sync_dataset("daily_forward", str(tmp_path))
+    assert result["layout"] == "v2_daily_partition"
+    assert (tmp_path / "1_kline_data" / "daily_forward" / "dt=20260726" / "data.parquet").read_bytes() == payload
+    params = parse_qs(urlparse(responses.calls[-1].request.url).query)
+    assert params["object_key"] == ["1_kline_data/daily_forward/dt=20260726/data.parquet"]
+
+
 @responses.activate
 def test_auth_error_raises_auth_error():
     responses.get(