quantdb-sdk 0.2.7__tar.gz → 0.3.3__tar.gz

{quantdb_sdk-0.2.7 → quantdb_sdk-0.3.3}/CHANGELOG.md

@@ -1,118 +1,178 @@
-# Changelog
-
-所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
-版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
-
-## [0.2.7] - 2026-07-29
-
-### Fixed
-- **V1 回退对纯 V2 数据集失效**：`query_kline` / `a_query_kline` 无日期范围时不再默认走 V1。`margin_trading`、`features_daily`、`l1_factors`、`l2_factors` 等 11 个纯 V2 数据集在 COS 上已无 V1 逐股票文件，V1 回退会 404。现在无范围时也走 V2 manifest 路径（manifest 列出的所有分区全量下载），仅在有日期范围时才做日历完整性校验。显式 `layout="v1"` 仍可直接走逐股票文件。
-- **异步客户端时区处理不一致**：`AsyncQuantDBClient._normalise_kline` 缺少 `tz_convert` 逻辑，与同步客户端行为不一致（相同输入可能产生不同的 `trade_date` 字符串），已对齐。
-
-## [0.2.6] - 2026-07-27
-
-### Fixed
-- **适配服务端 CDN 直连下载（302 跳转）**：异步客户端（httpx 默认不跟随重定向）此前在服务端开启 302 直连后所有下载/同步接口失效，现已修复。
-- **凭证保护**：同步客户端此前跟随 302 时会把 `X-API-Key` 透传给 CDN 域；现两个客户端统一改为「手动处理 302 + 无鉴权头裸请求直连 CDN」，凭证只发给 QuantDB 网关。
-- 302 响应中的 COS ETag 回填至 CDN 响应，保证进程内 ETag 缓存与 If-None-Match 304 逻辑不受影响。
-
-### Security (后端)
-- **一次性下载令牌**：302 直连模式改为两跳（`/download` → `/cdn-bridge?token=xxx` → CDN），令牌一次性消费，防止签名 URL 被重复使用或分享给他人免费下载。
-- **移除 `?direct=1` 请求级覆盖**：用户无法再通过请求参数强制走 302 模式，仅全局开关 `QUANTDB_DOWNLOAD_REDIRECT` 可控制。
-- 令牌有效期 90s，远小于 CDN 签名有效期 300s，窗口极小。
-
-### Data Architecture (COS)
-- **V2 数据集全面清理 V1 残留**：COS 上 11 个 V2 数据集已删除全部 V1 逐股票文件（~1.8 万对象），实现纯 V2 存储。ListObjects 分页效率提升 3-5 倍。
-- **L1 日频因子 V2 全量上线**：`l1_factors` 2565 个交易日分区（2016-01-04 ~ 至今），支持按日范围高效查询。
-- **L2 高频因子 V2 上线**：`l2_factors` 34 个交易日分区（2026-01-05 ~ 2026-02-27）。
-- **融资融券纯 V2**：`margin_trading` 已从 V1 迁移至纯 V2 按日分区（2563 个分区）。
-
-## [0.2.5] - 2026-07-26
-
-### Security
-- 下载响应文件名与 release/Manifest 相对路径均限制在指定下载目录内，防止路径穿越。
-- 公网 API Host 强制 HTTPS；CLI 改从环境变量读取 API Key，避免密钥出现在命令历史和进程参数中。
-- 下载增加单文件大小上限（默认 2 GiB，可通过 `QUANTDB_MAX_DOWNLOAD_BYTES` 配置）。
-- `query_local()` / `a_query_local()` 只接受 WHERE 条件，拒绝完整 SQL、JOIN 和外部表函数。
-
-### Documentation
-- 更新官网 SDK 文档：并发下载建议、V1/V2 选择、安全配置与异常处理。
-
-## [0.2.4] - 2026-07-26
-
-### Fixed
-- **Windows CLI 编码**：移除 `✓/✗` 字符，GBK 控制台可正常执行 `quantdb check`。
-
-## [0.2.3] - 2026-07-26
+# Changelog
+
+所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+
+## [0.3.3] - 2026-08-29
 
 ### Added
