# ShinnyQuant

<div align="center">

**ShinnyTech EDB数据服务产品 Python SDK**

[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

</div>

## 简介

ShinnyQuant 是由 [ShinnyTech（信易科技）](https://www.shinnytech.com/) 提供的[EDB 数据服务产品](https://edb.shinnytech.com/docs/)  Python 客户端 SDK。

## 功能特性

- 期货合约历史 K 线数据查询（分钟线 + 日线）
- 宏观/经济指标数据查询（EDB 服务）
- 支持免费和专业版访问
- 返回 pandas DataFrame 格式，便于数据分析
- 支持主连合约和指数合约查询
- 完整的类型提示
- 简洁易用的 API

## 安装

```bash
pip install shinny-quant
```

或从源码安装：

```bash
git clone https://github.com/shinnytech/shinny-quant.git
cd shinny-quant
pip install -e .
```

## 快速开始

### 免费访问

免费用户可以获取：
- 最近 1 年的分钟线数据
- 任意历史区间的日线数据

```python
from shinny_quant import ShinnyQuantClient, Period

client = ShinnyQuantClient()

# 获取日线数据
df = client.get_kline(
    symbol="SHFE.rb2501",
    period=Period.DAILY,
    start_time="2023-08-01 09:00:00",
    end_time="2023-08-31 15:00:00",
)

print(df.head())
```

### 专业版访问

专业版用户可以获取全部历史分钟线与日线数据：

```python
from shinny_quant import ShinnyQuantClient, Period

# 方式一：初始化时自动登录（推荐）
client = ShinnyQuantClient(auth=("your_username", "your_password"))

# 方式二：手动登录
# client = ShinnyQuantClient()
# client.login("your_username", "your_password")

# 获取分钟线数据
df = client.get_kline(
    symbol="SHFE.rb2501",
    period=Period.MINUTE,
    start_time="2021-01-01 09:00:00",
    end_time="2023-12-31 15:00:00",
)

print(df.head())
```

## 使用示例

### 指定返回列

```python
# 只返回需要的列
df = client.get_kline(
    symbol="SHFE.rb2501",
    period=Period.MINUTE,
    start_time="2023-08-01 09:00:00",
    end_time="2023-08-01 15:00:00",
    columns=["open", "close", "volume"],
)
```

### 查询主连合约

```python
from shinny_quant.models import make_continuous_symbol, Exchange

# 构造主连合约标识
symbol = make_continuous_symbol(Exchange.CFFEX, "IF")
# 结果: "KQ.m@CFFEX.IF"

df = client.get_kline(
    symbol=symbol,
    period=Period.DAILY,
    start_time="2023-01-01 09:00:00",
    end_time="2023-12-31 15:00:00",
)
```

### 查询指数合约

```python
from shinny_quant.models import make_index_symbol, Exchange

# 构造指数合约标识
symbol = make_index_symbol(Exchange.SHFE, "bu")
# 结果: "KQ.i@SHFE.bu"

df = client.get_kline(
    symbol=symbol,
    period=Period.DAILY,
)
```

### 使用上下文管理器

```python
with ShinnyQuantClient() as client:
    client.login("username", "password")
    df = client.get_kline(
        symbol="SHFE.rb2501",
        period=Period.MINUTE,
    )
    print(df)
```

### 获取原始 CSV 数据

```python
# 返回原始 CSV 字符串
csv_data = client.get_kline_raw(
    symbol="SHFE.rb2501",
    period=Period.DAILY,
)
print(csv_data)
```

## EDB 经济数据服务

ShinnyQuant 支持查询宏观/经济指标数据（需专业版权限）。

### 搜索指标

```python
from shinny_quant import ShinnyQuantClient

# 登录
client = ShinnyQuantClient(auth=("username", "password"))

# 搜索包含"库存"的指标
df = client.search_edb_index("库存")
print(df)
#    id    cn_name     table_name frequency unit start_date    end_date
# 0   1  可用库容量:铜  可用库容量:铜      周    吨  2010-01-01  2026-01-16
# 1   2  可用库容量:白银 可用库容量:白银   周   千克  2012-07-06  2026-01-16
```

### 查询指标数据

```python
# 查询指标数值（指定 ID 和时间范围）
df = client.get_edb_data(
    ids=[1, 2, 3],
    start="2024-01-01",
    end="2024-12-31",
)

print(df)
#                  1     2          3
# 2024-01-05  957664.0  NaN  1007959.0
# 2024-01-12  956037.0  NaN  1008703.0
# 2024-01-19  942861.0  NaN   991716.0
```

### 获取指标目录

```python
# 获取指定 ID 的指标信息
df = client.get_edb_index_table(ids=[1, 2, 3])

# 搜索关键词
df = client.get_edb_index_table(search="库存")

# 获取全部指标目录
df = client.get_edb_index_table()
```

## 合约标识格式

### 普通合约

格式: `交易所.合约代码`

| 交易所 | 代码 | 示例 | 说明 |
|--------|------|------|------|
| 上期所 | SHFE | SHFE.cu1901 | 上期所 cu1901 期货合约 |
| 大商所 | DCE | DCE.m1901 | 大商所 m1901 期货合约 |
| 郑商所 | CZCE | CZCE.SR901 | 郑商所 SR901 期货合约 |
| 中金所 | CFFEX | CFFEX.IF1901 | 中金所 IF1901 期货合约 |
| 上期能源 | INE | INE.sc2109 | 上期能源 sc2109 期货合约 |
| 广期所 | GFEX | GFEX.si2301 | 广期所 si2301 期货合约 |

### 主连合约

格式: `KQ.m@交易所.品种`

示例: `KQ.m@CFFEX.IF` (中金所 IF 品种主连合约)

### 指数合约

格式: `KQ.i@交易所.品种`

示例: `KQ.i@SHFE.bu` (上期所 bu 品种指数)

## API 参考

### ShinnyQuantClient

主客户端类

#### 方法

**K 线数据：**
- `login(username, password)` - 登录获取访问令牌
- `logout()` - 清除当前令牌
- `get_kline(...)` - 获取 K 线数据（返回 DataFrame）
- `get_kline_raw(...)` - 获取原始 CSV 数据（返回字符串）

**EDB 经济数据：**
- `get_edb_index_table(ids, search)` - 查询指标目录
- `get_edb_data(ids, start, end)` - 查询指标数值
- `search_edb_index(keyword)` - 搜索指标（便捷方法）

**其他：**
- `close()` - 关闭客户端连接

#### 属性

- `token` - 当前访问令牌
- `is_authenticated` - 是否已认证

### Period

K 线周期枚举

- `Period.MINUTE` (60) - 1 分钟线
- `Period.DAILY` (86400) - 日线

### 异常

- `ShinnyQuantError` - SDK 基础异常
- `AuthenticationError` - 认证错误
- `ApiError` - API 调用错误

## 开发

安装开发依赖：

```bash
pip install -e ".[dev]"
```

运行测试：

```bash
pytest
```

代码格式化：

```bash
black shinny_quant/
ruff check shinny_quant/
```

类型检查：

```bash
mypy shinny_quant/
```

## 许可证

MIT License

## 关于 ShinnyTech

ShinnyTech（信易科技）专注于为量化交易者提供专业的交易工具和数据服务。

- 官网：[https://www.shinnytech.com/](https://www.shinnytech.com/)
- EDB数据服务产品 [https://edb.shinnytech.com/docs/](https://edb.shinnytech.com/docs/)
- 用户中心：注册账号和购买专业版
- 技术支持：support@shinnytech.com

## 相关产品

- **TqSdk** - 天勤量化交易策略程序开发包
- **ShinnyQuant** - 期货行情历史数据服务 SDK

---

Made with ❤️ by [ShinnyTech](https://www.shinnytech.com/)
