Metadata-Version: 2.4
Name: ssquantdata
Version: 0.1.1
Summary: Official Python client for SSQuant DataServer
Project-URL: Documentation, https://quant789.com
Author: SSQuant
License: Proprietary
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.9
Requires-Dist: filelock<4,>=3.13
Requires-Dist: httpx<1,>=0.27
Requires-Dist: platformdirs<5,>=4
Requires-Dist: websocket-client<2,>=1.8
Provides-Extra: async
Requires-Dist: websockets<17,>=14; extra == 'async'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling<1.29,>=1.24; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: respx<1,>=0.22; extra == 'dev'
Requires-Dist: twine<7,>=5; extra == 'dev'
Provides-Extra: full
Requires-Dist: pandas>=1.5; extra == 'full'
Requires-Dist: pyarrow>=14; extra == 'full'
Description-Content-Type: text/markdown

# ssquantdata

`ssquantdata` 是 SSQuant DataServer 的官方 Python SDK。它负责俱乐部账号鉴权、期货 raw 数据查询、批量历史任务、实时 WebSocket 和会员持仓查询。

服务端只返回 raw 数据。复权、策略、回测和交易继续由 SSQuant 或调用方负责。

## 0.1.1 能力

- 俱乐部账号登录、Bearer Token 自动刷新和稳定设备标识。
- 期货 symbol list、单数据源历史 K 线和批量历史任务。
- 同步及原生异步 HTTP Client。
- WebSocket 单连接多 channel、自动重连、缺口检测和快照恢复。
- 独立会员持仓数据库查询与安全分页。
- 受控持久缓存、revision 失效、LRU 容量上限和跨进程文件锁。
- 任务 ZIP、manifest、文件大小和 SHA-256 完整性校验。

0.1.1 不提供交易、回测、复权、数据库直连、期权或涨跌停 API，也不导出 `client.options`。

## 安装

要求 Python 3.9 及以上版本，并使用有效的 SSQuant 俱乐部会员账号。

