py-easy-qunjielong 1.0.0
一个简化群接龙开放平台API使用的Python工具包，提供群接龙相关功能的便捷封装。
Requires Python: >=3.6

# py-easy-qunjielong

一个简化群接龙开放平台API使用的Python工具包，提供群接龙相关功能的便捷封装。

## 功能特性

- **认证管理**：支持获取和缓存认证token
- **订单查询**：支持查询订单列表和单个订单详情
- **商品查询**：支持获取商品ID列表和商品详情
- **同步与异步**：同时支持同步和异步操作
- **响应处理**：统一的响应处理机制，自动验证响应结果
- **缓存管理**：支持diskcache和redis缓存token
- **类型提示**：完整的类型注解，提供良好的IDE支持

## 安装

### 使用pip安装

```bash
pip install py-easy-qunjielong
```

### 从源码安装

```bash
git clone https://gitee.com/guolei19850528/py_easy_qunjielong.git
cd py_easy_qunjielong
pip install -e .
```

## 依赖

- httpx
- jsonschema
- jsonpath-ng

## 快速开始

### 基本使用

```python
from py_easy_qunjielong.open import Open
import diskcache

# 初始化缓存
diskcache_default = diskcache.Cache("./runtime/diskcache/default")

# 初始化Open实例
qunjielong = Open(
    secret="YOUR_SECRET",  # 群接龙开放平台密钥
    cache_config={
        "instance": diskcache_default  # 使用diskcache缓存token
    }
)

# 刷新token并获取商品ID列表
response = qunjielong.refresh().api__goods__ids()
print(f"获取商品ID列表结果: {response.validated}")
if response.validated:
    print(f"商品ID列表: {response.value}")

# 获取商品详情
if response.validated and response.value:
    goods_id = response.value[0]  # 获取第一个商品ID
    goods_detail_response = qunjielong.refresh().api__goods__get_goods_detail(id=goods_id)
    print(f"获取商品详情结果: {goods_detail_response.validated}")
    if goods_detail_response.validated:
        print(f"商品详情: {goods_detail_response.value}")
```

### 异步使用

```python
import asyncio
from py_easy_qunjielong.open import Open
import diskcache

async def main():
    # 初始化缓存
    diskcache_default = diskcache.Cache("./runtime/diskcache/default")
    
    # 初始化Open实例
    qunjielong = Open(
        secret="YOUR_SECRET",
        cache_config={
            "instance": diskcache_default
        }
    )
    
    # 异步刷新token并获取商品ID列表
    response = await qunjielong.refresh().async_api__goods__ids()
    print(f"获取商品ID列表结果: {response.validated}")
    if response.validated:
        print(f"商品ID列表: {response.value}")

asyncio.run(main())
```

### 订单查询

```python
from py_easy_qunjielong.open import Open
import diskcache

# 初始化缓存
diskcache_default = diskcache.Cache("./runtime/diskcache/default")

# 初始化Open实例
qunjielong = Open(
    secret="YOUR_SECRET",
    cache_config={
        "instance": diskcache_default
    }
)

# 查询订单列表
order_list_response = qunjielong.refresh().api__order__all__query_order_list(
    json={
        # 订单查询参数
        "page": 1,
        "pageSize": 10
    }
)
print(f"查询订单列表结果: {order_list_response.validated}")
if order_list_response.validated:
    print(f"订单列表: {order_list_response.value}")
```

## API文档

### Open类

#### 初始化参数
- `base_url`：API基础URL，默认为"https://openapi.qunjielong.com"
- `secret`：群接龙开放平台密钥
- `cache_config`：缓存配置
- `client_kwargs`：传递给httpx.Client的额外参数

#### 方法
- `client(**kwargs)`：创建同步客户端实例
- `async_client(**kwargs)`：创建异步客户端实例
- `request(client=None, **kwargs)`：同步请求方法
- `async_request(client=None, **kwargs)`：异步请求方法
- `refresh(client=None, auth__token_kwargs=None, api__ghome__getGhomeInfo_kwargs=None)`：刷新access_token
- `auth__token(client=None, **kwargs)`：获取认证token
- `api__ghome__getGhomeInfo(client=None, **kwargs)`：获取群接龙信息
- `api__order__all__query_order_list(client=None, **kwargs)`：查询订单列表
- `api__order__single__query_order_info(client=None, **kwargs)`：查询单个订单详情
- `api__goods__page_goods_ids(client=None, **kwargs)`：分页获取商品ID列表
- `api__goods__ids(client=None, **kwargs)`：获取商品ID列表
- `api__goods__get_goods_detail(client=None, id=None, **kwargs)`：获取商品详情
- 以及所有对应的异步方法（以`async_`开头）

### 响应处理

所有API调用都会返回`RequestResponse`对象，包含以下属性：
- `validated`：响应是否有效
- `value`：从响应中提取的值
- `json`：响应的JSON数据
- `response`：原始的httpx.Response对象

## 测试

运行测试用例：

```bash
python -m unittest test_open.py
```

## 项目结构

```
py-easy-qunjielong/
├── py_easy_qunjielong/
│   ├── __init__.py        # 模块初始化和响应处理
│   └── open.py            # 群接龙开放平台API客户端
├── runtime/
│   └── diskcache/         # 缓存目录
├── test_open.py           # 测试文件
├── setup.py               # 安装配置
├── requirements.txt       # 依赖声明
├── LICENSE                # 许可证
└── README.md              # 项目文档
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

- 作者：guolei
- 邮箱：174000902@qq.com
- 项目地址：https://gitee.com/guolei19850528/py_easy_qunjielong