-- **财务本地仓库**：`mount_local_dataset()` 支持财务 V1、ETF/可转债与更多日频子类；财务数据以 `Symbol + m_timetag/endDate/time` 业务主键去重。
-
-## [0.2.2] - 2026-07-26
-
-### Added
-- **全数据集增量同步**：`sync_dataset()` / `a_sync_dataset()` 覆盖基础、财务、ETF/可转债、行情、技术与 ML 子类；没有 V2 release 的数据集自动走 V1 Manifest。
-- **CLI 同步**：新增 `quantdb sync <api_key> <dataset> --save-dir <目录>`。
-
-### Fixed
-- **V1 强校验**：V1 Manifest 同步以 ETag + size 判断变更，并在原子落盘前验证实际字节数。
-- **同步/异步一致性**：异步 release 同步采用 `relative_path`，SQLite 同时记录对象大小，与同步客户端保持同构目录和恢复语义。
-
-## [0.2.1] - 2026-07-26
+- **本地完整性扫描 `scan_local_directory`**，并作为 `QuantDBClient.scan_local()` / `AsyncQuantDBClient.a_scan_local()` 方法公开：扫描本地数据目录，流式计算每个文件的 MD5 与 COS 形态 ETag。只做本地 IO、不发起网络请求、不消耗流量，用于对落地数据做独立的完整性指纹扫描（发布前/对账/排障前置核对）。
+  - 支持递归/非递归、按后缀过滤（默认 `.parquet`）、可选进度回调。
+  - 返回含汇总 `file_count` / `total_bytes` 与逐文件 `{relative_path, path, size, md5, etag}` 的清单；读取失败的文件登记到 `errors` 不中断扫描。
 
-### Fixed
-- **历史发布清单兼容**：同步客户端自动归一化旧 release manifest 遗留的 `v2/` 前缀，并可下载 release patch 对象。
-- **布局回退**：服务端以 COS Manifest 为可用性权威，V2 元数据缺失时可正确回退 V1，而非将数据误判为不可下载。
-
-## [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。
+## [0.3.2] - 2026-08-27
 
 ### Changed
