quantdb-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

quantdb_sdk-0.1.2/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+
+## [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.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantDB Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantdb_sdk-0.1.2/MANIFEST.in

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

{quantdb_sdk-0.1.0/quantdb_sdk.egg-info → quantdb_sdk-0.1.2}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.1.0
+Version: 0.1.2
 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: 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
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -21,15 +22,18 @@ 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>=0.8.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
 
 # QuantDB Python SDK
 

{quantdb_sdk-0.1.0 → quantdb_sdk-0.1.2}/README.md

@@ -1,60 +1,60 @@
-# QuantDB Python SDK
-
-QuantDB 量化数据平台官方 Python SDK，提供同步与异步两种客户端，封装了全部 API 端点。
-
-## 安装
-
-```bash
-pip install quantdb-sdk
-```
-
-开发依赖：
-
-```bash
-pip install -e ".[dev]"
-```
-
-## 快速开始
-
-### API Key 鉴权（推荐）
-
-```python
-from quantdb_sdk import QuantDBClient
-
-client = QuantDBClient(api_key="qdb_xxx...")
-
-# 查询用量
-usage = client.get_usage()
-print(f"已用: {usage['used_gb']:.2f} GB, 剩余: {usage['remaining_gb']:.2f} GB")
-
-# K 线查询（免费）
-df = client.query_kline(
-    "600519.SH",
-    adj_type="forward",
-    start_date="2026-01-01",
-    end_date="2026-07-22",
-)
-print(df.head())
-```
-
-### 用户名密码鉴权
-
-```python
-client = QuantDBClient(username="admin", password="admin123")
-```
-
-## 核心功能
-
-- **数据查询**：K 线、Tick 通过下载 Parquet 切片后客户端解析（消耗流量）；股票列表、交易日历、元数据走网关 JSON（不计流量）。
-- **数据下载**：Parquet 文件下载或直读 DataFrame，计入订阅流量。
-- **本地分析**：基于 DuckDB 对本地 Parquet 执行 SQL。
-- **账户管理**：查询用户信息、用量、API Key、订阅与订单。
-- **异步客户端**：基于 httpx，适用于 asyncio 量化框架。
-
-## 流量说明
-
-每月前 30 GB 下载流量免费，超出部分按 ¥1/GB 计费；账户余额不足时，下载会被限流，充值后即可恢复。
-
-## 文档
-
-完整文档请访问：https://www.quantmindai.cn/docs/sdk.html
+# QuantDB Python SDK
+
+QuantDB 量化数据平台官方 Python SDK，提供同步与异步两种客户端，封装了全部 API 端点。
+
+## 安装
+
+```bash
+pip install quantdb-sdk
+```
+
+开发依赖：
+
+```bash
+pip install -e ".[dev]"
+```
+
+## 快速开始
+
+### API Key 鉴权（推荐）
+
+```python
+from quantdb_sdk import QuantDBClient
+
+client = QuantDBClient(api_key="qdb_xxx...")
+
+# 查询用量
+usage = client.get_usage()
+print(f"已用: {usage['used_gb']:.2f} GB, 剩余: {usage['remaining_gb']:.2f} GB")
+
+# K 线查询（免费）
+df = client.query_kline(
+    "600519.SH",
+    adj_type="forward",
+    start_date="2026-01-01",
+    end_date="2026-07-22",
+)
+print(df.head())
+```
+
+### 用户名密码鉴权
+
+```python
+client = QuantDBClient(username="admin", password="admin123")
+```
+
+## 核心功能
+
+- **数据查询**：K 线、Tick 通过下载 Parquet 切片后客户端解析（消耗流量）；股票列表、交易日历、元数据走网关 JSON（不计流量）。
+- **数据下载**：Parquet 文件下载或直读 DataFrame，计入订阅流量。
+- **本地分析**：基于 DuckDB 对本地 Parquet 执行 SQL。
+- **账户管理**：查询用户信息、用量、API Key、订阅与订单。
+- **异步客户端**：基于 httpx，适用于 asyncio 量化框架。
+
+## 流量说明
+
+每月前 30 GB 下载流量免费，超出部分按 ¥1/GB 计费；账户余额不足时，下载会被限流，充值后即可恢复。
+
+## 文档
+
+完整文档请访问：https://www.quantmindai.cn/docs/sdk.html

