# XSDK

Python 通用开发工具包，提供 MySQL、Redis、日志、邮件、HTTP、文件处理、图表生成、腾讯云 COS 等常用功能。

## 安装

```bash
pip install xsdk
```

## 配置文件

使用前需要在项目中创建配置文件（推荐放在 `conf/` 目录下）。

### sys.ini — 系统配置

所有配置统一放在 `sys.ini` 中，通过不同的 section 区分模块：

```ini
[sys_info]
sys_env=DEV                  # 环境标识：DEV / TEST / PROD

[xlog]
log_level=DEBUG              # 全局日志级别（控制台和文件共用）
file_log_flag=Y              # 是否启用文件日志（Y/N）
file_log_path=./             # 日志文件路径
file_log_name=xlog.log       # 日志文件名
console_log_flag=Y           # 是否启用控制台日志（Y/N）

[db_sett]
host=127.0.0.1
port=3306
user=root
password=your_password
timeout=300
```

可配置多个数据库 section：

```ini
[db_business]
host=10.0.0.1
port=3306
user=app_user
password=your_password
timeout=300

[db_analytics]
host=10.0.0.2
port=3306
user=reader
password=your_password
timeout=300
```

## 环境变量

以下功能模块需要设置环境变量：

| 环境变量 | 用途 | 格式 | 示例 |
|---------|------|------|------|
| `MAIL_ACCT` | QQ 邮箱 SMTP 账号 | `邮箱##授权码` 多个用 `^^` 分隔 | `user@qq.com##smtp_password` |
| `REDIS_URL` | Redis 连接地址 | `redis://host:port/db` | `redis://127.0.0.1:6379/0` |
| `XSDK_PROXY` | HTTP 代理地址 | `http://user:pwd@host:port` 多个用 `^^` 分隔 | `http://user:pass@proxy:8080` |

设置方式：

```bash
export REDIS_URL="redis://127.0.0.1:6379/0"
export MAIL_ACCT="your_email@qq.com##your_smtp_password"
export XSDK_PROXY="http://user:pass@proxy_host:port"
```

## 模块说明与使用示例

### 日志 (xlog)

```python
from xsdk.xlog import Xlog

logger = Xlog.get_logger("conf/sys.ini")
logger.info("应用启动")
logger.error("发生错误", exc_info=True)
```

- 支持文件日志 + 控制台日志
- 文件日志按天轮转，保留 45 天

### MySQL (mysql_client)

```python
from xsdk.mysql_client import MySQLClient

db = MySQLClient.get_instance("conf/sys.ini", conf_section="db_sett")

# 查询
result = db.query("SELECT * FROM users WHERE id = %s", params=(1,))

# 分页查询
page_result = db.query_page("SELECT * FROM users", page_number=1, page_size=20)

# 执行 INSERT/UPDATE/DELETE
db.execute("INSERT INTO users (name) VALUES (%s)", params=("test",))

# 批量插入
db.batch_insert(data_list, "db_name", "table_name")
```

- 内置连接池（4~64 连接）
- 线程安全，自动重连

### Redis (redis_client)

```python
from xsdk.redis_client import RedisClient

# 需要先设置环境变量 REDIS_URL
RedisClient.set_value("key", "value", timeout=3600)
value = RedisClient.get_value("key")
```

### 邮件 (mail_client)

```python
from xsdk.mail_client import MailClient, MailContentData

# 需要先设置环境变量 MAIL_ACCT
content = MailContentData("标题", "正文内容")
MailClient.send_mail_v2("邮件主题", "recipient@qq.com", [content])
```

- 支持 QQ 邮箱 SMTP
- 支持 HTML 内容和附件

### HTTP 请求 (http_client)

```python
from xsdk.http_client import HttpClient

response = HttpClient.do_get("https://api.example.com/data")
response = HttpClient.do_post("https://api.example.com/data", body={"key": "value"})
```

### HTTP 代理 (http_proxy)

```python
from xsdk.http_proxy import HttpProxy

# 需要先设置环境变量 XSDK_PROXY
response = HttpProxy.do_get("https://api.example.com/data")
```

### 配置读取 (config_reader)

```python
from xsdk.config_reader import ConfigReader

config = ConfigReader.get_instance("conf/sys.ini")
value = config.get("sys_info", "sys_env")
port = config.get_int("db_sett", "port")

# 环境判断
config.is_dev()   # True if sys_env == DEV
config.is_test()  # True if sys_env == TEST
config.is_prod()  # True if sys_env == PROD
```

### 通用工具 (xutil)

```python
from xsdk import Xutil

Xutil.md5_str("hello")           # MD5 哈希
Xutil.clean_str("  HELLO  ")     # 去空格并转小写
Xutil.contains_chinese("你好")    # 检查是否包含中文
Xutil.get_env_param("ENV_KEY")   # 读取环境变量
```

### 文件工具 (file_util)

```python
from xsdk import FileUtil

FileUtil.read_file("data.txt")
FileUtil.write_file("output.txt", "content")
FileUtil.delete_file("temp.txt")
```

### CSV 解析 (csv_parser)

```python
from xsdk.csv_parser import CsvParser

# 写入 CSV
CsvParser.write_csv("output.csv", header_list, data_list)

# 读取 CSV（迭代器模式）
for row in CsvParser("data.csv"):
    print(row)
```

### Excel 处理 (excel_util)

```python
from xsdk.excel_util import ExcelUtil

data = ExcelUtil.read_excel_xlrd("data.xls")
ExcelUtil.write_excel("output.xlsx", header_list, data_list)
```

### 图表生成 (chart_util)

```python
from xsdk.chart_util import ChartUtil

ChartUtil.gen_bar_chart(x_data, y_data, title="柱状图")
ChartUtil.gen_line_chart(x_data, y_data, title="折线图")
```

### 腾讯云 COS (cos_client)

```python
from xsdk.cos_client import CosClient

client = CosClient.get_client("conf/cos.ini", conf_section="cos")
client.upload_file(bucket, local_path, cos_path)
client.download_file(bucket, cos_path, local_path)
```

### 网页爬虫 (spider_util)

```python
from xsdk.spider_util import SpiderUtil

SpiderUtil.get_tag_html(html, "div", class_name="content")
SpiderUtil.get_text(html)
```

### 对象序列化 (bean_util)

```python
from xsdk.bean_util import BeanUtil, BaseBean

obj = BeanUtil.parse2bean(dict_data, MyBean)
obj_list = BeanUtil.parse2bean_list(dict_list, MyBean)
```

## 依赖说明

| 依赖包 | 用途 |
|-------|------|
| `arrow` | 日期时间处理 |
| `requests` | HTTP 请求 |
| `PyMySQL` / `DBUtils` | MySQL 连接与连接池 |
| `redis` | Redis 客户端 |
| `openpyxl` / `xlrd` / `pandas` | Excel 读写 |
| `matplotlib` | 图表生成 |
| `beautifulsoup4` | HTML 解析 |
| `cos-python-sdk-v5` | 腾讯云 COS |
| `pdfplumber` / `pdfminer` | PDF 解析 |
| `APScheduler` | 定时任务 |

## 构建与发布

```bash
# 安装构建工具
pip install --upgrade build twine

# 构建
python3 -m build

# 发布到 PyPI
./publish_pypi.sh

# 本地安装（开发调试）
pip install dist/xsdk-1.0.1.tar.gz
```
