# GouTool

#### 介绍
🐶 Python 工具类库 - 更加快速开发项目，便捷优雅地使用工具类库

GouTool 是一个功能丰富的 Python 工具类库集合，提供了日常开发中常用的各种实用工具，包括树形结构处理、字符串操作、ID 生成、路径处理、数据库操作、邮件发送等，帮助开发者提高开发效率。

#### 特性

- 🌳 **树形结构处理**：强大的树形数据结构转换和遍历功能
- 🔧 **工具类齐全**：涵盖字符串、日期、文件、路径等常用工具
- 💾 **数据库支持**：提供数据库模板和 SQL 处理工具
- 📧 **邮件发送**：便捷的邮件发送工具
- 🏢 **企业信息处理**：公司信息、地址、手机号等数据处理
- 🎲 **随机数据生成**：ID 生成器、随机数生成等
- 🌐 **WebHook 支持**：WebHook 消息推送工具

#### 安装
bash

# 通过 pip 安装
pip install gou2tool

# 或从源码安装
cd gou2tool
pip install .

#### 快速开始

##### 1. 树形结构处理

```
python
from gou2tool.util import TreeUtil
from gou2tool.core.tree.tree_dict_iterator import TreeDictIterator

# 数组转树结构
data = [
    {"id": 1, "name": "湖北省", "pid": 0},
    {"id": 2, "name": "武汉市", "pid": 1},
    {"id": 3, "name": "襄阳市", "pid": 1},
    {"id": 4, "name": "汉阳区", "pid": 2}
]

tree = TreeUtil.list_to_tree(data, {
    "children": "children",
    "parent_id": "pid"
})

# 遍历树结构（带完整层级信息）
for item in TreeDictIterator(tree):
    print(f"{item['full_name']} - 层级:{item['level']}")
# 输出：
# 湖北省 - 层级:1
# 武汉市 - 层级:2
# 汉阳区 - 层级:3
# 襄阳市 - 层级:2

# 获取最大深度
depth = TreeUtil.get_max_depth(tree)
print(f"最大深度：{depth}")

# 树转数组
flat_list = TreeUtil.tree_to_list(tree)
```
##### 2. ID 生成工具

```
python
from gou2tool.util import IdUtil

# 生成唯一 ID
uid = IdUtil.get_uuid()
print(f"UUID: {uid}")

# 生成时间戳 ID
tid = IdUtil.get_timestamp_id()
print(f"时间戳 ID: {tid}")
```
##### 3. 字符串处理

```
python
from gou2tool.util import StrUtil

# 字符串格式化
result = StrUtil.format("Hello, {}", "World")
print(result)  # Hello, World

# 检查是否为空
is_empty = StrUtil.is_empty("")
print(is_empty)  # True
```
##### 4. 路径处理

```
python
from gou2tool.util import PathUtil

# 获取项目根目录
root = PathUtil.get_root_dir()

# 拼接路径
config_path = PathUtil.join(root, "config", "settings.json")
```
##### 5. 日期时间工具

```
python
from gou2tool.util import DateUtil

# 获取当前时间
now = DateUtil.now()

# 格式化日期
formatted = DateUtil.format(now, "yyyy-MM-dd HH:mm:ss")

# 日期计算
yesterday = DateUtil.add_days(now, -1)
```
##### 6. 数据库工具

```
python
from gou2tool.util import DBTemplateUtil, SQLUtil

# 数据库模板使用
db = DBTemplateUtil.get_connection()

# SQL 处理
sql = SQLUtil.build_query(table="users", conditions={"status": 1})
```
##### 7. 邮件发送

```
python
from gou2tool.util import EmailUtil

# 发送邮件
EmailUtil.send(
    to="user@example.com",
    subject="测试邮件",
    content="这是一封测试邮件"
)
```
##### 8. 手机号和地址处理

```
python
from gou2tool.util import PhoneUtil, AddressUtil

# 手机号验证
is_valid = PhoneUtil.validate("13800138000")

# 地址解析
address_info = AddressUtil.parse("湖北省武汉市汉阳区")
```
#### 核心模块说明

| 模块 | 说明 |
|------|------|
| `TreeUtil` | 树形结构转换、遍历、深度计算 |
| `TreeDictIterator` | 树形字典迭代器（支持父节点、完整路径等信息） |
| `IdUtil` | UUID、时间戳 ID 生成 |
| `StrUtil` | 字符串格式化、校验、转换 |
| `DateUtil` | 日期格式化、计算、解析 |
| `PathUtil` | 路径拼接、文件路径处理 |
| `FileUtil` | 文件读写、目录操作 |
| `SQLUtil` | SQL 语句构建、解析 |
| `DBTemplateUtil` | 数据库连接模板 |
| `EmailUtil` | 邮件发送工具 |
| `PhoneUtil` | 手机号验证、归属地查询 |
| `AddressUtil` | 地址解析、标准化 |
| `CompanyUtil` | 企业信息处理 |
| `EnvUtil` | 环境变量读取配置 |
| `WebHookUtil` | WebHook 消息推送 |

#### 高级用法

##### 树形迭代器的高级特性

```
python
from gou2tool.core.tree.tree_dict_iterator import TreeDictIterator

# 自定义配置的树形遍历
config = {
    "children": "sub_departments",  # 子节点字段
    "id": "dept_id",                 # ID 字段
    "name": "dept_name",             # 名称字段
    "parent_id": "parent_id"         # 父 ID 字段
}

for item in TreeDictIterator(tree, config):
    # 访问所有返回字段
    print(f"节点：{item['node']}")           # 原始节点
    print(f"父节点：{item['parent']}")        # 直接父节点
    print(f"祖先列表：{item['parents']}")     # 所有祖先节点
    print(f"层级：{item['level']}")          # 当前层级
    print(f"完整名称：{item['full_name']}")   # 完整路径名称
    print(f"完整 ID: {item['full_id']}")      # 完整路径 ID
    print(f"名称数组：{item['full_names']}")  # 名称数组
    print(f"ID 数组：{item['full_ids']}")     # ID 数组
    print(f"根 ID: {item['root_id']}")       # 根节点 ID
    print(f"父 ID: {item['parent_id']}")     # 父节点 ID
```
#### 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

#### 开发环境

- Python >= 3.6
- 项目依赖见 `requirements.txt`

#### 运行测试

```
bash
# 运行所有测试
python -m unittest discover tests

# 运行单个测试
python -m unittest tests.tree_util
```
#### 发布

```
bash
# 本地构建
python setup.py sdist bdist_wheel

# 发布到 PyPI
twine upload dist/*
```
#### 许可证

MIT License

#### 联系方式

- Author: wl4837
- Email: wl4837@example.com

---

🎉 希望 GouTool 能让你的开发工作更加高效愉快！
```