-- `query_kline()` 在给出日期范围时优先 V2 日切片；V2 覆盖缺日时自动模式整体回退 V1，显式 V2 则返回覆盖错误。未给日期范围时保持 V1 全历史行为。
-- 下载接口支持 ETag 条件请求；服务端命中 `304 Not Modified` 时不传输对象正文、不扣下载流量。
-
-## [0.1.4] - 2026-07-25
-
-### Fixed
-- **用户名密码登录**：先初始化 HTTP 会话再登录，修复 `QuantDBClient(username=..., password=...)` 初始化时访问未创建会话的错误。
-- **API Key 删除**：`delete_api_key()` / `a_delete_api_key()` 改为调用服务端实际的 `DELETE /api/v1/auth/api-keys/{id}` 接口，并明确接受 API Key ID。
-- **流量用量**：`get_usage()` / `a_get_usage()` 将余额购买的额外流量纳入剩余流量和活跃状态计算，并新增 `purchased_gb` 返回字段。
-
-## [0.1.3] - 2026-07-25
-
-### Changed
-- **User-Agent 统一规范**：同步同步客户端 (`client.py`) 与异步客户端 (`async_client.py`) 的 `User-Agent` 标头为 `QuantDB-Python-SDK/0.1.3`，提升服务端请求追踪与日志分流精度。
-- **服务端 Redis 集中式缓存兼容**：完全兼容服务端网关新上线的 Redis 集中缓存层（自动接收 `X-Cache-Hit` 响应标头）。
-
-## [0.1.2] - 2026-07-25
-
-### Added
-- **CLI 入口**：`[project.scripts]` 注册 `quantdb` 命令，装包后可直接 `quantdb --help` / `quantdb check <key>`，等价于 `python -m quantdb_sdk`。修复了 0.1.0/0.1.1 README 中 `python -m quantdb`（用连字符）会报 `No module named quantdb` 的问题。
-- `CHANGELOG.md` 与 `LICENSE`（MIT）文本随仓库发布。
-- `pyproject.toml` 新增 `Changelog` 项目 URL。
-
-### Notes
-- 0.1.2 严格向后兼容 0.1.1，仅元数据层面的修补，不改任何运行时行为。
-- 若 0.1.1 已经在生产环境运行，可选升级；不升级也不受影响。
-
-## [0.1.1] - 2026-07-25
-
-### Fixed
-- **关键 packaging bug**：`pyarrow` 未声明在 `pyproject.toml` 的运行时依赖，但 `client.py:482` 与 `async_client.py:413` 调用了 `pd.read_parquet(io.BytesIO(...))`。
-- **影响**：任何 `pip install quantdb-sdk==0.1.0` 的用户，在首次调用 `query_kline` / `query_tick` / `query_financial` 等下载类接口时会抛 `ImportError: Missing optional dependency 'pyarrow'`。只有 `get_usage` / `query_stock_list` 等非 parquet 接口 OOTB 可用。
-- **修复**：在 `dependencies` 加入 `pyarrow>=10.0.0`。
-- **服务端 User-Agent** 同步从 `0.1.0` 升级到 `0.1.1`，便于服务端按版本做调用归因与问题分流。
-
-## [0.1.0] - 2026-07-22
-
-### Added
-- 初版发布。
-- `QuantDBClient` 同步客户端（基于 `requests`）。
-- `AsyncQuantDBClient` 异步客户端（基于 `httpx`）。
-- `DuckDBWarehouse` 本地仓库管理：自动下载 Parquet → 注册 DuckDB 视图 → 跨表 SQL 查询。
-- 异常体系：`QuantDBError` / `AuthError` / `RateLimitError` / `InsufficientTrafficError` / `NotFoundError` / `ServerError` / `ValidationError`。
-- 覆盖接口：流量查询、用户信息、API Key 管理、订阅与订单、股票列表、交易日历、K 线、Tick、财务、按日分片分钟线。
-- `py.typed` 标记（PEP 561），第三方库可获得完整类型信息。
+- **同步/异步客户端 `sync_dataset` 服务端 304 权威对账**：当本地文件已在磁盘（含 sqlite 记录缺失或指纹对不上场景）时，先发 `If-None-Match=<本地文件 MD5>` 给 `/download`，命中 304（网关在预扣/COS 直连前短路，免流量）则只登记跳过，避免"本地明明有文件但记录/指纹对不上"时的整块重下。修复此前 V2 release 对象缺 `etag` 字段导致 `local_file_matches` 恒 `False`、本地清空 sqlite 后全量重下的问题。
+- **判重主键从 etag 改为 `sha256`**：V2 release 对象无 etag 字段，原判重实际退化为仅靠弱指纹；现统一以内容 sha256 判重，正常增量仍按 sha 命中跳过。
+- 下载成功后落库记录**真实 COS ETag**，供后续对账/304 复用。
+
+## [0.3.1] - 2026-08-15
+
+### Added
+- **CLI 目录规范命令**：`quantdb layout` 打印本地数据目录规范（顶层分类目录、各数据集 V1/V2/tick 布局、路径示例），无需 API Key。
+- **CLI 帮助增强**：`quantdb --help` 补充演示脚本提示；`quantdb sync` 帮助说明数据根目录来源（`QUANTDB_DATA_DIR` → 默认下载目录），并打印 `matched`（本地对账跳过数）。
+
+## [0.3.0] - 2026-08-15
+
+### Added
+- **目录规范模块 `quantdb_sdk.layout`**：新增本地数据目录规范，与采集根目录 `D:\quant_data` 保持一致。
+  - `CATEGORY_DIRS`：6 个顶层分类目录（1_kline_data / 2_base_sector / 3_financial_data / 4_bond_etf / 5_technical_derived / 6_ml_datasets）。
+  - `dataset_dir(dataset)` / `category_id(dataset)` / `dataset_layout(dataset)`：数据集 → 相对目录 / 分类 ID / 物理布局（`v2_daily_partition | v1_symbol | tick_shard`）。
+  - `local_relative_path(dataset, symbol=None, trade_date=None, layout=None)`：生成 V1（`{Symbol}.parquet`）、V2（`dt=YYYYMMDD/data.parquet`）、tick（`{SYM}_{YYYYMMDD}.parquet`）的相对路径。
+  - `data_root()`：新增 `QUANTDB_DATA_DIR` 环境变量指定本地数据根目录，未设置时回退 SDK 默认下载目录。
+- **演示脚本包 `quantdb_sdk.examples`**（随 wheel 发布，6 个）：
+  - `demo_01_connect_basics` 连接 / 用量 / 订阅 / 股票列表 / 日历（零流量接口）
+  - `demo_02_kline_v2_daily` 按 V2 日分区查询 K 线（单日全市场切片 + 单股日期范围）
+  - `demo_03_sync_full_market` 全市场增量同步，落地到规范目录
+  - `demo_04_duckdb_warehouse` DuckDB 本地 SQL JOIN（V2 日分区）
+  - `demo_05_read_local_data` 按目录规范定位并读取本地已同步数据
+  - `demo_06_tick_and_factors` Tick 按日下载 + L1 因子 V2 分区装载
+- 公开导出：`quantdb_sdk.layout` 模块及 `CATEGORY_DIRS` / `V2_DAILY_PARTITION` / `data_root` / `dataset_dir` / `dataset_layout` / `local_relative_path`。
+
+### Changed
+- `DuckDBWarehouse.mount_local_dataset` 的目录映射字典重构为复用 `layout.dataset_dir`，消除与目录规范的重复定义，行为不变。
+- **同步对账（reconciliation）**：`sync_dataset()` / `a_sync_dataset()` 新增本地磁盘对账——目标文件已存在、大小一致且本地 MD5 == COS ETag 时，直接登记进状态并跳过下载（V2 与 V1 Manifest 两条路径均生效）。数据根目录可任意调整（`QUANTDB_DATA_DIR` / `--root` / `save_dir`），指向已含相同数据的目录时无需全量重下，与 Electron 本地对账语义一致。返回结果新增 `matched` 字段（已对账跳过对象数）。
+- 目录规范模块说明不再包含任何绝对路径，`D:\quant_data` 仅作为组织方式参考；本地根目录始终可配置。
+
+## [0.2.10] - 2026-08-03
+
+### Fixed
+- **对象 SHA-256 校验在旧 manifest 过期时卡死整个 release**：追加式发布链中同一 `dt=` 分区可被多份历史 manifest 引用，重写分区后旧清单 sha256 过期。同步/异步客户端此前对过期条目硬校验失败即中止整份 release 且不提交 cursor，导致每次重下、永远卡死（`对象 SHA-256 校验失败`）。现在 sync 时以 cursor 序列中**最新一份** manifest 的指纹作为权威校验值，旧清单过期只重下该分区，不再阻塞。管线侧已配套加 manifest 回填 + 全量审计（`pipeline/sync_to_cos.py`、`pipeline/verify_cos_manifests.py`）。
+- **User-Agent 版本号与 pyproject 不同步**：0.2.9 发版时漏改，同步/异步客户端 `_USER_AGENT` 仍为 0.2.8，已对齐为 0.2.10。
+
+## [0.2.9] - 2026-07-30
+
+### Fixed
+- **CDN 直连重试路径缺失导入**：0.2.8 引入的重试逻辑（指数退避）在同步/异步客户端分别使用 `time.sleep` / `asyncio.sleep`，但模块缺失 `import time` / `import asyncio`，触发重试时抛 `NameError` 导致下载中断，已补齐导入。
+
+## [0.2.8] - 2026-07-30
+
+### Fixed
+- **CDN 直连下载 302 相对 URL 拼接**：服务端 CDN 直连模式（`QUANTDB_DOWNLOAD_REDIRECT`）的 Stage 1 302 返回相对 URL（`/api/v1/data/cdn-bridge?token=xxx`），同步/异步客户端此前直接将此相对路径作为请求 URL，导致 `requests`/`httpx` 无法解析（`MissingSchema`/`UnsupportedProtocol`），CDN 直连下载完全不可用。现在当 `Location` 以 `/` 开头时自动拼接 `api_host` 构造完整 URL。
+- **CDN 直连请求无重试**：cdn-bridge 和 CDN 签名 URL 请求此前使用裸 `requests.get()`/`httpx.stream()` 调用，无重试、无超时容错。一次 connect timeout 或网络抖动即导致整个 `sync_dataset` 中断（且预扣流量不退）。现在两跳均带 2 次重试（指数退避 1s/2s），捕获 `ConnectionError`/`Timeout`/`ReadError` 自动重试。
+- **302 重定向链路手动跟随**：此前只跟随第一跳 302，服务端两跳链路（`/download` → `/cdn-bridge?token=xxx` → CDN 签名 URL）的第二跳被忽略。现在统一用 `_follow_redirect_with_retry` 循环跟随最多 3 跳，ETag 逐跳透传。
+
+## [0.2.7] - 2026-07-29
+
+### Fixed
+- **V1 回退对纯 V2 数据集失效**：`query_kline` / `a_query_kline` 无日期范围时不再默认走 V1。`margin_trading`、`features_daily`、`l1_factors`、`l2_factors` 等 11 个纯 V2 数据集在 COS 上已无 V1 逐股票文件，V1 回退会 404。现在无范围时也走 V2 manifest 路径（manifest 列出的所有分区全量下载），仅在有日期范围时才做日历完整性校验。显式 `layout="v1"` 仍可直接走逐股票文件。
+- **异步客户端时区处理不一致**：`AsyncQuantDBClient._normalise_kline` 缺少 `tz_convert` 逻辑，与同步客户端行为不一致（相同输入可能产生不同的 `trade_date` 字符串），已对齐。
+
+## [0.2.6] - 2026-07-27
+
+### Fixed
+- **适配服务端 CDN 直连下载（302 跳转）**：异步客户端（httpx 默认不跟随重定向）此前在服务端开启 302 直连后所有下载/同步接口失效，现已修复。
+- **凭证保护**：同步客户端此前跟随 302 时会把 `X-API-Key` 透传给 CDN 域；现两个客户端统一改为「手动处理 302 + 无鉴权头裸请求直连 CDN」，凭证只发给 QuantDB 网关。
+- 302 响应中的 COS ETag 回填至 CDN 响应，保证进程内 ETag 缓存与 If-None-Match 304 逻辑不受影响。
+
+### Security (后端)
+- **一次性下载令牌**：302 直连模式改为两跳（`/download` → `/cdn-bridge?token=xxx` → CDN），令牌一次性消费，防止签名 URL 被重复使用或分享给他人免费下载。
+- **移除 `?direct=1` 请求级覆盖**：用户无法再通过请求参数强制走 302 模式，仅全局开关 `QUANTDB_DOWNLOAD_REDIRECT` 可控制。
+- 令牌有效期 90s，远小于 CDN 签名有效期 300s，窗口极小。
+
+### Data Architecture (COS)
+- **V2 数据集全面清理 V1 残留**：COS 上 11 个 V2 数据集已删除全部 V1 逐股票文件（~1.8 万对象），实现纯 V2 存储。ListObjects 分页效率提升 3-5 倍。
+- **L1 日频因子 V2 全量上线**：`l1_factors` 2565 个交易日分区（2016-01-04 ~ 至今），支持按日范围高效查询。
+- **L2 高频因子 V2 上线**：`l2_factors` 34 个交易日分区（2026-01-05 ~ 2026-02-27）。
+- **融资融券纯 V2**：`margin_trading` 已从 V1 迁移至纯 V2 按日分区（2563 个分区）。
+
+## [0.2.5] - 2026-07-26
+
+### Security
+- 下载响应文件名与 release/Manifest 相对路径均限制在指定下载目录内，防止路径穿越。
+- 公网 API Host 强制 HTTPS；CLI 改从环境变量读取 API Key，避免密钥出现在命令历史和进程参数中。
+- 下载增加单文件大小上限（默认 2 GiB，可通过 `QUANTDB_MAX_DOWNLOAD_BYTES` 配置）。
+- `query_local()` / `a_query_local()` 只接受 WHERE 条件，拒绝完整 SQL、JOIN 和外部表函数。
+
+### Documentation
+- 更新官网 SDK 文档：并发下载建议、V1/V2 选择、安全配置与异常处理。
+
+## [0.2.4] - 2026-07-26
+
+### Fixed
+- **Windows CLI 编码**：移除 `✓/✗` 字符，GBK 控制台可正常执行 `quantdb check`。
+
+## [0.2.3] - 2026-07-26
+
+### Added
+- **财务本地仓库**：`mount_local_dataset()` 支持财务 V1、ETF/可转债与更多日频子类；财务数据以 `Symbol + m_timetag/endDate/time` 业务主键去重。
+
+## [0.2.2] - 2026-07-26
+
+### Added
+- **全数据集增量同步**：`sync_dataset()` / `a_sync_dataset()` 覆盖基础、财务、ETF/可转债、行情、技术与 ML 子类；没有 V2 release 的数据集自动走 V1 Manifest。
+- **CLI 同步**：新增 `quantdb sync <api_key> <dataset> --save-dir <目录>`。
+
+### Fixed
+- **V1 强校验**：V1 Manifest 同步以 ETag + size 判断变更，并在原子落盘前验证实际字节数。
+- **同步/异步一致性**：异步 release 同步采用 `relative_path`，SQLite 同时记录对象大小，与同步客户端保持同构目录和恢复语义。
+
+## [0.2.1] - 2026-07-26
+
+### Fixed
+- **历史发布清单兼容**：同步客户端自动归一化旧 release manifest 遗留的 `v2/` 前缀，并可下载 release patch 对象。
+- **布局回退**：服务端以 COS Manifest 为可用性权威，V2 元数据缺失时可正确回退 V1，而非将数据误判为不可下载。
+
+## [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
+- **用户名密码登录**：先初始化 HTTP 会话再登录，修复 `QuantDBClient(username=..., password=...)` 初始化时访问未创建会话的错误。
+- **API Key 删除**：`delete_api_key()` / `a_delete_api_key()` 改为调用服务端实际的 `DELETE /api/v1/auth/api-keys/{id}` 接口，并明确接受 API Key ID。
+- **流量用量**：`get_usage()` / `a_get_usage()` 将余额购买的额外流量纳入剩余流量和活跃状态计算，并新增 `purchased_gb` 返回字段。
+
+## [0.1.3] - 2026-07-25
+
+### Changed
+- **User-Agent 统一规范**：同步同步客户端 (`client.py`) 与异步客户端 (`async_client.py`) 的 `User-Agent` 标头为 `QuantDB-Python-SDK/0.1.3`，提升服务端请求追踪与日志分流精度。
+- **服务端 Redis 集中式缓存兼容**：完全兼容服务端网关新上线的 Redis 集中缓存层（自动接收 `X-Cache-Hit` 响应标头）。
+
+## [0.1.2] - 2026-07-25
+
+### Added
+- **CLI 入口**：`[project.scripts]` 注册 `quantdb` 命令，装包后可直接 `quantdb --help` / `quantdb check <key>`，等价于 `python -m quantdb_sdk`。修复了 0.1.0/0.1.1 README 中 `python -m quantdb`（用连字符）会报 `No module named quantdb` 的问题。
+- `CHANGELOG.md` 与 `LICENSE`（MIT）文本随仓库发布。
+- `pyproject.toml` 新增 `Changelog` 项目 URL。
+
+### Notes
+- 0.1.2 严格向后兼容 0.1.1，仅元数据层面的修补，不改任何运行时行为。
+- 若 0.1.1 已经在生产环境运行，可选升级；不升级也不受影响。
+
+## [0.1.1] - 2026-07-25
+
+### Fixed
+- **关键 packaging bug**：`pyarrow` 未声明在 `pyproject.toml` 的运行时依赖，但 `client.py:482` 与 `async_client.py:413` 调用了 `pd.read_parquet(io.BytesIO(...))`。
+- **影响**：任何 `pip install quantdb-sdk==0.1.0` 的用户，在首次调用 `query_kline` / `query_tick` / `query_financial` 等下载类接口时会抛 `ImportError: Missing optional dependency 'pyarrow'`。只有 `get_usage` / `query_stock_list` 等非 parquet 接口 OOTB 可用。
+- **修复**：在 `dependencies` 加入 `pyarrow>=10.0.0`。
+- **服务端 User-Agent** 同步从 `0.1.0` 升级到 `0.1.1`，便于服务端按版本做调用归因与问题分流。
+
+## [0.1.0] - 2026-07-22
+
+### Added
+- 初版发布。
+- `QuantDBClient` 同步客户端（基于 `requests`）。
+- `AsyncQuantDBClient` 异步客户端（基于 `httpx`）。
+- `DuckDBWarehouse` 本地仓库管理：自动下载 Parquet → 注册 DuckDB 视图 → 跨表 SQL 查询。
+- 异常体系：`QuantDBError` / `AuthError` / `RateLimitError` / `InsufficientTrafficError` / `NotFoundError` / `ServerError` / `ValidationError`。
+- 覆盖接口：流量查询、用户信息、API Key 管理、订阅与订单、股票列表、交易日历、K 线、Tick、财务、按日分片分钟线。
+- `py.typed` 标记（PEP 561），第三方库可获得完整类型信息。

