# jcutils - Python 多功能工具库

一个高效封装的 Python 工具库，集成数据库客户端、云服务 API、消息队列及常用开发工具，助力快速开发与运维自动化。

## 特性

- 🚀 **开箱即用**：统一接口设计，降低学习成本
- 🛡️ **生产级代码**：内置连接池、异常重试、日志记录
- 📦 **模块化设计**：按需引用，无冗余依赖
- 📝 **完整类型注解**：Python 3.8+ 兼容，支持 IDE 智能提示

## 核心模块

### Client（客户端）

#### 数据库客户端
- **关系型数据库**
  - `mysql_client.py` / `mysql_client_async.py`：MySQL 客户端（同步/异步）
  - `postgres_client.py` / `postgres_client_async.py`：PostgreSQL 客户端（同步/异步）
  - `mssql_client.py`：SQL Server 客户端
  - `sqlite3_client.py`：SQLite 客户端
  - `PyodbcClient.py`：通用 ODBC 客户端

- **OLAP/大数据**
  - `clickhouse_client.py`：ClickHouse 客户端
  - `presto_client.py`：Presto/Trino 客户端
  - `hive_client.py`：Hive 客户端

- **NoSQL**
  - `mongo_client.py`：MongoDB 客户端
  - `redis_client.py`：Redis 客户端
  - `elasticsearch_client.py`：Elasticsearch 客户端
  - `hbase_client.py` / `hbase_thrift2_client.py`：HBase 客户端

#### 云服务与存储
- `maxcompute_client.py`：阿里云 MaxCompute（ODPS）
- `dataworks_client.py`：阿里云 DataWorks
- `s3_client.py`：AWS S3 兼容存储
- `qiniu_client.py`：七牛云存储
- `hdfs_client.py`：HDFS 客户端

#### 消息与通信
- `kafka_client.py`：Kafka 客户端
- `work_weixin_bot.py` / `work_weixin_api.py`：企业微信机器人/API
- `work_weixin_send.py`：企业微信消息推送
- `weixin_offiaccount.py`：微信公众号工具

#### 其他
- `ftp_client.py`：FTP 客户端
- `ldap_client.py`：LDAP 客户端
- `imaplib_client.py`：IMAP 邮件客户端

### Utils（工具集）

#### 日期时间
- `datetime_.py`：日期时间操作（转换、计算、范围查询）
- `relative_time.py`：相对时间计算（如"3分钟前"）
- `date_encoder.py`：日期 JSON 序列化

#### 性能监控
- `run_time.py` / `run_func_time.py`：函数执行时间装饰器
- `run_line_time.py`：行级性能分析装饰器
- `run_log_time.py`：带日志的执行时间装饰器
- `Tool.py`：重试装饰器、超时控制等

#### 格式化与处理
- `format_utils.py`：字符串格式化（支持宽字符）
- `tabulate_utils.py`：表格美化输出
- `html.py` / `htmlstrip.py`：HTML 标签去除

#### 开发工具
- `try_except_.py`：异常捕获装饰器
- `logging_.py`：日志配置工具
- `tool_threading.py`：多线程工具
- `lazy_import.py`：懒加载模块导入

#### 系统与网络
- `os_path.py` / `os_platform.py` / `platform_.py`：系统平台检测
- `nginx_log.py`：Nginx 日志分析
- `apscheduler_.py`：Cron 定时任务触发器

#### 地理位置
- `geo.py` / `regeo.py` / `geapi.py`：高德地图地理编码

#### 其他
- `convert.py`：类型转换工具
- `built_in_tools.py`：pickle 序列化工具
- `save_data.py`：CSV 文件保存
- `dingtalkoapi.py`：钉钉 API 客户端

## 安装

```bash
pip install jcutils
```

## 快速开始

### 数据库查询

```python
from jcutils.client.clickhouse_client import ClickHouseClient

client = ClickHouseClient(host="localhost", user="default")
result = client.execute("SELECT * FROM system.tables")
print(result)
```

### 消息推送

```python
from jcutils.client.work_weixin_bot import WeixinBot

bot = WeixinBot(webhook_url="YOUR_WEBHOOK")
bot.send_text("Alert: 服务器CPU负载超过90%")
```

### 性能监控

```python
from jcutils.utils.run_func_time import run_time

@run_time
def slow_function():
    import time
    time.sleep(2)

slow_function()  # 输出执行时间
```

### 日期处理

```python
from jcutils.utils.datetime_ import day_ops, dt2ts, ts2dt

# 当前时间加一天
print(day_ops(days=1))

# 时间戳转换
print(ts2dt(1640995200))
```

## 文档

详细文档请参考：
- [类型注解改进文档](src/jcutils/utils/TYPING_IMPROVEMENTS.md)
- [优化总结文档](src/jcutils/utils/OPTIMIZATION_SUMMARY.md)

## 贡献

欢迎提交 Issue 或 Pull Request！

## License

MIT