Metadata-Version: 2.1
Name: scu-api
Version: 0.0.1a1
Summary: An api provide for Sichuan University
Home-page: https://github.com/hx-w/scu-api
Author: CarOL
Author-email: herixth@gmail.com
License: GNU General Public License v3.0
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: requests (==2.25.1)
Requires-Dist: ujson

# scu-api
提供与四川大学相关的信息接口

## Install

```bash
pip install scu-api
```

国内用户

```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple scu-api
```

## API Format


Api返回类型：`API_Status`
```python
OK = 0
ERROR = 1
WARNING = 2
UNKNOWN = 3
```

通用Api返回类型：`API_ReturnType`
```python
{
    "status": API_Status,
    "result": Any  # API返回的有效内容，如果status不为OK，则返回内容为报错内容
}
```

使用示例：

```python
_ = some_api_method()

_['status']        # 获取状态码(API_Status类型)，同_.status
_['status'].value  # 获取状态码对应的数字(int)，同_.status.value
_['result']        # 获取API返回的有效内容，同_.result

_.is_ok()          # 判断API返回状态是否正确(bool)
```


## Usage

获取本科生用户`U_Student`实例:

```python
import scu_api

my_student = scu_api.get_u_student()
```

`U_Student`内置方法(目前为止)：
```python
@abstractmethod
def set_baseinfo(self, stid: str, passwd: str, hashed: Optional[bool] = False) -> NoReturn:
    '''
    @brief 设置学生的基本信息，用于登陆
    @param[in] stid(str)    学号
    @param[in] passwd(str)  密码
    @param[in] hashed(Optional[bool]) 密码是否已经过md5加密，默认False
    '''

@abstractmethod
def session_valid(self) -> bool:
    '''
    @brief 返回网站会话是否有效，在有效的情况下才可以获取个人信息
            如果session过期，则需要获取验证码重新登陆
    @param[out] valid(bool)  网站会话是否有效
    '''

@abstractmethod
def get_captcha(self, filepath: Optional[str] = None) -> API_ReturnType:
    '''
    @brief 获取验证码
    @param[in]  filepath(str)  [可选的] 存储验证码图像的全路径，使用**.jpg**格式
    @param[out] _(API_ReturnType) 
        {
            'status': API_Status,
            'result': str # 验证码的base64编码字符串
        }
    '''

@abstractmethod
def login(self, catpcha: str, remember_me: Optional[bool] = True) -> API_ReturnType:
    '''
    @brief 模拟登陆
    @param[in] captcha(str) 通过get_captcha获取的验证码识别后的字符串
    @param[in] remember_me(Optional[bool]) [可选的]是否开启两周内快速登录，默认True
    @param[out] _(API_ReturnType) 
        {
            'status': API_Status,
            'result': None
        }
    '''

@session_valid_required
@abstractmethod
def get_student_name(self) -> API_ReturnType:
    '''
    @brief 获取学生姓名
    @param[out] _(API_ReturnType)
        {
            'status': API_Status,
            'result': str # 学生的姓名
        }
    '''

@session_valid_required
@abstractmethod
def get_student_pic(self, filepath: Optional[str] = None) -> API_ReturnType:
    '''
    @brief 获取学生照片
    @param[in]  filepath(Optinal[str]) [可选的]存储图片的全路径，使用**.jpg**格式
    @param[out] _(API_ReturnType)
        {
            'status': API_Status,
            'result': str # 学生照片的base64编码字符串
        }
    '''

@session_valid_required
@abstractmethod
def get_all_term_scores(self, pagesize: Optional[int] = -1) -> API_ReturnType:
    '''
    @brief 获取学生所有学期的成绩
    @param[in]  pagesize(Optional[int]) 最近多少门课的成绩，默认-1为取全部课成绩
    @param[out] _(API_ReturnType)
        {
            'status': API_Status,
            'result': dict # 教务处的学生成绩的原始json数据
        }
    '''
```

## Example

```python
```