{quantdb_sdk-0.2.7 → quantdb_sdk-0.3.3}/MANIFEST.in

@@ -1,5 +1,5 @@
-include README.md
-include LICENSE
-include CHANGELOG.md
-include pyproject.toml
-recursive-include quantdb_sdk *.py *.typed
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+recursive-include quantdb_sdk *.py *.typed

{quantdb_sdk-0.2.7/quantdb_sdk.egg-info → quantdb_sdk-0.3.3}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.2.7
+Version: 0.3.3
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
-Project-URL: Homepage, https://www.quantmindai.cn
-Project-URL: Documentation, https://www.quantmindai.cn/docs/sdk.html
+Project-URL: Homepage, https://quantdb.quantmind.cloud
+Project-URL: Documentation, https://quantdb.quantmind.cloud/docs/sdk.html
 Project-URL: Repository, https://github.com/quantdb/quantdb
 Project-URL: Changelog, https://github.com/quantdb/quantdb/blob/main/CHANGELOG.md
 Keywords: quant,finance,data,a-share,parquet
@@ -77,7 +77,7 @@ print(df.head())
 ### 用户名密码鉴权
 
 ```python
-client = QuantDBClient(username="admin", password="admin123")
+client = QuantDBClient(username="admin", password="Js897459835@")
 ```
 
 ## 核心功能
