quantdb-sdk 0.4.7__tar.gz → 0.5.0__tar.gz

{quantdb_sdk-0.4.7 → quantdb-sdk-0.5.0}/CHANGELOG.md

@@ -3,6 +3,62 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## \[Unreleased]
+
+### Removed
+
+- **移除演示脚本包 `quantdb_sdk.examples`**（demo_01 ~ demo_07，共 7 个脚本）：不再随 wheel 发布。CLI 帮助与文档中的演示脚本指引已同步删除，改用 `quantdb layout` / `quantdb datasets` 自述目录规范与数据集目录。
+
+## \[0.5.0] - 2026-10-31
+
+### Added
+
+- **字段字典接入（列级字段说明）**：数据集可以自带一份字段字典 JSON（随数据集放在 COS），SDK 现在能直接读到列级的「中文名 / 公式 / 释义 / 分组 / 来源 / 方向」。首批支持 `factor_dictionary`（V5 全因子宽表，571 列 = 2 键 + 6 列后复权 OHLCV + 563 因子）。
+  - `client.get_fields(sub_category, group=..., query=..., field=..., limit=...)` → 列明细 DataFrame；
+  - `client.get_field_groups(sub_category)` → 分组摘要（组名 + 字段数）；
+  - `client.get_field_dictionary(...)` → 原始响应（含 `schema_version` / `total_columns` / `groups`）；
+  - `client.data.fields(...)` / `client.data.field_groups(...)` 为 Hub 层封装；
+  - 异步端对应 `a_get_fields` / `a_get_field_groups` / `a_get_field_dictionary` 与 `a_fields` / `a_field_groups`；
+  - `client.data.info("factor_dictionary")` 现在额外返回 `field_count` 与 `field_groups`（没有字典的数据集不受影响，404 被静默忽略）。
+  - 新增 CLI：`quantdb fields factor_dictionary [--group/--query/--field/--limit/--json]`，不带过滤条件时打印分组摘要。
+- 字典接口**不消耗下载流量**；摘要响应在客户端进程内缓存，重复调用不重复请求（也不额外占用 30/min 限流额度）。
+
+### Changed
+
+- `describe_dataset`（MCP）在有字典时额外返回 `field_groups` / `field_count`，并提示用 `describe_fields` 查看列明细。
+
+## \[0.4.9] - 2026-10-31
+
+### Added
+
+- **注册新数据集 `factor_dictionary`（第 6 大类，订阅级）**：V5 全因子宽表，571 列（8 个键与后复权 OHLCV + 563 个因子），COS 布局为 `6_ml_datasets/factor_dictionary/dt=YYYYMMDD/data.parquet`。此前该数据集在 SDK 侧完全未注册，`client.data.*` / `sync_dataset` / `mount_local_dataset` / CLI / MCP 全部拒绝。本次补齐三张表：
+  - `_utils.SYNC_DATASET_CATEGORIES` 加 `"factor_dictionary" -> "6"`；
+  - `hub._ENTRIES` 加一条注册表条目（名称/描述/`subscription`/关键词/`v2_daily_partition`/选择器）；
+  - `layout.V2_DAILY_PARTITION` 加 `factor_dictionary`。
+
+### Fixed
+
+- **`layout.V2_DAILY_PARTITION` 与 COS 实际布局漂移**：补入 `min1_kline`、`min5_kline`、`etf_kline`。经 COS 复核，四者均为 `{category}/{sub}/dt=YYYYMMDD/data.parquet`，此前被 `dataset_layout()` 误判为 `v1_symbol`，导致公开 API `dataset_layout()` / `local_relative_path()` 与 `quantdb layout` 输出错误路径（etf_kline 的 V1 逐股票文件在 COS 上早已删除）。
+- `hub` 模块 docstring 与 `DATASET_REGISTRY` 注释中的数据集数量（29）更正为 31；`__init__.__version__` 的 importlib 回退值（0.4.5）同步到 0.4.9。
+
+### Known issues
+
+- `tick_data` 在 COS 上同样是 `dt=YYYYMMDD/data.parquet`（单日全市场约 189 MB），但 SDK 仍按 `tick_shard` 处理本地读取（`{SYM}_{YYYYMMDD}.parquet` glob + 文件名取日期）。带 `symbol` 的 `read_local("tick_data", ...)` 因此找不到 dt 分区，属既有缺陷，切换布局是行为变更，留待单独修复。
+
+## \[0.4.8] - 2026-10-27
+
+### Fixed
+
+- **`quantdb usage` 在中文 Windows 控制台崩溃**：`余额` 一行输出的是窄人民币符号 U+00A5，而 Windows 中文控制台默认编码是 GBK/cp936，**GBK 中不存在该字符**（GBK 用 0x80 表示），`print` 抛 `UnicodeEncodeError: 'gbk' codec can't encode character '\xa5'`，命令以异常收场、后续输出（订阅状态等）全部丢失。
+  修复两处：① 金额改用**全角人民币符号 U+FFE5**（GBK 可编码，中文终端显示正常）；② CLI 入口新增 `_configure_stdout()`，把 stdout/stderr 的编码错误处理降级为 `replace`——以后任何不可编码字符只会显示为 `?`，不再中断命令。
+
+### Added
+
+- 新增回归测试 `tests/test_cli_encoding.py`（仓库根 `tests/`，不进 wheel）：
+  - 扫描 SDK 全部源码的**字符串字面量**，断言每个字符都能被 GBK 编码——防止再次引入不可编码字符；
+  - 在 GBK 编码的 stdout 下渲染用量输出，断言不抛异常；
+  - 断言 `_configure_stdout()` 确实把编码错误处理改为 `replace`。
+
 ## \[0.4.7] - 2026-10-27
 
 ### Fixed
