quantdb-sdk 0.3.5__tar.gz → 0.4.0__tar.gz

{quantdb_sdk-0.3.5 → quantdb_sdk-0.4.0}/CHANGELOG.md

@@ -3,6 +3,22 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## \[0.4.0] - 2026-10-05
+
+### Added
+
+- **统一数据入口** **`client.data`**（同步 `DataHub` / 异步 `AsyncDataHub`，模块 `quantdb_sdk.hub`）：只凭 **dataset 名**即可跨 6 大分类目录取数，不必再手填 `category_id + sub_category`。SDK 侧解析分类后复用现有端点，**零后端改动**。
+
+  - **发现**：`datasets(category, access, keyword)` 列出 29 个数据集目录；`info(dataset)` 返回注册表字段并叠加云端元数据（覆盖区间 / 文件数 / 文件大小）。
+  - **本地零流量**：`local_files` / `local_path` / `read_local` / `read`（本地优先，缺失时显式回退在线）。数据根目录可配置（`root` 参数，缺省读 `QUANTDB_DATA_DIR`）；多形态 glob 兼容 V2 `dt=` 分区、tick 平铺/子目录分片、V1 逐股票文件；V2/tick 无日期列时从路径注入 `trade_date`。
+  - **在线**：`preview` / `load` / `download` / `query` / `sync` / `mount`，逐项委托既有方法。`query` 按数据集自动路由：日线三兄弟走 `query_kline`、ETF 走 `query_etf_kline`、tick 走 `query_tick` 并按 symbol 后置过滤、其余 V2 走通用日分区分支、V1 逐股票走 `layout="v1"` + 日期列过滤。
+  - 异步方法统一 `a_` 前缀；异步端不含 `mount`（无 `a_mount_local_dataset`，DuckDB 仓库为同步）。
+  - 新增 `DATASET_REGISTRY` 注册表（29 项），`category_id` 复用 `SYNC_DATASET_CATEGORIES`，`category_dir` 复用 `CATEGORY_DIRS`，避免重复维护分类事实源。
+
+- **命令行** **`quantdb datasets [name]`**：列出全部数据集目录或查看某个数据集详情（无需 API Key）。
+
+- 新增演示脚本 `quantdb_sdk/examples/demo_07_data_hub.py`。
+
 ## \[0.3.5] - 2026-09-26
 
 ### Added

{quantdb_sdk-0.3.5/quantdb_sdk.egg-info → quantdb_sdk-0.4.0}/PKG-INFO

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

{quantdb_sdk-0.3.5 → quantdb_sdk-0.4.0}/pyproject.toml

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

{quantdb_sdk-0.3.5 → quantdb_sdk-0.4.0}/quantdb_sdk/__init__.py

@@ -5,12 +5,13 @@ try:
     # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
     __version__ = version("quantdb-sdk")
 except ImportError:
-    __version__ = "0.3.4"
+    __version__ = "0.4.0"
 
 from . import layout
 from ._utils import scan_local_directory
 from .async_client import AsyncQuantDBClient
 from .client import DuckDBWarehouse, QuantDBClient