{quantdb_sdk-0.1.0 → quantdb_sdk-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantdb-sdk"
-version = "0.1.0"
+version = "0.1.2"
 description = "QuantDB 量化数据平台官方 Python SDK"
 readme = "README.md"
 license = {text = "MIT"}
@@ -31,8 +31,19 @@ dependencies = [
     "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",
@@ -45,7 +56,12 @@ dev = [
 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"]

{quantdb_sdk-0.1.0 → quantdb_sdk-0.1.2}/quantdb_sdk/client.py

@@ -51,7 +51,9 @@ class QuantDBClient:
             raise ValueError("必须提供 api_key 或 username+password")
 
         self.session = requests.Session()
-        self.session.headers.update({"User-Agent": "QuantDB-Python-SDK/0.1.0"})
+        # User-Agent 中的版本与 pyproject.toml 同步，用于服务端日志归因
+        # 维护提示：每次版本号变化必须同步改这里（init 里的 __version__ 走 metadata 自动同步）
+        self.session.headers.update({"User-Agent": "QuantDB-Python-SDK/0.1.2"})
         if self.headers:
             self.session.headers.update(self.headers)
 

{quantdb_sdk-0.1.0 → quantdb_sdk-0.1.2/quantdb_sdk.egg-info}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.1.0
+Version: 0.1.2
 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: 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
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -21,15 +22,18 @@ 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>=0.8.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
 
 # QuantDB Python SDK
 

{quantdb_sdk-0.1.0 → quantdb_sdk-0.1.2}/quantdb_sdk.egg-info/SOURCES.txt

@@ -1,3 +1,5 @@
+CHANGELOG.md
+LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
@@ -12,5 +14,9 @@ quantdb_sdk/py.typed
 quantdb_sdk.egg-info/PKG-INFO
 quantdb_sdk.egg-info/SOURCES.txt
 quantdb_sdk.egg-info/dependency_links.txt
+quantdb_sdk.egg-info/entry_points.txt
 quantdb_sdk.egg-info/requires.txt
-quantdb_sdk.egg-info/top_level.txt
+quantdb_sdk.egg-info/top_level.txt
+tests/test_async_client.py
+tests/test_client.py
+tests/test_technical_indicators.py

quantdb_sdk-0.1.2/quantdb_sdk.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quantdb = quantdb_sdk.__main__:main

{quantdb_sdk-0.1.0 → quantdb_sdk-0.1.2}/quantdb_sdk.egg-info/requires.txt

@@ -2,6 +2,7 @@ requests>=2.25.0
 pandas>=1.3.0
 httpx>=0.24.0
 duckdb>=0.8.0
+pyarrow>=10.0.0
 
 [dev]
 pytest>=7.0.0

quantdb_sdk-0.1.2/tests/test_async_client.py

@@ -0,0 +1,134 @@
+"""QuantDB 异步 SDK 单元测试（使用 respx mock HTTP）。"""
+
+import io
+
+import httpx
+import pandas as pd
+import pytest
+import respx
+
+from quantdb_sdk import AsyncQuantDBClient, AuthError, InsufficientTrafficError
+
+
+API_HOST = "http://localhost:5000"
+
+
+def _kline_parquet() -> bytes:
+    buf = io.BytesIO()
+    pd.DataFrame({
+        "trade_date": ["2025-01-02", "2025-01-03"],
+        "open": [100.0, 101.0],
+        "high": [101.5, 102.5],
+        "low": [99.5, 100.5],
+        "close": [101.0, 102.0],
+    }).to_parquet(buf)
+    return buf.getvalue()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_query_kline():
+    route = respx.get(f"{API_HOST}/api/v1/data/download").mock(
+        return_value=httpx.Response(200, content=_kline_parquet())
+    )
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        df = await client.a_query_kline("600519.SH")
+    assert "trade_date" in df.columns
+    assert "open" in df.columns
+    assert "close" in df.columns
+    assert len(df) == 2
+    assert route.called
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_auth_error_raises_auth_error():
+    respx.get(f"{API_HOST}/api/v1/data/download").mock(
+        return_value=httpx.Response(401, json={"detail": "invalid key"})
+    )
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="bad-key") as client:
+        with pytest.raises(AuthError):
+            await client.a_query_kline("600519.SH")
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_insufficient_traffic_error():
+    respx.get(f"{API_HOST}/api/v1/data/download").mock(
+        return_value=httpx.Response(402, json={"detail": "no active subscription"})
+    )
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        with pytest.raises(InsufficientTrafficError):
+            await client.a_load_as_df("1", "daily_forward", symbol="600519.SH")
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_get_usage_with_subscription():
+    respx.get(f"{API_HOST}/api/v1/auth/usage").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "used_traffic": 1073741824,
+                "traffic_limit": 53687091200,
+                "credit_limit": 0,
+                "balance_yuan": 0.0,
+                "subscription": {"plan_id": "pro-annual", "status": "active"},
+            },
+        )
+    )
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        usage = await client.a_get_usage()
+    assert usage["used_gb"] == 1.0
+    assert usage["limit_gb"] == 50.0
+    assert usage["subscription"]["status"] == "active"
+    assert usage["is_active"] is True
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_list_plans():
+    respx.get(f"{API_HOST}/api/v1/subscription/plans").mock(
+        return_value=httpx.Response(
+            200, json={"plans": [{"id": "pro-annual", "amount_yuan": 999}]}
+        )
+    )
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        plans = await client.a_list_plans()
+    assert len(plans) == 1
+    assert plans[0]["id"] == "pro-annual"
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_create_order():
+    respx.post(f"{API_HOST}/api/v1/subscription/orders").mock(
+        return_value=httpx.Response(
+            200, json={"order_id": 2, "pay_url": "https://example.com/pay"}
+        )
+    )
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        order = await client.a_create_order("pro-annual")
+    assert order["order_id"] == 2
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_delete_api_key():
+    respx.post(f"{API_HOST}/api/v1/auth/api-keys/qdb_abc123/delete").mock(
+        return_value=httpx.Response(200, json={"message": "API Key 撤销成功"})
+    )
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        result = await client.a_delete_api_key("qdb_abc123")
+    assert result["message"] == "API Key 撤销成功"
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_get_version():
+    respx.get(f"{API_HOST}/api/v1/version").mock(
+        return_value=httpx.Response(200, json={"latest_version": "1.0.0", "min_required": "1.0.0"})
+    )
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        version = await client.a_get_version()
+    assert version["latest_version"] == "1.0.0"

