quantdb-sdk 0.1.0__tar.gz

quantdb_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,22 @@
+# 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 *

quantdb_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: quantdb-sdk
+Version: 0.1.0
+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
+Keywords: quant,finance,data,a-share,parquet
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: duckdb>=0.8.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"
+
+# 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/README.md

@@ -0,0 +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_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quantdb-sdk"
+version = "0.1.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",
+]
+
+[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"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["quantdb_sdk*"]

quantdb_sdk-0.1.0/quantdb_sdk/__init__.py

@@ -0,0 +1,33 @@
+"""QuantDB 量化数据平台官方 Python SDK。"""
+
+try:
+    from importlib.metadata import version
+    # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
+    __version__ = version("quantdb-sdk")
+except ImportError:
+    __version__ = "0.1.0"
+
+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_sdk-0.1.0/quantdb_sdk/__main__.py

@@ -0,0 +1,77 @@
+"""QuantDB SDK 命令行入口。
+
+提供快速验证和诊断功能：
+  python -m quantdb --version
+  python -m quantdb --help
+  python -m quantdb check <api_key>  # 验证 API Key 是否有效
+"""
+
+import argparse
+import sys
+
+from . import __version__
+from .client import QuantDBClient
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="quantdb",
+        description="QuantDB 量化数据平台官方 Python SDK",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "--api-host",
+        default="https://quantdb.quantmind.cloud",
+        help="API 服务地址 (默认: https://quantdb.quantmind.cloud)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="可用命令")
+
+    # check 命令：验证 API Key
+    check_parser = subparsers.add_parser("check", help="验证 API Key 是否有效")
+    check_parser.add_argument("api_key", help="要验证的 API Key")
+
+    # usage 命令：查询用量
+    usage_parser = subparsers.add_parser("usage", help="查询账户用量和订阅状态")
+    usage_parser.add_argument("api_key", help="API Key")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    try:
+        client = QuantDBClient(api_host=args.api_host, api_key=args.api_key)
+
+        if args.command == "check":
+            me = client.get_me()
+            print(f"✓ API Key 有效")
+            print(f"  用户: {me.get('username', 'N/A')}")
+            print(f"  ID: {me.get('id', 'N/A')}")
+            return 0
+
+        if args.command == "usage":
+            usage = client.get_usage()
+            print(f"账户用量:")
+            print(f"  已用: {usage['used_gb']:.2f} GB")
+            print(f"  限额: {usage['limit_gb']:.1f} GB")
+            print(f"  剩余: {usage['remaining_gb']:.2f} GB")
+            print(f"  余额: ¥{usage['balance_yuan']:.2f}")
+            sub = usage.get("subscription", {})
+            print(f"  订阅: {sub.get('status', 'none')}")
+            return 0
+
+    except Exception as e:
+        print(f"✗ 错误: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

quantdb_sdk-0.1.0/quantdb_sdk/_utils.py

@@ -0,0 +1,68 @@
+"""QuantDB SDK 内部工具函数。
+
+包含下载目录管理、文件名解析、字节换算等通用工具。
+"""
+
+import os
+import re
+from urllib.parse import unquote
+
+
+def default_download_dir() -> str:
+    """返回默认下载目录。
+
+    优先读取环境变量 ``QUANTDB_DOWNLOAD_DIR``，未设置时按平台回退：
+
+    - Windows: ``D:\\QuantDB\\downloads\\``
+    - Linux/macOS: ``~/QuantDB/downloads/``
+
+    Returns:
+        绝对路径字符串。
+    """
+    env = os.getenv("QUANTDB_DOWNLOAD_DIR")
+    if env:
+        return env.strip()
+    if os.name == "nt":
+        return r"D:\QuantDB\downloads"
+    return os.path.join(os.path.expanduser("~"), "QuantDB", "downloads")
+
+
+def parse_filename_from_content_disposition(value: str, fallback: str) -> str:
+    """从 HTTP Content-Disposition 响应头解析文件名。
+
+    支持 RFC 5987 (filename*=utf-8''name) 和常规 filename="name" 两种格式。
+    解析失败时返回 *fallback*。
+
+    Args:
+        value: Content-Disposition 头的值。
+        fallback: 解析失败时的默认文件名。
+
+    Returns:
+        解析后的文件名或 fallback。
+    """
+    if not value:
+        return fallback
+
+    # RFC 5987 filename*=utf-8''name
+    m = re.search(r"filename\*\s*=\s*(?:[^']*)'" r"(?:[^']*)'([^;]+)", value, re.IGNORECASE)
+    if m:
+        return unquote(m.group(1))
+
+    # filename="name" 或 filename=name
+    m = re.search(r'filename\s*=\s*"?([^";]+)"?', value, re.IGNORECASE)
+    if m:
+        return unquote(m.group(1).strip('"'))
+
+    return fallback
+
+
+def bytes_to_gb(n: int) -> float:
+    """将字节数转换为 GB（1024 进制）。
+
+    Args:
+        n: 字节数。
+
+    Returns:
+        GB 数值（浮点数）。
+    """
+    return n / (1024 ** 3)