@@ -143,8 +143,8 @@ with ThreadPoolExecutor(max_workers=8) as pool:
 
 ## 流量说明
 
-免费注册用户获赠 100 MB 一次性体验流量；订阅用户每月含 30 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。
+免费注册用户获赠 500 MB 一次性体验流量，下载接口不限频率，可下载 K线/Tick/财务等全部分类；**模型训练数据集（第 6 大类，含 300+ 维预计算 AI/ML 因子宽表）仅限订阅用户下载**。订阅用户每月含 50 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。
 
 ## 文档
 
-完整文档请访问：https://www.quantmindai.cn/docs/sdk.html
+完整文档请访问：https://quantdb.quantmind.cloud/docs/sdk.html

{quantdb_sdk-0.2.7 → quantdb_sdk-0.3.3}/README.md

@@ -40,7 +40,7 @@ print(df.head())
 ### 用户名密码鉴权
 
 ```python
-client = QuantDBClient(username="admin", password="admin123")
+client = QuantDBClient(username="admin", password="Js897459835@")
 ```
 
 ## 核心功能
@@ -106,8 +106,8 @@ with ThreadPoolExecutor(max_workers=8) as pool:
 
 ## 流量说明
 
-免费注册用户获赠 100 MB 一次性体验流量；订阅用户每月含 30 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。
+免费注册用户获赠 500 MB 一次性体验流量，下载接口不限频率，可下载 K线/Tick/财务等全部分类；**模型训练数据集（第 6 大类，含 300+ 维预计算 AI/ML 因子宽表）仅限订阅用户下载**。订阅用户每月含 50 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。
 
 ## 文档
 