quantdb_sdk-0.1.2/tests/test_client.py

@@ -0,0 +1,152 @@
+"""QuantDB 同步 SDK 单元测试（使用 responses mock HTTP）。"""
+
+import io
+
+import pandas as pd
+import pytest
+import responses
+
+from quantdb_sdk import AuthError, InsufficientTrafficError, QuantDBClient
+
+
+API_HOST = "http://localhost:5000"
+
+
+def _kline_parquet() -> bytes:
+    """构造一份含 trade_date/open/high/low/close 列的 parquet 字节流。"""
+    buf = io.BytesIO()
+    pd.DataFrame({
+        "trade_date": ["2025-01-02", "2025-01-03"],
+        "open": [100.0, 101.0],
+        "high": [101.5, 102.5],
+        "low": [99.5, 100.5],
+        "close": [101.0, 102.0],
+    }).to_parquet(buf)
+    return buf.getvalue()
+
+
+@responses.activate
+def test_query_kline():
+    # query_kline 走 /data/download 下载 parquet 切片后客户端解析（消耗流量）
+    responses.get(
+        f"{API_HOST}/api/v1/data/download",
+        body=_kline_parquet(),
+        status=200,
+        content_type="application/octet-stream",
+    )
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    df = client.query_kline("600519.SH")
+    assert "trade_date" in df.columns
+    assert "open" in df.columns
+    assert "close" in df.columns
+    assert len(df) == 2
+
+
+@responses.activate
+def test_auth_error_raises_auth_error():
+    responses.get(
+        f"{API_HOST}/api/v1/data/download",
+        json={"detail": "invalid key"},
+        status=401,
+    )
+    client = QuantDBClient(api_host=API_HOST, api_key="bad-key")
+    with pytest.raises(AuthError):
+        client.query_kline("600519.SH")
+
+
+@responses.activate
+def test_insufficient_traffic_error():
+    responses.get(
+        f"{API_HOST}/api/v1/data/download",
+        json={"detail": "no active subscription"},
+        status=402,
+    )
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    with pytest.raises(InsufficientTrafficError):
+        client.load_as_df("1", "daily_forward", symbol="600519.SH")
+
+
+@responses.activate
+def test_get_usage_with_subscription():
+    responses.get(
+        f"{API_HOST}/api/v1/auth/usage",
+        json={
+            "used_traffic": 1073741824,
+            "traffic_limit": 32212254720,
+            "credit_limit": 0,
+            "balance_yuan": 0.0,
+            "subscription": {"plan_id": "pro-monthly", "status": "active"},
+        },
+        status=200,
+    )
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    usage = client.get_usage()
+    assert usage["used_gb"] == 1.0
+    assert usage["limit_gb"] == 30.0
+    assert usage["subscription"]["status"] == "active"
+    assert usage["is_active"] is True
+
+
+@responses.activate
+def test_list_plans():
+    responses.get(
+        f"{API_HOST}/api/v1/subscription/plans",
+        json={"plans": [{"id": "pro-monthly", "amount_yuan": 99}]},
+        status=200,
+    )
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    plans = client.list_plans()
+    assert len(plans) == 1
+    assert plans[0]["id"] == "pro-monthly"
+
+
+@responses.activate
+def test_create_order():
+    responses.post(
+        f"{API_HOST}/api/v1/subscription/orders",
+        json={"order_id": 1, "pay_url": "https://example.com/pay"},
+        status=200,
+    )
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    order = client.create_order("pro-monthly")
+    assert order["order_id"] == 1
+
+
+@responses.activate
+def test_delete_api_key():
+    responses.post(
+        f"{API_HOST}/api/v1/auth/api-keys/qdb_abc123/delete",
+        json={"message": "API Key 撤销成功"},
+        status=200,
+    )
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    result = client.delete_api_key("qdb_abc123")
+    assert result["message"] == "API Key 撤销成功"
+
+
+@responses.activate
+def test_get_version():
+    responses.get(
+        f"{API_HOST}/api/v1/version",
+        json={"latest_version": "1.0.0", "min_required": "1.0.0"},
+        status=200,
+    )
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    version = client.get_version()
+    assert version["latest_version"] == "1.0.0"
+
+
+def test_duckdb_warehouse(tmp_path):
+    pytest.importorskip("duckdb")
+    # 测试 DuckDBWarehouse 注册本地 parquet 文件与 SQL 查询
+    file_path = tmp_path / "test.parquet"
+    pd.DataFrame({"code": ["000001.SZ", "600519.SH"], "val": [10, 20]}).to_parquet(file_path)
+
+    client = QuantDBClient(api_host=API_HOST, api_key="test-key")
+    wh = client.get_local_warehouse(save_dir=str(tmp_path))
+    wh.register_file("stock_val", str(file_path))
+
+    df = wh.query("SELECT * FROM stock_val WHERE val > 15")
+    assert len(df) == 1
+    assert df.iloc[0]["code"] == "600519.SH"
+

