Metadata-Version: 2.2
Name: litequant
Version: 3.0.2
Summary: LiteQuant Python client SDK
Author: LiteQuant Team
License: MIT
Project-URL: Homepage, https://litequant.pro
Project-URL: Documentation, https://litequant.pro/docs
Project-URL: Issues, https://litequant.pro/support
Keywords: quant,finance,data,parquet,pandas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: redis>=4.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: test
Requires-Dist: pytest<8.4,>=7.0; extra == "test"
Provides-Extra: release
Requires-Dist: build>=1.0; extra == "release"
Requires-Dist: twine>=5.0; extra == "release"
Provides-Extra: dev
Requires-Dist: pytest<8.4,>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# LiteQuant Python SDK

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

支持 Python 3.8 及以上版本。

## Installation

```bash
pip install litequant
```

## Quick Start

```python
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()
```

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

```python
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`。

## Error Handling

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

```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)
```

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

```python
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 数据去重键

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