没有账号的新用户请前往 [Quant789 官网](https://quant789.com/) 注册。新账号当前赠送 **20 MB DataServer 体验流量**，体验后可开通 VIP 继续使用。也可在安装 SDK 后查看账号指引：

```bash
ssquantdata account
```

```bash
pip install ssquantdata
```

同步 HTTP、同步 WebSocket、异步 HTTP 和 Parquet 文件下载均包含在基础安装中。异步 WebSocket 需要：

```bash
pip install "ssquantdata[async]"
```

将结果直接物化为 pandas DataFrame 需要：

```bash
pip install "ssquantdata[full]"
```

仅使用 `output="path"` 下载 Parquet 文件不要求本机安装 pandas 或 pyarrow。

## 快速开始

不要把账号密码写入代码仓库。PowerShell：

```powershell
$env:SSQUANTDATA_USERNAME="你的俱乐部手机号或邮箱"
$env:SSQUANTDATA_PASSWORD="你的俱乐部密码"
```

Linux/macOS：

```bash
export SSQUANTDATA_USERNAME="你的俱乐部手机号或邮箱"
export SSQUANTDATA_PASSWORD="你的俱乐部密码"
```

```python
from ssquantdata import SSQuantDataClient

with SSQuantDataClient.from_env() as client:
    print(client.futures.symbols()[:10])
```

SDK 默认只连接 SSQuant 的 HTTPS/WSS 生产服务。账号、密码和 Token 不写入数据缓存。

## 正式公开接口

| 能力 | Python API |
| --- | --- |
| 服务能力与真实限额 | `client.capabilities()` |
| 可用期货代码 | `client.futures.symbols()` |
| 单数据源历史 K 线 | `client.futures.history()` |
| 批量历史 | `client.futures.history_many()` |
| 手动管理历史任务 | `client.futures.create_history_task()` |
| 实时 K 线/Tick 订阅 | `client.realtime()` |
| 会员持仓 | `client.member_positions` |
| 原生异步调用 | `AsyncSSQuantDataClient` |

调用前 SDK 会读取生产 capabilities。服务端限额和协议版本以 capabilities 为准，不应由客户代码长期写死。

## 历史 K 线

```python
from ssquantdata import SSQuantDataClient

with SSQuantDataClient.from_env() as client:
    result = client.futures.history(
        "rb888",
        "1D",
        start_date="2025-01-01",
        end_date="2025-12-31",
    )
    print(result.count, result.cache_status)
    print(result.records[-1])
```

支持周期：`1M/5M/15M/30M/1H/1D`。`60M` 会规范化为 `1H`，`D` 会规范化为 `1D`。

单个 data source 最多 100,000 bars。`adjust_type` 只能为 raw 值 `"0"`；SDK 不在服务端或本地自动改价。

返回的每根 K 线保留服务端 raw 字段，例如：

```text
datetime, symbol, real_symbol
open, high, low, close
volume, amount, openint, cumulative_openint
open_askp, open_bidp, close_askp, close_bidp
订单流分类字段（数据源具备时）
```

## 批量历史任务

```python
from ssquantdata import HistorySource, SSQuantDataClient

sources = [
    HistorySource("rb888", "30M", limit=50_000),
    HistorySource("au888", "30M", limit=50_000),
]

with SSQuantDataClient.from_env() as client:
    result = client.futures.history_many(
        sources,
        mode="auto",
        output="path",
        destination="downloaded_history",
    )
    print(result.transport, result.summary)
    print(result.files)
    result.raise_for_failures()
```

`mode="auto"` 会根据线上真实限额自动选择同步 JSON 或异步任务。大请求由一个服务端任务分块处理，不会让客户端并发发送数百个请求。

`output`：

| 值 | 行为 |
| --- | --- |
| `auto` | 根据请求规模选择合适返回方式 |
| `records` | 将结果物化为 Python records，受本地物化上限保护 |
| `path` | 下载并校验 Parquet/JSON 任务文件，适合大数据量 |
| `dataframe` | 返回 pandas DataFrame，需要 `ssquantdata[full]` |

SDK 会校验任务 manifest、ZIP SHA-256、单文件 SHA-256、文件大小和解压路径。服务端在成功传输后删除临时任务文件。调用方显式传入 `destination` 后，该目录归调用方管理，SDK 不会自动删除。

## 实时数据

```python
from ssquantdata import KlineChannel, SSQuantDataClient
from ssquantdata.models import GapEvent, RecoveryEvent

with SSQuantDataClient.from_env() as client:
    with client.realtime() as stream:
        stream.replace_subscriptions([
            KlineChannel("rb888", "1M", preload=200),
            KlineChannel("au888", "1M", preload=200),
        ])
        for event in stream.events():
            if isinstance(event, GapEvent):
                print("data gap", event)
            elif isinstance(event, RecoveryEvent):
                print("snapshot recovered", event)
            else:
                print(event)
```

一个 Client 使用一条 WebSocket 连接复用多个 channel。`GapEvent` 表示当前 channel 暂时不能确认连续性；收到对应 `RecoveryEvent` 后，才表示 SDK 已通过历史快照重新建立基线。

业务代码不要忽略 `GapEvent`，也不要自行创建数百条 WebSocket 连接。

## 会员持仓

会员持仓使用独立服务和数据库，但与行情接口共用同一个俱乐部 Bearer Token。

```python
from ssquantdata import SSQuantDataClient

with SSQuantDataClient.from_env() as client:
    page = client.member_positions.history(
        start_date="2026-07-01",
        end_date="2026-07-31",
        variety="rb",
        limit=1000,
    )
    print(page.data)
    print(page.next_offset)
```

公开查询方法：

```text
status, varieties, members, rankings, latest, coverage
history, iter_history
member_varieties, member_contracts
```

大范围查询应使用 `iter_history()` 或根据 `next_offset` 分页，不要一次要求物化全部历史记录。

## 异步 Client

```python
import asyncio
from ssquantdata import AsyncSSQuantDataClient


async def main() -> None:
    async with AsyncSSQuantDataClient.from_env() as client:
        result = await client.futures.history("rb888", "1D", limit=100)
        print(result.records)


asyncio.run(main())
```

同步和异步 Client 共用参数模型、响应校验、鉴权规则、错误类型和缓存格式。

## 环境变量

| 环境变量 | 默认值/用途 |
| --- | --- |
| `SSQUANTDATA_USERNAME` | 俱乐部手机号或邮箱 |
| `SSQUANTDATA_PASSWORD` | 俱乐部密码 |
| `SSQUANTDATA_ACCESS_TOKEN` | 可选，由调用方提供的短期 Access Token |
| `SSQUANTDATA_REFRESH_TOKEN` | 可选，与 Access Token 配套 |
| `SSQUANTDATA_DEVICE_ID` | 可选；默认在当前系统用户配置目录生成稳定随机 ID |
| `SSQUANTDATA_CACHE_ENABLED` | 默认 `true` |
| `SSQUANTDATA_CACHE_MAX_BYTES` | 默认 5 GiB |
| `SSQUANTDATA_CACHE_DIR` | 可选缓存目录 |
| `SSQUANTDATA_AUTH_URL` | 默认生产鉴权地址 |
| `SSQUANTDATA_HTTP_BASE_URL` | 默认生产行情 HTTPS 地址 |
| `SSQUANTDATA_WS_URL` | 默认生产 WSS 地址 |
| `SSQUANTDATA_MEMBER_BASE_URL` | 默认生产会员持仓地址 |
| `SSQUANTDATA_VERIFY_TLS` | 默认 `true`，公网环境不得关闭 |

普通客户只需要设置账号和密码。URL 覆盖用于受控测试环境，不应在生产策略里随意修改。

## 缓存管理

默认缓存上限为 5 GiB，达到上限后按 LRU 清理到约 90%。服务端 `historical_revision` 变化后，旧历史缓存自动失效。

```bash
ssquantdata cache info
ssquantdata cache clear --yes
```

- 明确结束于历史交易日的查询使用较长 TTL，并受 revision 控制。
- 当前交易日、未指定结束日期或 revision 降级时使用短 TTL。
- 缓存按账号和服务器隔离，不保存账号、密码、Token 或 Authorization header。
- 缓存可以安全删除并重建，不是业务数据库，也不需要备份。

## 错误处理

所有公开异常都继承自 `SSQuantDataError`：

```python
from ssquantdata import (
    AuthenticationError,
    RateLimitError,
    SSQuantDataClient,
    SSQuantDataError,
)

try:
    with SSQuantDataClient.from_env() as client:
        result = client.futures.history("rb888", "1D", limit=100)
except AuthenticationError as exc:
    print(exc)  # 包含 Quant789 注册和体验流量指引
except RateLimitError as exc:
    print("请求过快，稍后重试", exc.retry_after)
except SSQuantDataError as exc:
    print("DataServer 请求失败", exc)
```

常用异常：

```text
AuthenticationError, EntitlementError
InvalidRequestError, IncompatibleServerError
RateLimitError, ResponseTooLargeError
ServiceUnavailableError
TaskError, TaskLostError, TaskTimeoutError, ArtifactIntegrityError
RealtimeConnectionError, RealtimeGapError
```

SDK 只自动重试适合安全重试的请求。收到 `429` 时应降低调用频率，不要在客户代码中无限立即重试。

## 安全与范围

- 不要把密码、Access Token、Refresh Token 或 Authorization header 写入日志。
- 不要关闭公网 TLS 验证。
- 不要把缓存目录当作可共享的用户数据库。
- 0.1.1 只提供数据访问能力，不包含交易和策略执行。
- 服务端和 SDK 都不会替客户完成复权。

## 示例与版本

完整示例位于 `examples/`：

```text
history.py
history_many.py
realtime.py
async_history.py
member_positions.py
```

版本变化见 `CHANGELOG.md`。

## 许可证

Copyright (c) 2026 SSQuant. All rights reserved.

本软件为专有软件，使用和分发受 SSQuant 俱乐部服务协议及单独书面授权约束。