quantdb_sdk-0.1.2/tests/test_technical_indicators.py

@@ -0,0 +1,237 @@
+"""
+技术指标计算真值测试。
+
+目的：在改公式前先立基准。对合成 OHLCV 断言 compute_technical_indicators
+符合「通达信口径」规格（见 .claude/plans/technical-indicator-fix-plan.md）。
+
+当前代码（Phase 1 前）应当失败：
+  - macd_hist 缺 ×2（应 = 2*(DIF-DEA)，现为 DIF-DEA）
+  - rsi 首行被强制设为 100（应为 NaN）
+  - rsi 平盘日未设为 50（纯涨=100 已对，但 ag=al=0 时按公式算得 NaN）
+  - 列名为 volume_ratio_5/20（应为 vol_to_ma5/20）
+  - 滚动前未去重
+
+失败即说明测试有效。Phase 1 修复后此测试全绿。
+
+断言策略：
+  - 易手算且口径明确的指标（MA / ma_gap / vol_to_ma / pct_change / return_Nd /
+    macd 三者关系）用精确数值匹配。
+  - 难手算的递归平滑指标（RSI / KDJ / EMA 系列的绝对值）用「边界与单调性」
+    属性断言，避免把 ewm 递归的手算误差写死进测试。
+"""
+import os
+import sys
+
+import numpy as np
+import pandas as pd
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "pipeline", "collectors"))
+
+# 09_technical.py 数字开头文件名无法直接 import，用 importlib 动态加载。
+import importlib.util
+
+
+def _load_technical_module():
+    """动态加载 09_technical.py（数字开头文件名无法直接 import）。"""
+    here = os.path.dirname(os.path.abspath(__file__))
+    # 尝试 09_technical.py 与可能的 technical.py 两种文件名
+    for cand in ("09_technical.py", "technical.py"):
+        path = os.path.join(here, "..", "pipeline", "collectors", cand)
+        if os.path.exists(path):
+            spec = importlib.util.spec_from_file_location("quantdb_technical", path)
+            mod = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mod)
+            return mod
+    raise ImportError("找不到 09_technical.py / technical.py")
+
+
+_technical = _load_technical_module()
+compute_technical_indicators = _technical.compute_technical_indicators
+
+
+def _make_df(closes, highs=None, lows=None, opens=None, volumes=None, amounts=None):
+    """构造单股日线 DataFrame。缺省按 close 推导 high/low/open，volume/amount 给定常量。"""
+    n = len(closes)
+    closes = np.asarray(closes, dtype=float)
+    if highs is None:
+        highs = closes * 1.01
+    if lows is None:
+        lows = closes * 0.99
+    if opens is None:
+        opens = closes
+    if volumes is None:
+        volumes = [10000.0] * n
+    if amounts is None:
+        amounts = [v * c for v, c in zip(volumes, closes)]
+    times = pd.date_range("2024-01-02", periods=n, freq="B")
+    return pd.DataFrame({
+        "time": times,
+        "open": opens,
+        "high": highs,
+        "low": lows,
+        "close": closes,
+        "volume": volumes,
+        "amount": amounts,
+    })
+
+
+# ============ MA / ma_gap（精确） ============
+
+def test_ma5_and_gap_exact():
+    closes = [10, 11, 12, 13, 14, 15]
+    df = _make_df(closes)
+    out = compute_technical_indicators(df)
+    # 第 5 行（idx=4，0-based）首次有 5 日 MA：(10+11+12+13+14)/5 = 12.0
+    assert out.loc[4, "ma5"] == pytest.approx(12.0)
+    # 第 6 行 MA5 = (11+12+13+14+15)/5 = 13.0
+    assert out.loc[5, "ma5"] == pytest.approx(13.0)
+    # 前 4 行 MA5 为 NaN
+    assert out["ma5"].iloc[:4].isna().all()
+    # ma_gap_5 = (close - ma5)/ma5 * 100，idx=4: (14-12)/12*100
+    assert out.loc[4, "ma_gap_5"] == pytest.approx((14 - 12) / 12 * 100)
+
+
+# ============ RSI 边界与属性 ============
+
+def test_rsi_first_row_is_nan():
+    """首行无前收，RSI 应为 NaN（当前代码错误地设为 100）。"""
+    df = _make_df([10, 11, 12, 13, 14, 15, 16])
+    out = compute_technical_indicators(df)
+    assert np.isnan(out.loc[0, "rsi_6"])
+    assert np.isnan(out.loc[0, "rsi_14"])
+
+
+def test_rsi_pure_uptrend_is_100():
+    """连续纯涨（每天上涨、无下跌日）-> RSI = 100。"""
+    df = _make_df([10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20])
+    out = compute_technical_indicators(df)
+    # 从第 2 行起 delta>0、loss=0 -> RSI=100
+    rsi6 = out["rsi_6"].iloc[1:]
+    assert (rsi6 == 100.0).all(), f"纯涨 RSI6 应全为 100，实际: {rsi6.tolist()}"
+
+
+def test_rsi_flat_is_50():
+    """全程平盘（每天与前日相同，无涨无跌）-> RSI = 50（中性）。
+
+    通达信口径：gain=loss=0 始终 -> avg_gain=avg_loss=0 -> RSI=50。
+    （注意：EMA alpha=1/6 衰减缓慢，"上涨后接若干平盘"会让 avg_gain 暂不为 0、
+     avg_loss=0，此时 RSI 仍为 100 而非 50--这不是本测试场景。本测试要求
+     从首日起就全程平盘。）
+    """
+    df = _make_df([10, 10, 10, 10, 10, 10, 10, 10, 10, 10])
+    out = compute_technical_indicators(df)
+    # 行 0 为 NaN；其余全程平盘 -> 50
+    assert np.isnan(out.loc[0, "rsi_6"])
+    rsi6 = out["rsi_6"].iloc[1:]
+    assert (rsi6 == 50.0).all(), f"全程平盘 RSI6 应为 50，实际: {rsi6.tolist()}"
+
+
+def test_rsi_range_and_pure_downtrend_zero():
+    """纯跌 -> RSI 趋近 0；全程 RSI ∈ [0,100] 或 NaN。"""
+    df = _make_df([20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10])
+    out = compute_technical_indicators(df)
+    rsi6 = out["rsi_6"].iloc[1:]
+    # 纯跌 avg_gain=0 -> 公式 RSI = 0（100-100/(1+0)）；但代码未对 avg_gain==0 设 0
+    # 规格：纯跌应得 0。这里仅断言非 NaN 的 RSI 落在 [0,100]
+    finite = rsi6.dropna()
+    if len(finite):
+        assert (finite >= 0).all() and (finite <= 100).all()
+
+
+# ============ KDJ 属性 ============
+
+def test_kdj_warmup_nan_then_finite():
+    """前 8 行 RSV 为 NaN（9 日窗口）-> KDJ 也 NaN；之后有限。"""
+    df = _make_df(list(range(10, 40)))  # 30 根
+    out = compute_technical_indicators(df)
+    assert out["kdj_k"].iloc[:8].isna().all()
+    assert out["kdj_k"].iloc[8:].notna().all()
+
+
+def test_kdj_j_formula():
+    """J = 3K - 2D，逐行成立。"""
+    df = _make_df([10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22])
+    out = compute_technical_indicators(df)
+    k, d, j = out["kdj_k"], out["kdj_d"], out["kdj_j"]
+    mask = k.notna()
+    assert np.allclose(j[mask], 3 * k[mask] - 2 * d[mask])
+
+
+# ============ MACD（关系精确，口径断言） ============
+
+def test_macd_hist_is_twice_diff():
+    """通达信口径：hist = 2*(DIF - DEA)。当前代码缺 ×2 -> 此测试失败。"""
+    df = _make_df([10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+                   21, 22, 23, 24, 25, 26, 27, 28, 29, 30,
+                   29, 28, 27, 26, 25, 24, 23, 22, 21, 20])
+    out = compute_technical_indicators(df)
+    dif, dea, hist = out["macd_dif"], out["macd_dea"], out["macd_hist"]
+    mask = dif.notna() & dea.notna()
+    # 通达信口径：hist = 2*(dif - dea)
+    expected = 2 * (dif[mask] - dea[mask])
+    assert np.allclose(hist[mask], expected, rtol=1e-9), \
+        "macd_hist 应 = 2*(DIF-DEA)（通达信口径）"
+
+
+def test_macd_dif_dea_ema_relationship():
+    """DEA = EMA9(DIF)，与 ewm 关系一致（adjust=False）。"""
+    df = _make_df([10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+                   21, 22, 23, 24, 25, 26, 27, 28, 29, 30])
+    out = compute_technical_indicators(df)
+    dif = out["macd_dif"]
+    expected_dea = dif.ewm(span=9, adjust=False).mean()
+    assert np.allclose(out["macd_dea"], expected_dea, rtol=1e-9)
+
+
+# ============ 成交量比（精确 + 改名） ============
+
+def test_vol_to_ma5_renamed_and_exact():
+    """列名应为 vol_to_ma5（非 volume_ratio_5），且 = volume / 5日均量。"""
+    volumes = [100, 200, 300, 400, 500, 600]
+    df = _make_df([10, 11, 12, 13, 14, 15], volumes=volumes)
+    out = compute_technical_indicators(df)
+    assert "vol_to_ma5" in out.columns, "应重命名为 vol_to_ma5"
+    assert "volume_ratio_5" not in out.columns, "旧名 volume_ratio_5 应已移除"
+    # idx=4: vol=500, ma5=(100+200+300+400+500)/5=300 -> 500/300
+    assert out.loc[4, "vol_to_ma5"] == pytest.approx(500 / 300)
+    # idx=5: vol=600, ma5=(200+300+400+500+600)/5=400 -> 600/400
+    assert out.loc[5, "vol_to_ma5"] == pytest.approx(600 / 400)
+
+
+# ============ 收益率（方向精确：未来 vs 过去） ============
+
+def test_return_1d_is_forward():
+    """return_1d = 未来 1 日收益（shift(-1)），与 pct_change(过去) 方向相反。"""
+    closes = [10, 11, 12, 13, 14]
+    df = _make_df(closes)
+    out = compute_technical_indicators(df)
+    # idx=0: return_1d = (11/10 - 1)*100 = 10
+    assert out.loc[0, "return_1d"] == pytest.approx((11 / 10 - 1) * 100)
+    # pct_change idx=0 = NaN（无前日）
+    assert np.isnan(out.loc[0, "pct_change"])
+    # pct_change idx=1 = (11/10-1)*100
+    assert out.loc[1, "pct_change"] == pytest.approx((11 / 10 - 1) * 100)
+    # 最后一行 return_1d = NaN（无未来）
+    assert np.isnan(out.loc[len(closes) - 1, "return_1d"])
+
+
+# ============ 去重（Phase 1 新增） ============
+
+def test_dedup_before_rolling():
+    """重复 time 行应在滚动前删除，否则 rolling 会重复计数。"""
+    df = _make_df([10, 11, 12, 13, 14])
+    # 复制第 3 行追加
+    dup = pd.concat([df, df.iloc[[2]]], ignore_index=True)
+    out = compute_technical_indicators(dup)
+    # 去重后应只剩 5 行
+    assert len(out) == 5, f"重复 time 行未被去重，行数={len(out)}"
+
+
+# ============ 排序稳定 ============
+
+def test_sort_by_time():
+    df = _make_df([10, 11, 12, 13, 14])
+    shuffled = df.iloc[[3, 1, 4, 0, 2]].reset_index(drop=True)
+    out = compute_technical_indicators(shuffled)
+    assert out["close"].tolist() == [10, 11, 12, 13, 14]

quantdb_sdk-0.1.0/MANIFEST.in

@@ -1,22 +0,0 @@
-# MANIFEST.in - 确保发布到 PyPI 时包含必要的非 Python 文件
-
-# 包含 README 和许可证
-include README.md
-include LICENSE
-
-# 包含依赖文件
-include requirements.txt
-
-# 包含类型标记文件
-include quantdb_sdk/py.typed
-
-# 排除不需要的文件
-exclude .gitignore
-exclude Makefile
-recursive-exclude tests *
-recursive-exclude .github *
-recursive-exclude docs *
-recursive-exclude website *
-recursive-exclude frontend *
-recursive-exclude backend *
-recursive-exclude pipeline *