@@ -17,20 +73,20 @@
 
 > 兼容性：0.4.7 对接 2026-10-27 上线的服务端版本；旧服务端（两跳 cdn-bridge）仍可正常同步，无需回退。
 
-## \[0.4.6] - 2026-10-27
-
-### Fixed
-
-- **增量同步的「检查更新」不再重复计费**：`sync_dataset` 此前对本地已存在的文件先发一次带 `If-None-Match` 的 GET 探测版本。ETag 命中时服务端在预扣前返回 304（免流量），但**ETag 不匹配时（对象已更新，正是需要下载的常见情况）该请求会继续走到流量预扣 + CDN 直连，把整个文件传完**，客户端却丢弃响应体再重下一次。CDN 直连模式签发即计费、不退款，于是「检查更新」被白白计费一次。
-
-  实测近 2 天生产数据：下载请求 309,973 次但只涉及 71,675 个不同文件（**放大到 4.3 倍**），其中 **93.6% 是同 ETag 的纯重复下载**，纯浪费带宽与用户流量。
-
-  修复：探测改用服务端新增的 `HEAD /api/v1/data/download`——只回 ETag 与长度，在流量预扣之前返回，**零流量、零令牌、零 PG 事务**。ETag 命中时同样返回 304。同步与异步客户端的 V2 release 与 V1 manifest 两条探测路径均已改用 HEAD。
-
-  客户端侧行为不变：探测结果与本地记录一致即免流量跳过，不一致才真正下载。
-
-  兼容性：服务端不支持 HEAD 时（老版本返回 405）自动退回原 GET 流程，不影响可用性。
-
+## \[0.4.6] - 2026-10-27
+
+### Fixed
+
+- **增量同步的「检查更新」不再重复计费**：`sync_dataset` 此前对本地已存在的文件先发一次带 `If-None-Match` 的 GET 探测版本。ETag 命中时服务端在预扣前返回 304（免流量），但**ETag 不匹配时（对象已更新，正是需要下载的常见情况）该请求会继续走到流量预扣 + CDN 直连，把整个文件传完**，客户端却丢弃响应体再重下一次。CDN 直连模式签发即计费、不退款，于是「检查更新」被白白计费一次。
+
+  实测近 2 天生产数据：下载请求 309,973 次但只涉及 71,675 个不同文件（**放大到 4.3 倍**），其中 **93.6% 是同 ETag 的纯重复下载**，纯浪费带宽与用户流量。
+
+  修复：探测改用服务端新增的 `HEAD /api/v1/data/download`——只回 ETag 与长度，在流量预扣之前返回，**零流量、零令牌、零 PG 事务**。ETag 命中时同样返回 304。同步与异步客户端的 V2 release 与 V1 manifest 两条探测路径均已改用 HEAD。
+
+  客户端侧行为不变：探测结果与本地记录一致即免流量跳过，不一致才真正下载。
+
+  兼容性：服务端不支持 HEAD 时（老版本返回 405）自动退回原 GET 流程，不影响可用性。
+
 ## \[0.4.5] - 2026-10-18
 
 ### Added

