Metadata-Version: 2.1
Name: jyhelper
Version: 26.7.10.1
Summary: 各种实用、常用的小函数、类
Home-page: https://pypi.org/project/jyhelper/
Author: JY
Author-email: your-email@example.com
License: UNKNOWN
Platform: UNKNOWN
Requires-Python: >=3.5
Description-Content-Type: text/markdown
Requires-Dist: pymysql
Requires-Dist: requests
Requires-Dist: sqlparse
Provides-Extra: all
Requires-Dist: fastapi ; extra == 'all'
Requires-Dist: uvicorn ; extra == 'all'
Requires-Dist: pymongo ; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi ; extra == 'api'
Requires-Dist: uvicorn ; extra == 'api'
Provides-Extra: mongo
Requires-Dist: pymongo ; extra == 'mongo'

# jyhelper

一些常用的类、方法，不定时更新。

PyPI: https://pypi.org/project/jyhelper/

---

## 模块说明

| 模块 | 说明 | 额外依赖 |
|------|------|----------|
| `db` / `mysql` | MySQL 数据库操作 | 基础包（pymysql） |
| `mongo` | MongoDB 操作 | `jyhelper[mongo]` |
| `timeHelper` | 时间日期相关 | 无 |
| `file` / `fileHelper` | 文件读写与操作 | 无 |
| `common` | 常用小工具方法 | 无 |
| `feishuRobot` | 飞书机器人发消息 | 无 |
| `sysHelper` | 系统、命令行、并发任务 | 无 |
| `strHelper` | 字符串处理 | 无 |
| `listHelper` | 列表处理 | 无 |
| `dictHelper` | 字典处理 | 无 |
| `docHelper` | 文档相关 | 无 |
| `mailHelper` | 邮件收发 | 无 |
| `apiHelper` | 基于 FastAPI 快速搭建 API | `jyhelper[api]` |

---

## 安装

### 基础安装

默认包含：`pymysql`、`requests`、`sqlparse`

```bash
pip install jyhelper
# 或
python3 -m pip install jyhelper
```

### 按需安装扩展

```bash
# API 服务（fastapi + uvicorn）
pip install jyhelper[api]

# MongoDB
pip install jyhelper[mongo]

# 安装全部扩展
pip install jyhelper[all]

# 组合安装
pip install jyhelper[api,mongo]
```

### 更新

`pip install jyhelper -U` 只升级 **jyhelper 本体** 及**基础依赖**，不会自动更新扩展依赖。
更新时需带上当初安装的 extras：

```bash
# 只装了基础包
pip install jyhelper -U

# 装了 API 扩展，更新时要带上 [api]
pip install jyhelper[api] -U

# 装了多个扩展
pip install jyhelper[api,mongo] -U

# 装了全部扩展
pip install jyhelper[all] -U

# 指定 PyPI 源
pip install jyhelper[api] --upgrade -i https://pypi.org/simple
python3 -m pip install jyhelper[api] --upgrade -i https://pypi.org/simple
```

---

## 使用说明

### 基础工具

```python
from jyhelper import db, timeHelper, common, fileHelper, feishuRobot

dbIns = db(host='', user='root', password='', port=3306, db='')
for row in dbIns.table('table').select():
    print(row)

print(common.explodeList([1, 2, 3], 2))
print(timeHelper.getDate())
fileHelper.read(file_path='')
```

### apiHelper — 快速搭建 API

需先安装：`pip install jyhelper[api]`

启动后访问：

- Swagger 文档：`http://127.0.0.1:8787/docs`
- ReDoc 文档：`http://127.0.0.1:8787/redoc`

#### 方式 1：routes 列表（推荐）

```python
from jyhelper import apiHelper

def hello():
    return apiHelper.success(data={"message": "Hello, World!"})

apiHelper(
    port=8787,
    title="My API",
    routes=[
        {
            "method": "GET",
            "path": "/hello",
            "handler": hello,
            "summary": "Hello 示例",
            "auth": None,
        },
    ],
)
```

运行：

```bash
python adminAPI.py
```

#### 方式 2：装饰器 + 热重载 / 多进程

```python
from jyhelper import apiHelper

helper = apiHelper(port=8787, auto_run=False)
app = helper.app

@helper.route("GET", "/hello", summary="Hello 示例")
def hello():
    return apiHelper.success(data={"message": "Hello, World!"})

@helper.route("POST", "/hello", auth="change-me", summary="Hello POST 示例")
def hello_post():
    return apiHelper.success(data={"message": "Hello, POST!"})

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "adminAPI:app",
        host=helper.host,
        port=helper.port,
        log_config=helper.log_config,
        reload=True,       # 开发热重载
        # workers=4,       # 生产多进程（与 reload 不能同时用）
    )
```

#### 统一响应格式

```python
# 成功
return apiHelper.success(data={"id": 1})
return apiHelper.success(message="操作成功", data={"id": 1})

# 错误（HTTP 仍为 200，错误体现在 body.code）
return apiHelper.error(message="参数错误", code=1001)
```

#### 鉴权

`auth` 为非空字符串时，请求需携带 Header：

```text
Authorization: Bearer <token>
```

```bash
curl http://127.0.0.1:8787/hello
curl -X POST http://127.0.0.1:8787/hello -H "Authorization: Bearer change-me"
```

#### 后台运行（Linux）

```bash
nohup python3 adminAPI.py >> adminAPI.log 2>&1 &
```

---

## 导入方式

所有模块均可从包根导入：

```python
from jyhelper import apiHelper, db, mysql, mongo, timeHelper, common
```

---

## 要求

- Python >= 3.5


