LiteQuant Python SDK

LiteQuant Python SDK 用于在本地下载和读取 LiteQuant 数据。SDK 会自动处理连接、同步、本地 Parquet 缓存和常见错误提示。

支持 Python 3.8 及以上版本。

Installation

pip install litequant

Quick Start

from litequant import LiteQuantClient

client = LiteQuantClient(
    api_token="your_api_token",
    save_path="./litequant_data",
)

client.UpdateAllCategory(update_method="incremental")
df = client.GetCategory("cn_stock_pivot#open")
print(df.tail())

client.close()

推荐使用上下文管理器自动关闭连接：

from litequant import LiteQuantClient

with LiteQuantClient(api_token="your_api_token", save_path="./litequant_data") as client:
    categories = client.ListCategories()
    df = client.GetCategory(categories[0])

默认 API 地址为 https://www.litequant.pro。如需连接测试环境，可以传入 api_url 或设置环境变量 LITEQUANT_API_URL。

Transport Security

• API Token 只会发送到 HTTPS 地址；仅允许 localhost、127.0.0.1 和 ::1 使用 HTTP 本地调试。
• SDK 不跟随 API 重定向，避免临时连接凭证被转发到其他地址。
• 外部 Redis/Tair 连接必须启用 TLS，并校验证书和主机名。
• 远端数据写入本地前必须通过 SHA-256 校验；不完整或异常元数据会被拒绝。
• 数据类别名称会经过严格校验，不能越过 save_path 读写或删除文件。

Error Handling

SDK 默认会在 Python 终端输出功能面错误提示，同时抛出类型化异常。错误信息不会展示后端细节。

from litequant import LiteQuantClient, LiteQuantError

try:
    with LiteQuantClient(api_token="your_api_token", save_path="./litequant_data") as client:
        df = client.GetCategory("cn_stock_pivot#open")
except LiteQuantError as exc:
    print(exc.code)
    print(exc.user_message)
    print(exc.retryable)

如果你希望完全自己处理错误提示，可以关闭终端输出：

client = LiteQuantClient(
    api_token="your_api_token",
    save_path="./litequant_data",
    display_errors=False,
)

常见公开错误码：

• AUTH_INVALID：API 凭证无效或已过期
• ACCOUNT_UNAVAILABLE：账号不可用
• SUBSCRIPTION_UNAVAILABLE：套餐不可用或已过期
• PERMISSION_DENIED：权限不足
• CONNECTION_LIMIT：连接数已达上限
• CONNECTION_INTERRUPTED：连接已中断，请重新连接
• REQUEST_INVALID：请求参数无效
• SERVICE_UNAVAILABLE：服务暂时不可用
• DATA_UNAVAILABLE：数据暂时不可用
• DATA_VERIFY_FAILED：数据校验失败

Data Cache

SDK 会把数据保存为本地 Parquet 缓存。再次读取同一数据类别时，会优先使用本地缓存；如果本地没有该数据类别，SDK 会自动同步。

当前 pivot 数据支持 monthly 和 daily 两种分区模式。后续可以在服务端元信息和客户端缓存层一起扩展更多分区模式。

Metadata Contract

数据服务会提供客户端可识别的类别列表、类别元信息和分区元信息。客户端会自动读取这些元信息并完成数据同步。

公开稳定字段包括：

• partition_mode：pivot 分区模式，目前支持 monthly 和 daily
• partition_keys：数据分区标识列表
• hash：数据校验值
• key_columns / dedupe_keys：unstack 数据去重键

普通用户通常不需要直接使用这些字段。