{quantdb_sdk-0.4.7/quantdb_sdk.egg-info → quantdb-sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: quantdb-sdk
-Version: 0.4.7
+Version: 0.5.0
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -22,18 +22,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Office/Business :: Financial
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.25.0
-Requires-Dist: pandas>=1.3.0
-Requires-Dist: httpx>=0.24.0
-Requires-Dist: duckdb>=1.0.0
-Requires-Dist: pyarrow>=10.0.0
 Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
-Requires-Dist: responses>=0.23.0; extra == "dev"
-Requires-Dist: respx>=0.20.0; extra == "dev"
-Dynamic: license-file
+License-File: LICENSE
 
 # QuantDB Python SDK
 

{quantdb_sdk-0.4.7 → quantdb-sdk-0.5.0}/pyproject.toml

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

{quantdb_sdk-0.4.7 → quantdb-sdk-0.5.0}/quantdb_sdk/__init__.py

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

{quantdb_sdk-0.4.7 → quantdb-sdk-0.5.0}/quantdb_sdk/__main__.py

@@ -7,9 +7,6 @@
   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），
-如: python -m quantdb_sdk.examples.demo_03_sync_full_market
 """
 
 import argparse
@@ -63,11 +60,46 @@ def cmd_datasets(name: Optional[str] = None) -> int:
     return 0
 
 
+def _configure_stdout() -> None:
+    """让 CLI 在非 UTF-8 控制台（中文 Windows 默认 GBK/cp936）下不因不可编码字符崩溃。
+
+    Windows 中文控制台的默认编码是 GBK，而窄人民币符号 U+00A5 在 GBK 中**不存在**
+    （GBK 用 0x80 表示该符号），直接 print 会抛
+    ``UnicodeEncodeError: 'gbk' codec can't encode character '\\xa5'``，
+    导致整条命令以异常收场、后续输出全部丢失。
+
+    这里把 stdout/stderr 的编码错误处理改成 replace：无法编码的字符降级为 '?'，
+    命令本身不再中断。配合正文中改用全角 ￥（U+FFE5，GBK 可编码），
+    中文 Windows 终端可正常显示金额。
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")  # type: ignore[attr-defined]
+        except Exception:  # pragma: no cover - 老版本/非 TextIOWrapper 忽略
+            pass
+
+
+def print_usage(usage: dict) -> None:
+    """打印账户用量（抽成独立函数便于单测覆盖非 UTF-8 控制台场景）。"""
+    print("账户用量:")
+    print(f"  套餐:   已用 {usage['plan_used_gb']:.2f} GB / {usage['plan_total_gb']:.2f} GB"
+          f"（剩余 {usage['plan_remaining_gb']:.2f} GB）")
+    print(f"  流量包: 已用 {usage['package_used_gb']:.2f} GB / {usage['package_total_gb']:.2f} GB"
+          f"（剩余 {usage['package_remaining_gb']:.2f} GB）")
+    print(f"  合计:   已用 {usage['used_gb']:.2f} GB / {usage['total_gb']:.2f} GB"
+          f"（剩余 {usage['remaining_gb']:.2f} GB）")
+    # 全角人民币符号 U+FFE5：GBK 可编码；窄符号 U+00A5 在 GBK 中不存在会崩溃
+    print(f"  余额: ￥{usage['balance_yuan']:.2f}")
+    sub = usage.get("subscription", {})
+    print(f"  订阅: {sub.get('status', 'none')}")
+
+
 def main() -> int:
+    _configure_stdout()
     parser = argparse.ArgumentParser(
         prog="quantdb",
         description="QuantDB 量化数据平台官方 Python SDK",
-        epilog="演示脚本: python -m quantdb_sdk.examples.demo_01 .. demo_06；目录规范: quantdb layout",
+        epilog="目录规范: quantdb layout；数据集目录: quantdb datasets",
     )
     parser.add_argument(
         "--version",
@@ -115,6 +147,14 @@ def main() -> int:
     download_parser.add_argument("--save-dir", default=None, help="本地数据根目录")
     download_parser.add_argument("--json", action="store_true", help="输出 JSON 保存路径和文件大小")
 
+    fields_parser = subparsers.add_parser("fields", help="查询数据集的字段字典（列级说明，不消耗流量）")
+    fields_parser.add_argument("dataset", help="数据集，如 factor_dictionary")
+    fields_parser.add_argument("--group", default=None, help="分组子串，如 动量 / L2 2.1")
+    fields_parser.add_argument("--query", default=None, help="在字段名/中文名/释义/公式上子串匹配")
+    fields_parser.add_argument("--field", default=None, help="精确字段名，如 turn_1")
+    fields_parser.add_argument("--limit", type=int, default=None, help="返回列数上限（默认 200）")
+    fields_parser.add_argument("--json", action="store_true", help="输出 JSON")
+
     args = parser.parse_args()
 
     if not args.command:
@@ -158,16 +198,7 @@ def main() -> int:
 
         if args.command == "usage":
             usage = client.get_usage()
-            print(f"账户用量:")
-            print(f"  套餐:   已用 {usage['plan_used_gb']:.2f} GB / {usage['plan_total_gb']:.2f} GB"
-                  f"（剩余 {usage['plan_remaining_gb']:.2f} GB）")
-            print(f"  流量包: 已用 {usage['package_used_gb']:.2f} GB / {usage['package_total_gb']:.2f} GB"
-                  f"（剩余 {usage['package_remaining_gb']:.2f} GB）")
-            print(f"  合计:   已用 {usage['used_gb']:.2f} GB / {usage['total_gb']:.2f} GB"
-                  f"（剩余 {usage['remaining_gb']:.2f} GB）")
-            print(f"  余额: ¥{usage['balance_yuan']:.2f}")
-            sub = usage.get("subscription", {})
-            print(f"  订阅: {sub.get('status', 'none')}")
+            print_usage(usage)
             return 0
 
         if args.command == "sync":
@@ -179,6 +210,32 @@ def main() -> int:
                 print(f"  Release: {result['release_id']}")
             return 0
 
+        if args.command == "fields":
+            filtered = bool(args.group or args.query or args.field)
+            if args.json:
+                payload = client.get_field_dictionary(
+                    args.dataset, group=args.group, query=args.query,
+                    field=args.field, limit=args.limit,
+                )
+                print(json.dumps(payload, ensure_ascii=False))
+                return 0
+            if not filtered:
+                groups = client.get_field_groups(args.dataset)
+                print(f"{args.dataset} 字段分组（共 {int(groups['count'].sum())} 列）：")
+                for _, row in groups.iterrows():
+                    print(f"  {int(row['count']):>4}  {row['group']}")
+                print("\n加 --group / --query / --field 查看列明细。")
+                return 0
+            df = client.get_fields(args.dataset, group=args.group, query=args.query,
+                                   field=args.field, limit=args.limit)
+            if df.empty:
+                print("没有匹配的字段。")
+                return 0
+            print(f"匹配 {len(df)} 列：")
+            for _, row in df.iterrows():
+                print(f"  {row['field']:<32} {row['name_cn']:<18} [{row['group']}]")
+            return 0
+
     except Exception as e:
         print(f"[ERROR] {e}", file=sys.stderr)
         return 1

{quantdb_sdk-0.4.7 → quantdb-sdk-0.5.0}/quantdb_sdk/_utils.py

@@ -23,6 +23,7 @@ SYNC_DATASET_CATEGORIES: Dict[str, str] = {
     "etf_pcf": "4", "convertible_bond": "4", "etf_kline": "4",
     "valuation": "5", "technical_indicators": "5", "market_sentiment": "5",
     "features_daily": "6", "l1_factors": "6", "l1_l2_factors": "6", "l2_factors": "6",
+    "factor_dictionary": "6",
 }
 
 

{quantdb_sdk-0.4.7 → quantdb-sdk-0.5.0}/quantdb_sdk/async_client.py

@@ -28,7 +28,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.7"
+_USER_AGENT = "QuantDB-Python-SDK/0.5.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]] = {}
 
+        # 字段字典摘要缓存（dataset -> 原始响应），与同步客户端同语义。
+        self._field_cache: Dict[str, Dict[str, Any]] = {}
+
         # 统一数据入口（quantdb_sdk.hub.AsyncDataHub）惰性实例，见 data property。
         self._data_hub: Optional[Any] = None
 
@@ -609,6 +612,61 @@ class AsyncQuantDBClient:
             df["file_size_gb"] = df["file_size"].fillna(0).map(bytes_to_gb).round(2)
         return df
 
+    # ========== 字段字典（列级说明，不消耗下载流量） ==========
+
+    async def a_get_field_dictionary(
+        self,
+        sub_category: str,
+        group: Optional[str] = None,
+        query: Optional[str] = None,
+        field: Optional[str] = None,
+        limit: Optional[int] = None,
+        use_cache: bool = True,
+    ) -> Dict[str, Any]:
+        """返回字段字典原始响应（异步）：schema 信息 + ``groups`` [+ ``columns``]。
+
+        不带过滤条件时服务端只返回分组摘要；同一进程内摘要会缓存复用。
+        """
+        filtered = bool(group or query or field)
+        cache_key = f"summary:{sub_category}"
+        if use_cache and not filtered and cache_key in self._field_cache:
+            return self._field_cache[cache_key]
+
+        params: Dict[str, Any] = {"sub_category": sub_category}
+        if group:
+            params["group"] = group
+        if query:
+            params["query"] = query
+        if field:
+            params["field"] = field
+        if limit:
+            params["limit"] = int(limit)
+        payload = await self._get("/api/v1/data/fields", params)
+        if use_cache and not filtered:
+            self._field_cache[cache_key] = payload
+        return payload
+
+    async def a_get_fields(
+        self,
+        sub_category: str,
+        group: Optional[str] = None,
+        query: Optional[str] = None,
+        field: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """查询列级字段说明（异步）；必须带 group / query / field 之一。"""
+        payload = await self.a_get_field_dictionary(
+            sub_category, group=group, query=query, field=field, limit=limit,
+        )
+        columns = payload.get("columns") or []
+        return pd.DataFrame(columns, columns=["field", "name_cn", "formula", "description",
+                                              "group", "source", "direction", "order"])
+
+    async def a_get_field_groups(self, sub_category: str) -> pd.DataFrame:
+        """字段分组摘要（异步）：``group`` + ``count``。"""
+        payload = await self.a_get_field_dictionary(sub_category)
+        return pd.DataFrame(payload.get("groups") or [], columns=["group", "count"])
+
     # ========== 数据预览与下载 ==========
 
     async def a_preview_as_df(

{quantdb_sdk-0.4.7 → quantdb-sdk-0.5.0}/quantdb_sdk/client.py

@@ -32,7 +32,13 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.7"
+_USER_AGENT = "QuantDB-Python-SDK/0.5.0"
+
+# 字段字典的列顺序（与后端 /api/v1/data/fields 返回的 columns[] 一致）
+_FIELD_COLUMNS = (
+    "field", "name_cn", "formula", "description",
+    "group", "source", "direction", "order",
+)
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -95,6 +101,10 @@ class QuantDBClient:
         # 只需下载一次。进程退出即失效（无跨进程副作用）。
         self._cache: Dict[str, Dict[str, Any]] = {}
 
+        # 字段字典摘要缓存（dataset -> 原始响应）：字典是静态文件，
+        # 同一进程内重复 info()/get_field_groups() 不必反复请求（也不吃 30/min 限流）。
+        self._field_cache: Dict[str, Dict[str, Any]] = {}
+
         # 统一数据入口（quantdb_sdk.hub.DataHub）惰性实例，见 data property。
         self._data_hub: Optional[Any] = None
 
@@ -145,29 +155,29 @@ class QuantDBClient:
         resp = self._request("GET", path, params=params)
         return self._check_response(resp)
 
-    def _probe_head(self, params: dict, headers: Optional[dict] = None) -> requests.Response:
-        """HEAD 探测对象元数据（增量同步的「检查更新」）：零流量、零令牌、零计费。
-
-        服务端在流量预扣之前返回 ETag 与 Content-Length，客户端与本地记录
-        比对后决定是否需要真正下载。
-
-        为什么必须用 HEAD 而不是带 If-None-Match 的 GET：
-        GET 探测在 ETag 不匹配时（对象已更新，正是需要下载的常见情况）会
-        继续走到流量预扣 + CDN 直连，把整个文件传完；客户端却丢弃响应体
-        再重下一次。CDN 直连模式签发即计费、不退款，于是「检查更新」被
-        白白计费一次——实测近 2 天下载请求量放大到文件数的 4.3 倍，
-        其中 93.6% 是同 ETag 的纯重复下载。
-
-        服务端不支持 HEAD 时（老版本）返回 405，调用方应退回 GET 流程。
-        """
-        try:
-            return self._request(
-                "HEAD", "/api/v1/data/download", params=params,
-                headers=headers, allow_redirects=False,
-            )
-        except requests.RequestException:
-            return requests.Response()
-
+    def _probe_head(self, params: dict, headers: Optional[dict] = None) -> requests.Response:
+        """HEAD 探测对象元数据（增量同步的「检查更新」）：零流量、零令牌、零计费。
+
+        服务端在流量预扣之前返回 ETag 与 Content-Length，客户端与本地记录
+        比对后决定是否需要真正下载。
+
+        为什么必须用 HEAD 而不是带 If-None-Match 的 GET：
+        GET 探测在 ETag 不匹配时（对象已更新，正是需要下载的常见情况）会
+        继续走到流量预扣 + CDN 直连，把整个文件传完；客户端却丢弃响应体
+        再重下一次。CDN 直连模式签发即计费、不退款，于是「检查更新」被
+        白白计费一次——实测近 2 天下载请求量放大到文件数的 4.3 倍，
+        其中 93.6% 是同 ETag 的纯重复下载。
+
+        服务端不支持 HEAD 时（老版本）返回 405，调用方应退回 GET 流程。
+        """
+        try:
+            return self._request(
+                "HEAD", "/api/v1/data/download", params=params,
+                headers=headers, allow_redirects=False,
+            )
+        except requests.RequestException:
+            return requests.Response()
+
     def _download_stream(self, params: dict, headers: Optional[dict] = None) -> requests.Response:
         """下载专用流式请求：手动处理服务端 302 CDN 直连跳转。
 
@@ -684,6 +694,77 @@ class QuantDBClient:
             df["file_size_gb"] = df["file_size"].fillna(0).map(bytes_to_gb).round(2)
         return df
 
+    # ========== 字段字典（列级说明，不消耗下载流量） ==========
+
+    def get_field_dictionary(
+        self,
+        sub_category: str,
+        group: Optional[str] = None,
+        query: Optional[str] = None,
+        field: Optional[str] = None,
+        limit: Optional[int] = None,
+        use_cache: bool = True,
+    ) -> Dict[str, Any]:
+        """返回字段字典原始响应（schema 信息 + ``groups`` 分组摘要 [+ ``columns``]）。
+
+        字典由数据侧随数据集发布（如 ``factor_dictionary`` 的
+        ``v5_factor_dictionary.json``），后端读取 COS 后缓存，**不消耗下载流量**。
+
+        :param sub_category: 数据集标识，如 ``factor_dictionary``。
+        :param group: 可选，分组子串匹配（如 ``动量`` / ``L2 2.1``）。
+        :param query: 可选，在字段名/中文名/释义/公式上做子串匹配。
+        :param field: 可选，精确字段名（如 ``turn_1``）。
+        :param limit: 可选，返回列数上限（服务端默认 200，最大 1000）。
+        :param use_cache: 同一进程内复用已取过的「摘要」响应（仅当不带过滤条件时）。
+        :raises NotFoundError: 该数据集没有字段字典。
+        """
+        filtered = bool(group or query or field)
+        cache_key = f"summary:{sub_category}"
+        if use_cache and not filtered and cache_key in self._field_cache:
+            return self._field_cache[cache_key]
+
+        params: Dict[str, Any] = {"sub_category": sub_category}
+        if group:
+            params["group"] = group
+        if query:
+            params["query"] = query
+        if field:
+            params["field"] = field
+        if limit:
+            params["limit"] = int(limit)
+        payload = self._get("/api/v1/data/fields", params)
+        if use_cache and not filtered:
+            self._field_cache[cache_key] = payload
+        return payload
+
+    def get_fields(
+        self,
+        sub_category: str,
+        group: Optional[str] = None,
+        query: Optional[str] = None,
+        field: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """查询某数据集的列级字段说明（中文名 / 公式 / 释义 / 分组 / 方向）。
+
+        **必须带 ``group`` / ``query`` / ``field`` 之一**：不带过滤条件时服务端只返回
+        分组摘要（571 列全量下发会撑爆调用方上下文），此时返回空 DataFrame，
+        请改用 :meth:`get_field_groups`。
+
+        :return: DataFrame，列为 ``field`` / ``name_cn`` / ``formula`` /
+            ``description`` / ``group`` / ``source`` / ``direction`` / ``order``。
+        """
+        payload = self.get_field_dictionary(
+            sub_category, group=group, query=query, field=field, limit=limit,
+        )
+        columns = payload.get("columns") or []
+        return pd.DataFrame(columns, columns=list(_FIELD_COLUMNS))
+
+    def get_field_groups(self, sub_category: str) -> pd.DataFrame:
+        """字段分组摘要（``group`` 组名 + ``count`` 字段数），不消耗下载流量。"""
+        payload = self.get_field_dictionary(sub_category)
+        return pd.DataFrame(payload.get("groups") or [], columns=["group", "count"])
+
     # ========== 数据预览与下载（消耗下载流量） ==========
 
     def preview_as_df(

{quantdb_sdk-0.4.7 → quantdb-sdk-0.5.0}/quantdb_sdk/hub.py

@@ -9,7 +9,7 @@
     from quantdb_sdk import QuantDBClient
 
     client = QuantDBClient(api_key="qdb_xxx")
-    client.data.datasets()                         # 29 个数据集目录（零流量）
+    client.data.datasets()                         # 31 个数据集目录（零流量）
     client.data.info("l1_factors")                 # 覆盖区间 + 文件大小
     client.data.read_local("daily_forward", start_date="2026-09-01")   # 本地零流量
     client.data.preview("balance", symbol="600519.SH")                 # 在线预览
@@ -21,7 +21,8 @@
   ``category_dir`` 复用 :data:`quantdb_sdk.layout.CATEGORY_DIRS`，避免重复维护分类事实源。
 - ``layout`` 记录数据集的**实际 COS 形态**（``v2_daily_partition`` / ``v1_symbol`` /
   ``tick_shard``），用于 ``query()`` 路由；不用 :func:`quantdb_sdk.layout.dataset_layout`
-  （其 V2 集合已过期，缺 min1/min5/etf/tick）。
+  （其 V2 集合截至 2026-10-31 已与 COS 对齐，但 tick_data 例外：COS 已改为 dt= 分区，
+  本地读取仍是分片语义）。
 - 本地读取用**多形态 glob** 与目录布局集合解耦，支持显式 ``root``（数据根目录可配置，
   非固定目录；缺省读 :func:`quantdb_sdk.layout.data_root`）；读取本身交给 DuckDB 对
   精确文件列表做一次 ``read_parquet``（列裁剪 / symbol / 日期下推），不逐文件拼接。
@@ -157,6 +158,8 @@ _ENTRIES: Tuple[Tuple[str, str, str, str, Tuple[str, ...], str, Tuple[str, ...]]
      ("l2", "因子", "factor"), "v2_daily_partition", ("symbol", "trade_date")),
     ("l1_l2_factors", "L1+L2 合并因子", "L1 和 L2 的合并宽表。", "subscription",
      ("l1", "l2", "因子", "factor", "合并"), "v2_daily_partition", ("symbol", "trade_date")),
+    ("factor_dictionary", "V5 因子宽表", "V5 全因子宽表：571 列（2 键 + 6 列后复权 OHLCV + 563 因子），按交易日分区；字段字典见数据集目录内 v5_factor_dictionary.json。", "subscription",
+     ("因子", "factor", "v5", "宽表", "f500", "字典"), "v2_daily_partition", ("symbol", "trade_date")),
 )
 
 
@@ -178,7 +181,7 @@ def _build_registry() -> Dict[str, DatasetInfo]:
     return registry
 
 
-#: dataset 名 -> DatasetInfo（29 项）
+#: dataset 名 -> DatasetInfo（31 项）
 DATASET_REGISTRY: Dict[str, DatasetInfo] = _build_registry()
 
 
@@ -509,7 +512,9 @@ class DataHub:
         """返回数据集注册表信息，并可选叠加云端元数据（覆盖区间/文件数/大小）。
 
         ``with_meta=True``（默认）时叠加 ``client.query_meta(sub_category=dataset)``
-        的 ``min_date/max_date/file_count/file_size_gb/row_count/updated_at``。
+        的 ``min_date/max_date/file_count/file_size_gb/row_count/updated_at``，
+        并在该数据集带**字段字典**时额外叠加 ``field_count`` 与 ``field_groups``
+        （如 ``factor_dictionary`` 的 571 列分组）。没有字典的数据集不受影响。
         """
         entry = _info(dataset).to_dict()
         if not with_meta:
@@ -519,8 +524,36 @@ class DataHub:
         except Exception:
             meta = None
         entry.update(_meta_row(meta))
+        try:
+            fields = self._client.get_field_dictionary(dataset)
+        except Exception:
+            fields = None
+        if isinstance(fields, dict) and fields.get("groups"):
+            entry["field_count"] = fields.get("total_columns")
+            entry["field_groups"] = fields.get("groups")
         return entry
 
+    def fields(
+        self,
+        dataset: str,
+        group: Optional[str] = None,
+        query: Optional[str] = None,
+        field: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """查询列级字段说明（中文名 / 公式 / 释义 / 分组 / 方向），不消耗下载流量。
+
+        必须带 ``group`` / ``query`` / ``field`` 之一，否则服务端只回分组摘要、
+        返回空 DataFrame（用 :meth:`field_groups` 拿摘要）。
+        """
+        return self._client.get_fields(
+            _info(dataset).dataset, group=group, query=query, field=field, limit=limit,
+        )
+
+    def field_groups(self, dataset: str) -> pd.DataFrame:
+        """字段分组摘要（``group`` + ``count``），不消耗下载流量。"""
+        return self._client.get_field_groups(_info(dataset).dataset)
+
     def local_files(
         self,
         dataset: str,
@@ -827,7 +860,7 @@ class AsyncDataHub:
         return pd.DataFrame(rows, columns=cols)
 
     async def a_info(self, dataset: str, with_meta: bool = True) -> Dict[str, Any]:
-        """异步版 :meth:`DataHub.info`。"""
+        """异步版 :meth:`DataHub.info`（含字段字典分组摘要）。"""
         entry = _info(dataset).to_dict()
         if not with_meta:
             return entry
@@ -836,8 +869,32 @@ class AsyncDataHub:
         except Exception:
             meta = None
         entry.update(_meta_row(meta))
+        try:
+            fields = await self._client.a_get_field_dictionary(dataset)
+        except Exception:
+            fields = None
+        if isinstance(fields, dict) and fields.get("groups"):
+            entry["field_count"] = fields.get("total_columns")
+            entry["field_groups"] = fields.get("groups")
         return entry
 
+    async def a_fields(
+        self,
+        dataset: str,
+        group: Optional[str] = None,
+        query: Optional[str] = None,
+        field: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """异步版 :meth:`DataHub.fields`。"""
+        return await self._client.a_get_fields(
+            _info(dataset).dataset, group=group, query=query, field=field, limit=limit,
+        )
+
+    async def a_field_groups(self, dataset: str) -> pd.DataFrame:
+        """异步版 :meth:`DataHub.field_groups`。"""
+        return await self._client.a_get_field_groups(_info(dataset).dataset)
+
     async def a_local_files(
         self,
         dataset: str,