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

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

@@ -3,6 +3,21 @@
 所有 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.4.0
+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.4.0 → 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.4.0"
-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.4.0 → quantdb_sdk-0.4.1}/quantdb_sdk/__init__.py

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

{quantdb_sdk-0.4.0 → 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.4.0"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.1"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:

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

@@ -32,7 +32,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.0"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.1"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:

{quantdb_sdk-0.4.0 → quantdb_sdk-0.4.1}/quantdb_sdk/hub.py

@@ -23,12 +23,14 @@
   ``tick_shard``），用于 ``query()`` 路由；不用 :func:`quantdb_sdk.layout.dataset_layout`
   （其 V2 集合已过期，缺 min1/min5/etf/tick）。
 - 本地读取用**多形态 glob** 与目录布局集合解耦，支持显式 ``root``（数据根目录可配置，
-  非固定目录；缺省读 :func:`quantdb_sdk.layout.data_root`）。
+  非固定目录；缺省读 :func:`quantdb_sdk.layout.data_root`）；读取本身交给 DuckDB 对
+  精确文件列表做一次 ``read_parquet``（列裁剪 / symbol / 日期下推），不逐文件拼接。
 """
 
 import glob
 import os
 import re
+import threading
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -52,6 +54,16 @@ _KLINE_ADJ_TYPES = {
 # V1 逐股票表的日期列候选（财务表多为 m_timetag；holder_num 为 endDate；l1_l2_factors 为 date）
 _V1_DATE_COLUMNS = ("time", "trade_date", "date", "_filename_date", "m_timetag", "endDate")
 
+# 从路径推导 trade_date 的 DuckDB 表达式（V2 用 dt= 目录名；tick 用文件名 _YYYYMMDD）。
+# 统一从 filename 提取，不依赖 hive 注入的 dt 列——dt 列仅在较新 DuckDB 自动出现，
+# 低版本（如 1.0.x）不存在，会使 `EXCLUDE (dt)` / `CAST(dt ...)` 直接报错。
+_V2_DATE_EXPR = (
+    "strftime(strptime(regexp_extract(filename, 'dt=(\\d{8})', 1), '%Y%m%d'), '%Y-%m-%d')"
+)
+_TICK_DATE_EXPR = (
+    "strftime(strptime(regexp_extract(filename, '_(\\d{8})\\.parquet$', 1), '%Y%m%d'), '%Y-%m-%d')"
+)
+
 
 @dataclass(frozen=True)
 class DatasetInfo:
@@ -315,6 +327,41 @@ def _local_path(
     return files[-1]
 
 
+# DuckDB 连接（线程内复用）：精确文件列表查询用裸连接即可，无需挂载 glob 视图。
+# 参考实现 quantmindoss QuantDBDataHub._exact_conn 的结论：复用视图连接会为每个
+# 新线程重建视图，首查开销极大；精确路径查询不需要视图。
+_DUCK_LOCAL = threading.local()
+
+
+def _duck_conn():
+    """返回当前线程复用的 DuckDB 连接（懒建）。"""
+    conn = getattr(_DUCK_LOCAL, "conn", None)
+    if conn is None:
+        try:
+            import duckdb  # type: ignore
+        except ImportError as exc:
+            raise RuntimeError("本地零流量读取需要 duckdb：pip install duckdb") from exc
+        conn = duckdb.connect()
+        _DUCK_LOCAL.conn = conn
+    return conn
+
+
+def _sql_file_list(files: List[str]) -> str:
+    """把文件列表转成 ``read_parquet([...])`` 的 SQL 字面量（/ 分隔、转义单引号）。"""
+    return ", ".join("'" + p.replace("\\", "/").replace("'", "''") + "'" for p in files)
+
+
+def _exec_df(sql: str, params: Optional[List[Any]] = None) -> pd.DataFrame:
+    return _duck_conn().execute(sql, params or []).fetchdf()
+
+
+def _detect_local_date_column(files: List[str]) -> Optional[str]:
+    """用 DuckDB 元数据（``LIMIT 0``，不读行数据）探测 V1 文件的日期列。"""
+    sql = f"SELECT * FROM read_parquet([{_sql_file_list(files)}], union_by_name=true) LIMIT 0"
+    names = [col[0] for col in _duck_conn().execute(sql).description]
+    return next((c for c in _V1_DATE_COLUMNS if c in names), None)
+
+
 def _read_local(
     info: DatasetInfo,
     symbol: Optional[str] = None,
@@ -325,52 +372,86 @@ def _read_local(
     root: Optional[str] = None,
     latest: bool = False,
 ) -> pd.DataFrame:
-    """读取本地 Parquet（零流量）。V2/tick 无日期列时从路径注入 ``trade_date``。"""
+    """读取本地 Parquet（零流量）。
+
+    先用多形态 glob 定位**所需分区**（只枚举目录名 / 文件名，不读文件内容），再交给
+    DuckDB 对精确文件列表做**一次** ``read_parquet``，并把 symbol / 日期 / 列裁剪
+    下推到 SQL——不再逐文件 ``pd.read_parquet`` 再 ``concat``。
+
+    V2 按日分区与 tick 分片文件内无日期列，``trade_date`` 由分区目录名 / 文件名推导。
+    """
     files = _local_files(info, symbol, trade_date, root, start_date, end_date)
     if not files:
         raise NotFoundError(f"本地未找到数据集 {info.dataset} 的文件（root={_local_root(root)}）")
     if latest:
         files = [files[-1]]
 
-    need_date_filter = info.layout == "v1_symbol" and bool(start_date or end_date)
-    frames: List[pd.DataFrame] = []
-    for path in files:
-        # V1 需要日期列做区间过滤，先整表读；其余按 columns 下推
-        df = pd.read_parquet(path) if need_date_filter else pd.read_parquet(path, columns=columns)
-        if info.layout == "v2_daily_partition":
-            td = _v2_trade_date(path)
-            if td and "trade_date" not in df.columns:
-                df = df.copy()
-                df["trade_date"] = td
-        elif info.layout == "tick_shard":
-            td = _tick_trade_date(path)
-            if td and "trade_date" not in df.columns:
-                df = df.copy()
-                df["trade_date"] = td
-        frames.append(df)
+    if info.layout == "v1_symbol":
+        return _read_local_v1(files, start_date, end_date, columns)
+    return _read_local_partitioned(info, files, symbol, columns)
 
-    df = frames[0] if len(frames) == 1 else pd.concat(frames, ignore_index=True, sort=False)
 
-    # tick / V2 全市场分区需按 symbol 后置过滤
-    if symbol and "symbol" in df.columns:
-        df = df[df["symbol"].astype(str).str.upper() == str(symbol).strip().upper()].copy()
+def _read_local_partitioned(
+    info: DatasetInfo,
+    files: List[str],
+    symbol: Optional[str],
+    columns: Optional[List[str]],
+) -> pd.DataFrame:
+    """V2 按日分区 / tick 分片：``trade_date`` 由路径推导，读取与过滤下推到 DuckDB。"""
+    if info.layout == "v2_daily_partition":
+        date_expr, order = _V2_DATE_EXPR, " ORDER BY trade_date"
+    else:
+        date_expr, order = _TICK_DATE_EXPR, ""
+
+    if columns:
+        wanted = [c for c in columns if c != "trade_date"]
+        projected = ", ".join(f'"{c}"' for c in wanted)
+        select = f"{projected}, {date_expr} AS trade_date" if projected else f"{date_expr} AS trade_date"
+    else:
+        select = f"* EXCLUDE (filename), {date_expr} AS trade_date"
+
+    where: List[str] = []
+    params: List[Any] = []
+    if symbol:
+        where.append("UPPER(symbol) = ?")
+        params.append(str(symbol).strip().upper())
+
+    sql = f"SELECT {select} FROM read_parquet([{_sql_file_list(files)}], union_by_name=true, filename=true)"
+    if where:
+        sql += " WHERE " + " AND ".join(where)
+    sql += order
+    return _exec_df(sql, params).reset_index(drop=True)
+
+
+def _read_local_v1(
+    files: List[str],
+    start_date: Optional[str],
+    end_date: Optional[str],
+    columns: Optional[List[str]],
+) -> pd.DataFrame:
+    """V1 逐股票 / 单文件：日期列在文件内，用归一化 YYYYMMDD 字符串比较下推过滤。
 
-    if need_date_filter:
-        date_col = _detect_date_column(df)
+    ``substr(replace(CAST(col AS VARCHAR),'-',''),1,8)`` 同时兼容 ``20260331``（整型
+    报告期）与 ``2025-12-31`` / ``2025-12-31 09:30:00``（字符串），无需先探测列类型。
+    """
+    where: List[str] = []
+    params: List[Any] = []
+    if start_date or end_date:
+        date_col = _detect_local_date_column(files)
         if date_col:
-            dt = pd.to_datetime(df[date_col], errors="coerce")
-            mask = pd.Series(True, index=df.index)
+            norm = f"substr(replace(CAST(\"{date_col}\" AS VARCHAR), '-', ''), 1, 8)"
             if start_date:
-                mask &= dt >= pd.to_datetime(_norm_date(start_date))
+                where.append(f"{norm} >= ?")
+                params.append(_yyyymmdd(start_date))
             if end_date:
-                mask &= dt <= pd.to_datetime(_norm_date(end_date))
-            df = df[mask].copy()
-        if columns:
-            df = df.loc[:, [c for c in columns if c in df.columns]]
+                where.append(f"{norm} <= ?")
+                params.append(_yyyymmdd(end_date))
 
-    if info.layout == "v2_daily_partition" and "trade_date" in df.columns:
-        df = df.sort_values("trade_date", kind="stable")
-    return df.reset_index(drop=True)
+    select = ", ".join(f'"{c}"' for c in columns) if columns else "*"
+    sql = f"SELECT {select} FROM read_parquet([{_sql_file_list(files)}], union_by_name=true)"
+    if where:
+        sql += " WHERE " + " AND ".join(where)
+    return _exec_df(sql, params).reset_index(drop=True)
 
 
 # ---------------------------------------------------------------------------
@@ -478,8 +559,11 @@ class DataHub:
     ) -> pd.DataFrame:
         """读取本地已落地的 Parquet（零流量）。
 
-        - ``start_date/end_date`` 先按 ``dt=`` 目录名 / tick 文件名裁剪文件，再读取；
-        - V2 与 tick 文件无日期列时，``trade_date`` 从路径注入；
+        - ``start_date/end_date`` 先按 ``dt=`` 目录名 / tick 文件名裁剪文件（只枚举目录，
+          不读内容），再交给 DuckDB 对精确文件列表做一次 ``read_parquet``；
+        - ``symbol`` / ``columns`` / 日期过滤全部下推到 SQL（宽表只读需要的列），
+          避免逐文件 ``pd.read_parquet`` 再 ``concat``；
+        - V2 与 tick 文件无日期列时，``trade_date`` 由分区目录名 / 文件名推导；
         - ``latest=True`` 只读最新一个文件；
         - 未命中本地文件时抛 ``NotFoundError``（不自动走在线，避免静默消耗流量）。
         """

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.4.0
+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.4.0 → quantdb_sdk-0.4.1}/quantdb_sdk.egg-info/requires.txt

@@ -1,7 +1,7 @@
 requests>=2.25.0
 pandas>=1.3.0
 httpx>=0.24.0
-duckdb>=0.8.0
+duckdb>=1.0.0
 pyarrow>=10.0.0
 
 [dev]

{quantdb_sdk-0.4.0 → quantdb_sdk-0.4.1}/tests/test_data_hub.py

@@ -250,6 +250,32 @@ def test_read_local_v1_date_filter(tmp_path, client):
     assert len(df) == 2
 
 
+def test_read_local_v1_int_report_period_filter(tmp_path, client):
+    """V1 整型报告期（如 m_timetag=20251231）也要能被日期区间正确过滤。"""
+    root = str(tmp_path)
+    path = tmp_path / "3_financial_data" / "income" / "600519.SH.parquet"
+    path.parent.mkdir(parents=True)
+    pd.DataFrame({
+        "Symbol": ["600519.SH"] * 3,
+        "m_timetag": [20251231, 20250930, 20250630],
+        "x": [1, 2, 3],
+    }).to_parquet(path)
+    df = client.data.read_local("income", symbol="600519.SH", root=root,
+                                start_date="2025-09-01", end_date="2025-12-31")
+    assert len(df) == 2
+
+
+def test_read_local_v2_columns_projection_and_symbol_pushdown(tmp_path, client):
+    """V2：列裁剪下推 + symbol 下推（symbol 不在 columns 里也照样过滤）。"""
+    root = str(tmp_path)
+    _write_v2(root, "daily_forward", ["20260901"])
+    df = client.data.read_local("daily_forward", symbol="600519.SH", columns=["close"], root=root)
+    assert list(df.columns) == ["close", "trade_date"]
+    assert len(df) == 1
+    assert df.iloc[0]["close"] == 1.0
+    assert df.iloc[0]["trade_date"] == "2026-09-01"
+
+
 def test_local_path_precise_hit(tmp_path, client):
     root = str(tmp_path)
     _write_v2(root, "daily_forward", ["20260901"])