Metadata-Version: 2.4
Name: CHUAuthSDK
Version: 1.0.0
Summary: A Python SDK for CHU Central Authentication Service
Author: Rinn
License-Expression: MIT
Project-URL: Homepage, https://github.com/RinnMoe/CHUAuthSDK
Project-URL: Repository, https://github.com/RinnMoe/CHUAuthSDK
Project-URL: Issues, https://github.com/RinnMoe/CHUAuthSDK/issues
Keywords: cas,auth,chu,login,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: beautifulsoup4>=4.11.0
Requires-Dist: pycryptodome>=3.15.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: ddddocr>=0.8.0; python_version < "3.13"
Dynamic: license-file

# CHUAuthSDK

CHU统一身份认证 Python SDK

## 安装

### 从 PyPI 安装

```bash
pip install CHUAuthSDK
```

默认安装包含验证码图片处理能力（`Pillow`）与 OCR 能力。

但 `ddddocr` 当前仅在 Python 3.12 及以下可用；
在 Python 3.13 环境中会自动跳过 `ddddocr`，图片保存与手动输入验证码流程仍可使用。

### 本地开发安装

```bash
pip install -r requirements.txt
```

## 快速开始

```python
from CHUAuthSDK import CHUAuth, CaptchaRequiredError

# 创建认证客户端
auth = CHUAuth(cookie_dir="cookies")

try:
    # 登录
    session = auth.login("你的学工号", "你的密码")
    
    # 获取用户信息
    user_info = auth.get_user_info()
    print(f"欢迎, {user_info['cn']}!")
    
    # 使用 session 访问需要认证的资源
    resp = session.get("https://course-online.chd.edu.cn/api/radar/rollcalls")
    print(resp.json())
    
except CaptchaRequiredError as e:
    # 需要验证码（如果tkinter可用会自动弹出窗口）
    print("需要验证码")
    if not e.captcha_image:
        # tkinter窗口已显示，用户取消了输入
        print("用户取消了验证码输入")
    else:
        # tkinter不可用，保存图片文件
        with open("captcha.png", "wb") as f:
            f.write(e.captcha_image)
        print("请查看 captcha.png 并输入验证码")
        
        # 获取验证码后重新登录
        captcha_code = input("请输入验证码: ")
        session = auth.login("你的学工号", "你的密码", captcha=captcha_code)
    
except Exception as e:
    print(f"登录失败: {e}")
```

## API 文档

### CHUAuth

#### 初始化参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `cas_url` | `str` | `https://ids.chd.edu.cn` | 统一身份认证服务器地址 |
| `cookie_dir` | `Optional[str]` | `None` | Cookie 存储目录，None 则不持久化。传入目录路径启用持久化，cookie 文件统一存放在该目录下，自动命名为 "cookies_{username}.json"。例如传入 "cookies" 会生成 "cookies/cookies_2021001.json" |

#### 登录方法

SDK 提供三种登录方式

##### 1. `login(username, password, captcha=None, force_relogin=False)`

直接传入账号密码登录。

**参数:**
- `username`: 用户名（学工号/手机号）
- `password`: 密码
- `captcha`: 验证码（可选）
- `force_relogin`: 强制重新登录

**返回:** `requests.Session` - 已认证的会话对象

**示例:**
```python
auth = CHUAuth(cookie_dir="cookies")
session = auth.login("2021001", "password")
```

##### 2. `login_interactive()`

CLI 交互式登录，SDK 自动提示用户输入账号密码。

**返回:** `requests.Session` - 已认证的会话对象

**示例:**
```python
auth = CHUAuth(cookie_dir="cookies")
session = auth.login_interactive()  # 提示输入账号密码
```

##### 3. `login_batch(accounts_json)`

批量登录多个账号。

**参数:**
- `accounts_json`: JSON 字符串或 JSON 文件路径
  ```json
  [
    {"username": "2021001", "password": "password1"},
    {"username": "2021002", "password": "password2"}
  ]
  ```

**返回:** `Dict[str, Any]` - 登录结果字典
```python
{
    "2021001": {"success": True, "session": <Session>, "error": None},
    "2021002": {"success": False, "session": None, "error": "密码错误"}
}
```

**示例:**
```python
auth = CHUAuth(cookie_dir="cookies")

# 传入 JSON 字符串
results = auth.login_batch('[{"username": "2021001", "password": "pwd"}]')

# 或传入 JSON 文件路径
results = auth.login_batch("accounts.json")
```

#### 其他方法

##### `get_user_info()`

获取当前用户信息。

**返回:** `Dict[str, Any]` - 用户信息字典

##### `get_cookies_dict()`

获取 cookies 字典。

**返回:** `Dict[str, str]`

##### `get_session_id()`

获取 session ID。

**返回:** `Optional[str]`

##### `logout()`

登出并清除会话。

### 异常

#### `AuthError`

认证失败异常基类。

#### `CaptchaRequiredError`

需要验证码异常。

**属性:**
- `captcha_image`: `bytes` - 验证码图片数据


## License

MIT
