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

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

@@ -3,6 +3,37 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## \[0.4.1] - 2026-10-05
+
+### Changed
+
+- **本地零流量读取提速**（`client.data.read_local` / `read`）：改用 DuckDB 对**精确分区文件列表**做一次 `read_parquet`，把 `symbol` / 日期区间 / 列裁剪全部下推到 SQL，替代原先逐文件 `pd.read_parquet` 再 `concat`。实测（120 分区 × 1000 标的）单标的全历史 `0.62s → 0.22s`，带 `columns` 列裁剪 `→ 0.07s`。
+
+  - V2 按日分区与 tick 分片的 `trade_date` 由分区目录名 / 文件名推导，**不依赖** hive 注入的 `dt` 列（该列仅在较新 DuckDB 存在）。
+  - V1 逐股票表日期过滤用 `substr(replace(CAST(col AS VARCHAR),'-',''),1,8)` 归一化后下推，同时兼容整型报告期 `20251231` 与字符串 `2025-12-31` / 带时分秒。
+
+- **依赖下界调整**：`duckdb` 由 `>=0.8.0` 改为 `>=1.0.0`。`read_local` 用到 `read_parquet(filename=true)` + `* EXCLUDE (filename)`；0.8.x 在部分环境（Windows / Python 3.10）导入即崩溃，1.0.0 ~ 1.5.5 已验证通过。
+
+### Fixed
+
+- `read_local(..., columns=[...])` 在 V2 / tick 上未把 `symbol` 过滤下推：当 `columns` 不含 `symbol` 时，旧实现会在读取后被静默跳过过滤、返回全市场行。现 `symbol` 始终在 SQL 中下推。
+
+## \[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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.3.5
+Version: 0.4.1
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -26,7 +26,7 @@ License-File: LICENSE
 Requires-Dist: requests>=2.25.0
 Requires-Dist: pandas>=1.3.0
 Requires-Dist: httpx>=0.24.0
-Requires-Dist: duckdb>=0.8.0
+Requires-Dist: duckdb>=1.0.0
 Requires-Dist: pyarrow>=10.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"

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

@@ -1,67 +1,69 @@
-[build-system]
-requires = ["setuptools>=61.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "quantdb-sdk"
-version = "0.3.5"
-description = "QuantDB 量化数据平台官方 Python SDK"
-readme = "README.md"
-license = {text = "MIT"}
-requires-python = ">=3.8"
-authors = [
-    {name = "QuantDB Team"},
-]
-keywords = ["quant", "finance", "data", "a-share", "parquet"]
-classifiers = [
-    "Development Status :: 3 - Alpha",
-    "Intended Audience :: Developers",
-    "Intended Audience :: Financial and Insurance Industry",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Topic :: Office/Business :: Financial",
-]
-dependencies = [
-    "requests>=2.25.0",
-    "pandas>=1.3.0",
-    "httpx>=0.24.0",
-    "duckdb>=0.8.0",
-    # 0.1.1 修复：pyarrow 是 pd.read_parquet 的硬依赖（client.py:482, async_client.py:413），
-    # 但 0.1.0 漏声明，导致 pip install 后首次 K线/Tick 查询会抛 ImportError。
-    # 锁定到 >=10.0.0 以获得 Python 3.10+ 完整支持（pyarrow 14+ 更好）。
-    "pyarrow>=10.0.0",
-]
-
-# 0.1.2 新增：装包后提供 `quantdb` shell 命令，等价于 `python -m quantdb_sdk`。
-# 0.1.0/0.1.1 README 写的是 `python -m quantdb`（用了 PyPI 名带连字符），
-# 但 Python 模块名是下划线，安装后 `python -m quantdb` 会报 No module named quantdb。
-# 加这个 entry point 后两个名字都能用，README 不需要再改。
-[project.scripts]
-quantdb = "quantdb_sdk.__main__:main"
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=7.0.0",
-    "pytest-asyncio>=0.21.0",
-    "responses>=0.23.0",
-    "respx>=0.20.0",
-]
-
-[project.urls]
-Homepage = "https://quantdb.quantmind.cloud"
-Documentation = "https://quantdb.quantmind.cloud/docs/sdk.html"
-Repository = "https://github.com/quantdb/quantdb"
-Changelog = "https://github.com/quantdb/quantdb/blob/main/CHANGELOG.md"
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["quantdb_sdk*"]
-
-# 0.1.2 新增：让 wheel 包含 LICENSE 和 CHANGELOG.md
-[tool.setuptools.package-data]
-quantdb_sdk = ["py.typed"]
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quantdb-sdk"
+version = "0.4.1"
+description = "QuantDB 量化数据平台官方 Python SDK"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "QuantDB Team"},
+]
+keywords = ["quant", "finance", "data", "a-share", "parquet"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "requests>=2.25.0",
+    "pandas>=1.3.0",
+    "httpx>=0.24.0",
+    # 0.4.1 起 client.data.read_local 用 read_parquet(filename=true) + `* EXCLUDE (filename)`
+    # 做精确分区读取；0.8.x 在部分环境（Windows/Python 3.10）导入即崩溃，1.0.0~1.5.5 已验证。
+    "duckdb>=1.0.0",
+    # 0.1.1 修复：pyarrow 是 pd.read_parquet 的硬依赖（client.py:482, async_client.py:413），
+    # 但 0.1.0 漏声明，导致 pip install 后首次 K线/Tick 查询会抛 ImportError。
+    # 锁定到 >=10.0.0 以获得 Python 3.10+ 完整支持（pyarrow 14+ 更好）。
+    "pyarrow>=10.0.0",
+]
+
+# 0.1.2 新增：装包后提供 `quantdb` shell 命令，等价于 `python -m quantdb_sdk`。
+# 0.1.0/0.1.1 README 写的是 `python -m quantdb`（用了 PyPI 名带连字符），
+# 但 Python 模块名是下划线，安装后 `python -m quantdb` 会报 No module named quantdb。
+# 加这个 entry point 后两个名字都能用，README 不需要再改。
+[project.scripts]
+quantdb = "quantdb_sdk.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "responses>=0.23.0",
+    "respx>=0.20.0",
+]
+
+[project.urls]
+Homepage = "https://quantdb.quantmind.cloud"
+Documentation = "https://quantdb.quantmind.cloud/docs/sdk.html"
+Repository = "https://github.com/quantdb/quantdb"
+Changelog = "https://github.com/quantdb/quantdb/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["quantdb_sdk*"]
+
+# 0.1.2 新增：让 wheel 包含 LICENSE 和 CHANGELOG.md
+[tool.setuptools.package-data]
+quantdb_sdk = ["py.typed"]

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

@@ -5,12 +5,13 @@ try:
     # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
     __version__ = version("quantdb-sdk")
 except ImportError:
-    __version__ = "0.3.4"
+    __version__ = "0.4.1"
 
 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.1}/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.1}/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.1"
 
 
 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.1}/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.1"
 
 
 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.1/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()