+from .hub import DATASET_REGISTRY, AsyncDataHub, DataHub
 from .errors import (
     AuthError,
     InsufficientTrafficError,
@@ -33,6 +34,10 @@ __all__ = [
     "QuantDBClient",
     "AsyncQuantDBClient",
     "DuckDBWarehouse",
+    # 统一数据入口（quantdb_sdk.hub）
+    "DataHub",
+    "AsyncDataHub",
+    "DATASET_REGISTRY",
     "QuantDBError",
     "AuthError",
     "InsufficientTrafficError",

{quantdb_sdk-0.3.5 → quantdb_sdk-0.4.0}/quantdb_sdk/__main__.py

@@ -4,6 +4,8 @@
   python -m quantdb --version
   python -m quantdb --help
   python -m quantdb layout            # 查看本地数据目录规范
+  python -m quantdb datasets          # 列出全部数据集目录（无需 API Key）
+  python -m quantdb datasets l1_factors  # 查看某个数据集详情
   QUANTDB_API_KEY=qdb_xxx quantdb check  # 验证 API Key 是否有效
 
 演示脚本见 quantdb_sdk.examples（demo_01 ~ demo_06），
@@ -13,6 +15,7 @@
 import argparse
 import os
 import sys
+from typing import Optional
 
 from . import __version__, layout
 from .client import QuantDBClient
@@ -38,6 +41,27 @@ def cmd_layout() -> int:
     return 0
 
 
+def cmd_datasets(name: Optional[str] = None) -> int:
+    """列出全部数据集目录，或查看某个数据集详情（无需 API Key）。"""
+    from .hub import DATASET_REGISTRY
+
+    if name:
+        info = DATASET_REGISTRY.get(name)
+        if info is None:
+            print(f"[ERROR] 未知数据集: {name}", file=sys.stderr)
+            return 1
+        print(f"{info.dataset}  {info.name}  ({info.category_id} {info.category_dir})")
+        print(f"  描述: {info.description}")
+        print(f"  访问: {info.access}    布局: {info.layout}    选择器: {', '.join(info.selectors) or '-'}")
+        print(f"  关键词: {', '.join(info.keywords)}")
+        return 0
+
+    print(f"共 {len(DATASET_REGISTRY)} 个数据集：")
+    for info in DATASET_REGISTRY.values():
+        print(f"  [{info.category_id}] {info.dataset:<20s} {info.name:<16s} {info.access:<12s} {info.layout}")
+    return 0
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(
         prog="quantdb",
@@ -71,6 +95,11 @@ def main() -> int:
     # layout 命令：打印目录规范
     layout_parser = subparsers.add_parser("layout", help="查看本地数据目录规范（无需 API Key）")
 
+    # datasets 命令：列出数据集目录（无需 API Key）
+    datasets_parser = subparsers.add_parser("datasets", help="列出全部数据集目录（无需 API Key）")
+    datasets_parser.add_argument("name", nargs="?", default=None,
+                                 help="可选：查看某个数据集详情，如 l1_factors")
+
     sync_parser = subparsers.add_parser("sync", help="以 release/Manifest 增量同步一个数据集")
     sync_parser.add_argument("dataset", help="数据集，如 daily_forward、balance、etf_pcf")
     sync_parser.add_argument("--save-dir", default=None,
@@ -83,9 +112,11 @@ def main() -> int:
         parser.print_help()
         return 0
 
-    # layout 命令无需 API Key，直接打印目录规范
+    # layout / datasets 命令无需 API Key
     if args.command == "layout":
         return cmd_layout()
+    if args.command == "datasets":
+        return cmd_datasets(args.name)
 
     api_key = os.getenv(args.api_key_env)
     if not api_key:

{quantdb_sdk-0.3.5 → quantdb_sdk-0.4.0}/quantdb_sdk/async_client.py

@@ -28,7 +28,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.3.5"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.0"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -83,6 +83,9 @@ class AsyncQuantDBClient:
         # 进程内 parquet ETag 缓存：同对象（ETag 未变）不重复下载，避免重复计费。
         self._cache: Dict[str, Dict[str, Any]] = {}
 
+        # 统一数据入口（quantdb_sdk.hub.AsyncDataHub）惰性实例，见 data property。
+        self._data_hub: Optional[Any] = None
+
     async def close(self) -> None:
         """关闭底层 httpx 客户端。"""
         await self.client.aclose()
@@ -92,6 +95,19 @@ class AsyncQuantDBClient:
         """清空进程内 Parquet 缓存（强制下次重新下载最新数据）。"""
         self._cache.clear()
 
+    @property
+    def data(self) -> "AsyncDataHub":
+        """统一数据入口（异步）：只凭 dataset 名跨 6 大分类目录取数。
+
+        返回 :class:`quantdb_sdk.hub.AsyncDataHub`，惰性创建，方法名统一 ``a_`` 前缀。
+        不含挂载方法（异步端无 ``a_mount_local_dataset``）；如需 DuckDB 挂载视图，
+        请改用同步客户端 ``client.data.mount(...)``。
+        """
+        if self._data_hub is None:
+            from .hub import AsyncDataHub  # 函数内 import，避免与 hub 循环依赖
+            self._data_hub = AsyncDataHub(self)
+        return self._data_hub
+
     @asynccontextmanager
     async def _download_stream(self, params: Dict[str, Any], headers: Optional[Dict[str, str]] = None):
         """下载专用流式请求：手动处理服务端 302 CDN 直连跳转。

{quantdb_sdk-0.3.5 → quantdb_sdk-0.4.0}/quantdb_sdk/client.py

@@ -32,7 +32,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.3.5"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.0"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -92,6 +92,9 @@ class QuantDBClient:
         # 只需下载一次。进程退出即失效（无跨进程副作用）。
         self._cache: Dict[str, Dict[str, Any]] = {}
 
+        # 统一数据入口（quantdb_sdk.hub.DataHub）惰性实例，见 data property。
+        self._data_hub: Optional[Any] = None
+
         retries = Retry(
             total=max_retries,
             backoff_factor=0.5,
@@ -263,6 +266,20 @@ class QuantDBClient:
         """
         self._cache.clear()
 
+    @property
+    def data(self) -> "DataHub":
+        """统一数据入口：只凭 dataset 名跨 6 大分类目录取数。
+
+        返回 :class:`quantdb_sdk.hub.DataHub`，惰性创建。支持发现（``datasets`` /
+        ``info``）、本地零流量读取（``local_files`` / ``local_path`` / ``read_local`` /
+        ``read``）、在线查询（``preview`` / ``load`` / ``download`` / ``query``）与
+        同步挂载（``sync`` / ``mount``）。
+        """
+        if self._data_hub is None:
+            from .hub import DataHub  # 函数内 import，避免与 hub 循环依赖
+            self._data_hub = DataHub(self)
+        return self._data_hub
+
     @staticmethod
     def _validate_layout(layout: str) -> Literal["auto", "v1", "v2"]:
         if layout not in {"auto", "v1", "v2"}:

quantdb_sdk-0.4.0/quantdb_sdk/examples/demo_07_data_hub.py

@@ -0,0 +1,66 @@
+"""demo_07 统一数据入口 client.data（DataHub）。
+
+只凭 dataset 名跨 6 大分类目录取数，不必手填 category_id + sub_category：
+  1. datasets()    — 列出 29 个数据集目录（零流量）
+  2. info()        — 覆盖区间 + 文件大小
+  3. read_local()  — 本地零流量读取（root 可配，缺省读 QUANTDB_DATA_DIR）
+  4. preview()     — 在线预览（不消耗下载流量）
+  5. query()       — 在线查询（消耗下载流量）
+
+运行::
+
+    QUANTDB_API_KEY=qdb_xxx python -m quantdb_sdk.examples.demo_07_data_hub
+    QUANTDB_API_KEY=qdb_xxx python -m quantdb_sdk.examples.demo_07_data_hub --dataset l1_factors
+"""
+
+import argparse
+import os
+
+from quantdb_sdk import QuantDBClient
+from quantdb_sdk.errors import NotFoundError, QuantDBError
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--api-host", default="https://www.quantdb.cn")
+    p.add_argument("--api-key", default=None, help="默认读环境变量 QUANTDB_API_KEY")
+    p.add_argument("--root", default=None, help="本地数据根目录（默认读 QUANTDB_DATA_DIR / 回退默认下载目录）")
+    p.add_argument("--symbol", default="600519.SH")
+    p.add_argument("--dataset", default="daily_forward")
+    args = p.parse_args()
+
+    api_key = args.api_key or os.getenv("QUANTDB_API_KEY")
+    if not api_key:
+        raise SystemExit("请设置 QUANTDB_API_KEY 或传 --api-key")
+
+    client = QuantDBClient(api_host=args.api_host, api_key=api_key)
+    hub = client.data
+
+    # 1. 数据集目录（零流量）
+    print("== 数据集目录（前 8 个）==")
+    print(hub.datasets().head(8).to_string(index=False))
+
+    # 2. 元数据（覆盖区间 + 文件大小）
+    info = hub.info(args.dataset)
+    print(f"\n== {args.dataset} 元数据 ==")
+    print(f"  {info['name']}  分类={info['category_dir']}  区间={info['min_date']}~{info['max_date']}")
+    print(f"  文件数={info['file_count']}  大小={info['file_size_gb']} GB")
+
+    # 3. 本地零流量读取（root 可配）
+    print(f"\n== 本地读取 {args.dataset} ==")
+    try:
+        local = hub.read_local(args.dataset, symbol=args.symbol, root=args.root, latest=True)
+        print(local.head(3).to_string(index=False))
+    except NotFoundError:
+        print(f"  本地未找到 {args.dataset}；可先 client.data.sync('{args.dataset}') 同步")
+
+    # 4. 在线预览（不消耗下载流量）
+    try:
+        print(f"\n== 在线预览 {args.dataset} ==")
+        print(hub.preview(args.dataset, symbol=args.symbol, limit=3).to_string(index=False))
+    except QuantDBError as e:
+        print(f"  预览失败: {e}")
+
+
+if __name__ == "__main__":
+    main()