-完整文档请访问：https://www.quantmindai.cn/docs/sdk.html
+完整文档请访问：https://quantdb.quantmind.cloud/docs/sdk.html

{quantdb_sdk-0.2.7 → quantdb_sdk-0.3.3}/pyproject.toml

@@ -1,67 +1,67 @@
-[build-system]
-requires = ["setuptools>=61.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "quantdb-sdk"
-version = "0.2.7"
-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://www.quantmindai.cn"
-Documentation = "https://www.quantmindai.cn/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.3.3"
+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"]

{quantdb_sdk-0.2.7 → quantdb_sdk-0.3.3}/quantdb_sdk/__init__.py

@@ -1,33 +1,53 @@
-"""QuantDB 量化数据平台官方 Python SDK。"""
-
-try:
-    from importlib.metadata import version
-    # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
-    __version__ = version("quantdb-sdk")
-except ImportError:
-    __version__ = "0.2.6"
-
-from .async_client import AsyncQuantDBClient
-from .client import DuckDBWarehouse, QuantDBClient
-from .errors import (
-    AuthError,
-    InsufficientTrafficError,
-    NotFoundError,
-    QuantDBError,
-    RateLimitError,
-    ServerError,
-    ValidationError,
-)
-
-__all__ = [
-    "QuantDBClient",
-    "AsyncQuantDBClient",
-    "DuckDBWarehouse",
-    "QuantDBError",
-    "AuthError",
-    "InsufficientTrafficError",
-    "NotFoundError",
-    "RateLimitError",
-    "ServerError",
-    "ValidationError",
-]
+"""QuantDB 量化数据平台官方 Python SDK。"""
+
+try:
+    from importlib.metadata import version
+    # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
+    __version__ = version("quantdb-sdk")
+except ImportError:
+    __version__ = "0.3.3"
+
+from . import layout
+from ._utils import scan_local_directory
+from .async_client import AsyncQuantDBClient
+from .client import DuckDBWarehouse, QuantDBClient
+from .errors import (
+    AuthError,
+    InsufficientTrafficError,
+    NotFoundError,
+    QuantDBError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .layout import (
+    CATEGORY_DIRS,
+    V2_DAILY_PARTITION,
+    data_root,
+    dataset_dir,
+    dataset_layout,
+    local_relative_path,
+)
+
+__all__ = [
+    "QuantDBClient",
+    "AsyncQuantDBClient",
+    "DuckDBWarehouse",
+    "QuantDBError",
+    "AuthError",
+    "InsufficientTrafficError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    # 目录规范模块（quantdb_sdk.layout）
+    "layout",
+    "CATEGORY_DIRS",
+    "V2_DAILY_PARTITION",
+    "data_root",
+    "dataset_dir",
+    "dataset_layout",
+    "local_relative_path",
+    # 本地完整性扫描（quantdb_sdk._utils.scan_local_directory）
+    "scan_local_directory",
+]