Metadata-Version: 2.4
Name: wei-data-shu
Version: 0.7.0
Summary: wei-data-shu: 面向办公自动化和数据处理的 Python 工具库 | Domain-oriented office automation & data utility toolkit for Python
Author-email: Ethan Wilkins <thisluckyboy@126.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/phoenixlucky/wei-data-shu
Project-URL: Repository, https://github.com/phoenixlucky/wei-data-shu
Project-URL: Issues, https://github.com/phoenixlucky/wei-data-shu/issues
Project-URL: Changelog, https://github.com/phoenixlucky/wei-data-shu/blob/main/CHANGELOG.md
Keywords: office,excel,mysql,email,automation,utilities
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: toml>=0.10
Requires-Dist: requests>=2.31
Provides-Extra: excel
Requires-Dist: pandas>=2.0; extra == "excel"
Requires-Dist: openpyxl>=3.1; extra == "excel"
Provides-Extra: database
Requires-Dist: mysql-connector-python>=8.0; extra == "database"
Provides-Extra: analysis
Requires-Dist: pandas>=2.0; extra == "analysis"
Requires-Dist: numpy; extra == "analysis"
Requires-Dist: matplotlib; extra == "analysis"
Requires-Dist: statsmodels; extra == "analysis"
Requires-Dist: jieba; extra == "analysis"
Requires-Dist: wordcloud; extra == "analysis"
Requires-Dist: openpyxl>=3.1; extra == "analysis"
Provides-Extra: excel-client
Requires-Dist: xlwings; extra == "excel-client"
Dynamic: license-file

<div align="center">

# wei-data-shu 🧩

**面向办公自动化与数据处理的 Python 一站式工具库**
**Domain-Oriented Office Automation & Data Utility Toolkit for Python**

[![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python&logoColor=white)](https://www.python.org/)
[![PyPI version](https://img.shields.io/pypi/v/wei-data-shu?color=blue)](https://pypi.org/project/wei-data-shu/)
[![License](https://img.shields.io/badge/License-GPLv3-blue.svg)](./LICENSE)
[![Development Status](https://img.shields.io/badge/status-beta-yellow)](https://pypi.org/project/wei-data-shu/)
[![GitHub stars](https://img.shields.io/github/stars/phoenixlucky/wei-data-shu?logo=github)](https://github.com/phoenixlucky/wei-data-shu)

---

覆盖 **数据库 · Excel · 文件 · 文本分析 · 数据分析 · 邮件 · AI 对话 · 通用工具** 八大领域，
领域化分包设计，惰性导入零开销，开箱即用。

</div>

---

## ✨ 特性

- **八大领域一站覆盖** — MySQL 数据库、Excel 电子表格、文件管理、文本分析（词频/词云/趋势预测）、数据分析（通用读取/清洗/可视化）、邮件发送、Ollama AI 对话、通用工具
- **领域化分包设计** — 每个领域一个包，根包仅暴露入口，结构清晰、职责单一
- **惰性导入零开销** — 各领域包按需懒加载，`import wei_data_shu` 不拖慢启动
- **开箱即用** — 统一 `wei_data_shu.<domain>` 导入约定，配合完整示例，5 分钟上手
- **可选依赖按需安装** — 文本分析、Excel App 等重量能力通过 `extras` 安装，核心包轻量

## 📖 目录

- [快速开始](#快速开始)
  - [安装](#安装)
  - [导入方式](#导入方式)
  - [命令行工具](#命令行工具)
  - [5 分钟上手](#5-分钟上手)
- [功能概览](#功能概览)
- [项目结构](#项目结构)
- [用法示例](#用法示例)
  - [1. MySQLDatabase（数据库）](#1-mysqldatabase数据库)
  - [2. Excel（电子表格）](#2-excel电子表格)
  - [3. DailyEmailReport（邮件）](#3-dailyemailreport邮件)
  - [4. DateFormat（日期处理）](#4-dateformat日期处理)
  - [5. StringBaba（字符串处理）](#5-stringbaba字符串处理)
  - [6. TextAnalysis（文本分析）](#6-textanalysis文本分析)
  - [7. TrendPredictor（趋势预测）](#7-trendpredictor趋势预测)
  - [8. FileManagement（文件管理）](#8-filemanagement文件管理)
  - [9. ChatBot（AI 对话）](#9-chatbotai-对话)
  - [10. Utils（通用工具）](#10-utils通用工具)
- [参与贡献](#参与贡献)
- [许可证](#许可证)

---

## 🚀 快速开始

### 安装

```bash
pip install wei-data-shu
```

> 核心包仅依赖 `toml` 与 `requests`，开箱即用；重量能力按需安装：

```bash
# Excel 读写 / 拆分合并（依赖: pandas, openpyxl）
pip install "wei-data-shu[excel]"

# MySQL 数据库（依赖: mysql-connector-python）
pip install "wei-data-shu[database]"

# 文本分析 / 词云 / 趋势预测 / 数据分析（依赖: jieba, numpy, matplotlib, statsmodels, wordcloud, pandas, openpyxl）
pip install "wei-data-shu[analysis]"

# 需要通过本机 Excel 应用操作工作簿（依赖: xlwings + Microsoft Excel）
pip install "wei-data-shu[excel-client]"
```

升级到最新版本：

```bash
pip install --upgrade wei-data-shu
```

### 导入方式

所有公开 API 统一从 `wei_data_shu.<domain>` 导入，根包 `wei_data_shu` 只暴露领域包入口：

```python
from wei_data_shu.database import MySQLDatabase, MySQLDatabaseError
from wei_data_shu.excel import ExcelManager, OpenExcel, ExcelOperation, quick_excel
from wei_data_shu.files import FileManagement
from wei_data_shu.mail import DailyEmailReport
from wei_data_shu.text import DateFormat, StringBaba, TextAnalysis, TrendPredictor
from wei_data_shu.analysis import DataCleaner, read_csv, plot_line, plot_corr_heatmap
from wei_data_shu.ai import ChatBot
from wei_data_shu.utils import fn_timer, generate_password, search_colors
```

### 命令行工具

安装后可直接在终端使用：

```bash
# 查看帮助
wei-data-shu --help
# 或
python -m wei_data_shu --help
```

```bash
# 颜色检索
wei-data-shu colors                # 列出所有颜色
wei-data-shu colors mint           # 按英文名搜索
wei-data-shu colors 薄荷           # 按中文名搜索
wei-data-shu colors "#5BC49F"      # 按 HEX 搜索

# 密码生成
wei-data-shu password --count 10 --length 13

# 日期计算（默认今天，可回退 N 天）
wei-data-shu date                    # 2026-08-13
wei-data-shu date --days 1 --format "%Y%m%d"

# Excel 工作簿信息（需要 excel extras）
wei-data-shu excel info report.xlsx  # 列出各工作表行数
```

### 5 分钟上手

以下示例**不依赖**数据库、邮件服务或本机 Excel，安装后即可运行。它会完成 4 件事：

- 生成当天报表文件名
- 创建一个 Excel 文件并写入示例数据
- 检索颜色表中的中文颜色信息
- 生成一个不含易混淆字符的安全密码

```python
from pathlib import Path

from wei_data_shu.excel import ExcelManager
from wei_data_shu.text import DateFormat
from wei_data_shu.utils import generate_password, search_colors

# 1. 生成日期字符串
today = DateFormat(interval_day=0, timeclass="date").get_timeparameter(Format="%Y-%m-%d")
report_path = Path(f"demo-report-{today}.xlsx")

# 2. 写入 Excel 报表
rows = [
    ["日期", "渠道", "销售额"],
    [today, "电商", 12580],
    [today, "门店", 9680],
    [today, "分销", 7320],
]

with ExcelManager(str(report_path)) as wb:
    wb.write_sheet("日报", rows, start_row=1, start_col=1)
    summary = wb.read_sheet("日报", 1, 1)

# 3. 颜色检索
mint_colors = search_colors("薄荷")

# 4. 密码生成
temp_password = generate_password(13)

# 输出结果
print("报表文件：", report_path.resolve())
print("首行数据：", summary[0])
print("颜色搜索：", mint_colors[0]["hex"], mint_colors[0]["name"], mint_colors[0]["name_zh"])
print("临时密码：", temp_password)
```

运行后你会得到一个 `demo-report-YYYY-MM-DD.xlsx` 文件，并在终端看到类似输出：

```text
报表文件： D:\path\to\demo-report-2026-03-17.xlsx
首行数据： ['日期', '渠道', '销售额']
颜色搜索： #5BC49F mint green 薄荷绿
临时密码： 8rY#FvQ7mK2$T
```

---

## 🧭 功能概览

| 领域 | 导入路径 | 主要 API | 功能 |
| --- | --- | --- | --- |
| 数据库 | `wei_data_shu.database` | `MySQLDatabase`, `MySQLDatabaseError` | MySQL 连接、查询、插入、更新、删除、存储过程 |
| Excel | `wei_data_shu.excel` | `ExcelManager`, `OpenExcel`, `ExcelOperation`, `quick_excel`, `ExcelHandler` | 读写工作簿、样式、DataFrame、工作表管理、拆分合并、Excel App 操作 |
| 文件 | `wei_data_shu.files` | `FileManagement` | 查找最新文件夹、复制文件、批量重命名、删除 |
| 邮件 | `wei_data_shu.mail` | `DailyEmailReport` | SMTP/SSL 发送纯文本/HTML 邮件、附件 |
| 文本 | `wei_data_shu.text` | `DateFormat`, `StringBaba`, `TextAnalysis`, `TrendPredictor`, `MultipleTrendPredictor`, `textCombing` | 日期格式化、字符串清洗、词频分析、词云、ARIMA 趋势预测、段落重组 |
| 数据分析 | `wei_data_shu.analysis` | `read_csv`, `read_json`, `read_excel`, `read_any`, `DataCleaner`, `plot_line`, `plot_bar`, `plot_hist`, `plot_box`, `plot_scatter`, `plot_pie`, `plot_corr_heatmap` | 通用数据读取、缺失值/重复值/异常值处理、归一化、类别编码、常用图表绘制、相关热力图 |
| AI | `wei_data_shu.ai` | `ChatBot` | 对接 Ollama API，支持流式/非流式对话、聊天记录持久化 |
| 工具 | `wei_data_shu.utils` | `fn_timer`, `generate_password`, `search_colors`, `mav_colors` | 函数计时器、安全密码生成、颜色检索 |
| 文档 | `wei_data_shu.docs` | `FileManagement`, `ExcelHandler`, `OpenExcel`, `ExcelOperation` | 文档工作流（Excel + 文件操作的组合编排） |

---

## 🗂 项目结构

```text
wei_data_shu/
├─ wei_data_shu/            # 核心包
│  ├─ __init__.py           # 根包入口，按需惰性加载各个领域包
│  ├─ __main__.py           # python -m 入口
│  ├─ _api.py               # 统一公开 API 注册表
│  ├─ cli.py                # 命令行接口（colors / password / date / excel）
│  ├─ py.typed              # PEP 561 类型标记（IDE 补全）
│  ├─ ai/                   # AI 能力（ChatBot, Ollama）
│  ├─ analysis/             # 数据分析
│  │  ├─ io.py              #   通用数据读取（CSV/JSON/Excel, read_any）
│  │  ├─ cleaning.py        #   DataCleaner（缺失/重复/异常值, 归一化, 编码）
│  │  ├─ charts.py          #   可视化（折线/柱状/直方/箱线/散点/饼图/热力图）
│  │  └─ _deps.py           #   可选依赖守卫
│  ├─ database/             # 数据库能力（MySQL）
│  ├─ docs/                 # 文档工作流（Excel + 文件处理的组合）
│  ├─ excel/                # Excel 能力
│  │  ├─ manager.py         #   核心: ExcelManager
│  │  ├─ handler.py         #   兼容: ExcelHandler
│  │  ├─ client.py          #   桌面: OpenExcel (xlwings)
│  │  ├─ operations.py      #   高级: ExcelOperation (拆分/合并/CSV)
│  │  ├─ quick.py           #   快捷: quick_excel / read_excel_quick
│  │  └─ _helpers.py        #   内部: 样式/创建/自动范围
│  ├─ files/                # 文件处理（FileManagement）
│  ├─ mail/                 # 邮件发送（DailyEmailReport）
│  ├─ text/                 # 文本处理
│  │  ├─ core.py            #   DateFormat, StringBaba, decrypt
│  │  ├─ analysis.py        #   TextAnalysis (jieba 分词, 词云)
│  │  ├─ forecast.py        #   TrendPredictor, MultipleTrendPredictor
│  │  ├─ combiner.py        #   textCombing (段落重组)
│  │  └─ _deps.py           #   可选依赖守卫
│  └─ utils/                # 通用工具
│     ├─ timing.py          #   fn_timer
│     ├─ passwords.py       #   generate_password
│     └─ colors.py          #   mav_colors, search_colors
├─ tests/                   # 单元测试
├─ examples/                # 可运行示例（quickstart / excel / chatbot）
├─ docs/plans/              # 架构设计文档
├─ pyproject.toml           # 包配置 & 依赖
├─ LICENSE                  # GPL-3.0 许可证
└─ README.md                # 本文件
```

### 设计原则

| 原则 | 说明 |
| --- | --- |
| **惰性导入** | 每个领域包使用 `__getattr__` 按需加载，避免启动时全量导入 |
| **统一入口** | 根包只暴露领域包名称，所有公开 API 通过 `wei_data_shu.<domain>.ClassName` 访问 |
| **结构清晰** | 按领域分包，职责明确；`docs` 包编排跨领域的复合工作流 |
| **可选依赖** | Excel / 数据库 / 文本分析 / Excel App 通过 `[excel]` `[database]` `[analysis]` `[excel-client]` extras 按需安装，核心包仅依赖 `toml`/`requests` |

---

## 💻 用法示例

### 1. MySQLDatabase（数据库）

#### 基本 CRUD

```python
from wei_data_shu.database import MySQLDatabase, MySQLDatabaseError

# 数据库配置
config = {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "root",
    "password": "your_password",
    "database": "your_database",
}

db = MySQLDatabase(config)

# 插入
db.execute_query(
    "INSERT INTO users (name, age) VALUES (%s, %s)",
    ("Alice", 25),
)

# 查询
results = db.fetch_query("SELECT * FROM users WHERE age > %s", (20,))
for row in results:
    print(row)

# 更新
db.execute_query(
    "UPDATE users SET age = %s WHERE name = %s",
    (26, "Alice"),
)

# 删除
db.execute_query("DELETE FROM users WHERE name = %s", ("Bob",))

db.close()
```

#### 错误处理与上下文管理器

所有数据库操作失败都会抛出 `MySQLDatabaseError`（而不是静默打印），请在业务层捕获处理；推荐用 `with` 语句自动关闭连接：

```python
from wei_data_shu.database import MySQLDatabase, MySQLDatabaseError, MySQLDatabaseError

config = {
    "user": "root",
    "password": "your_password",
    "host": "127.0.0.1",
    "port": 3306,
    "database": "your_database",
}

try:
    with MySQLDatabase(config) as db:
        results = db.fetch_query("SELECT * FROM users WHERE age > %s", (20,))
except MySQLDatabaseError as exc:
    print("数据库操作失败:", exc)
```

> 说明：查询失败会抛异常；查询成功但结果为空时返回 `[]`，可放心区分"无数据"与"出错了"。

---

### 2. Excel（电子表格）

Excel 模块提供 4 个层次的能力：

| 类 | 依赖 | 适用场景 |
| --- | --- | --- |
| `ExcelManager` | 无（openpyxl） | 日常读写、样式、DataFrame、工作表管理 |
| `quick_excel` / `read_excel_quick` | 无（openpyxl） | 极简单次写入 / 读取 |
| `ExcelHandler` | 无（openpyxl） | 旧版兼容接口 |
| `ExcelOperation` | 无（openpyxl + pandas） | 拆分多工作表、合并多个文件、转 CSV |
| `OpenExcel` | xlwings + Microsoft Excel | 调用本机 Excel 应用（刷新公式、宏等） |

推荐优先使用 **`ExcelManager`**。

#### 2.1 ExcelManager — 基本读写

```python
from wei_data_shu.excel import ExcelManager

# 方式一：with 语句（自动保存、关闭）
with ExcelManager("data.xlsx") as wb:
    wb.write_sheet("Sheet1", [["Name", "Age"], ["Alice", 25]], start_row=1, start_col=1)
    wb.fast_write("Sheet1", [["Bob", 30]], start_row=3, start_col=1)
    data = wb.read_sheet("Sheet1", 1, 1)
    print(data)   # [['Name', 'Age'], ['Alice', 25], ['Bob', 30]]

# 方式二：手动管理
wb = ExcelManager("data.xlsx")
wb.fast_write("Sheet1", [[1, 2], [3, 4]], 1, 1)
wb.save()
wb.close()
```

#### 2.2 ExcelManager — DataFrame 读写

```python
import pandas as pd
from wei_data_shu.excel import ExcelManager

df = pd.DataFrame({"Name": ["Alice", "Bob", "Charlie"], "Age": [25, 30, 28]})

with ExcelManager("team.xlsx") as wb:
    wb.write_dataframe("Sheet1", df)

with ExcelManager("team.xlsx") as wb:
    df_read = wb.read_dataframe("Sheet1")
    print(df_read)
```

#### 2.3 ExcelManager — 工作表管理

```python
from wei_data_shu.excel import ExcelManager

wb = ExcelManager("workbook.xlsx")

# 创建新工作表
wb.create_sheet("销售数据")

# 获取工作表信息
info = wb.get_sheet_info("Sheet1")
print(f"行数: {info['max_row']}, 列数: {info['max_column']}")

# 复制工作表
wb.copy_sheet("Sheet1", "Sheet1_备份")

# 删除工作表
wb.delete_sheet("旧数据")

# 列出所有工作表
print(wb.sheet_names)

wb.save()
wb.close()
```

#### 2.4 quick_excel / read_excel_quick（极简模式）

```python
from wei_data_shu.excel import quick_excel, read_excel_quick

# 一行写入
wb = quick_excel("quick.xlsx", [["Name", "Age"], ["Alice", 25], ["Bob", 30]])

# 一行读取（返回列表）
data = read_excel_quick("quick.xlsx")
print(data)

# 读取为 DataFrame
df = read_excel_quick("quick.xlsx", as_dataframe=True)
print(df)
```

#### 2.5 ExcelOperation — 拆分、合并、转 CSV

```python
from wei_data_shu.excel import ExcelOperation

op = ExcelOperation("input.xlsx", "./output")

# 将多工作表的工作簿拆分为单个文件（每个工作表一个 .xlsx）
files = op.split_table()
print("拆分文件:", files)

# 合并多个文件为一个工作簿
op.merge_tables(["sales_q1.xlsx", "sales_q2.xlsx"], "sales_上半年.xlsx")

# 转换为 CSV
csv_path = op.convert_to_csv()
print("CSV 文件:", csv_path)
```

#### 2.6 OpenExcel — 本机 Excel 应用操作

需要安装 Microsoft Excel 和 `xlwings`：`pip install wei-data-shu[excel-client]`

```python
from wei_data_shu.excel import OpenExcel

# 方式一：读写后自动保存
with OpenExcel("data.xlsx").my_open() as wb:
    wb.fast_write("Sheet1", [["Name", "Age"], ["Alice", 25]], 1, 1)

# 方式二：刷新公式（如数据透视表）
with OpenExcel("report.xlsx").open_save_Excel() as appwb:
    appwb.api.RefreshAll()

# 方式三：列出工作簿中的工作表
sheets = OpenExcel("data.xlsx").file_show(filter=["sheet", "报表"])
print(sheets)
```

#### 2.7 完整流水线示例

```python
from pathlib import Path
from wei_data_shu.excel import ExcelManager, OpenExcel, ExcelOperation

base = Path.cwd()
filepath = str(base / "pipeline.xlsx")

# 1. 写入数据
with ExcelManager(filepath) as wb:
    wb.fast_write("Sheet1", [["Name", "Age"], ["Alice", 25], ["Bob", 30]], 1, 1)

# 2. 通过 Excel 应用刷新公式
with OpenExcel(filepath).open_save_Excel() as appwb:
    appwb.api.RefreshAll()

# 3. 拆分工作表
op = ExcelOperation(filepath, str(base / "output"))
op.split_table()

# 4. 转 CSV
csv_file = op.convert_to_csv()
```

---

### 3. DailyEmailReport（邮件）

#### 发送纯文本邮件

```python
from wei_data_shu.mail import DailyEmailReport

email_reporter = DailyEmailReport(
    email_host="smtp.example.com",
    email_port=465,
    email_username="your_email@example.com",
    email_password="your_password",
)

email_reporter.add_receiver("recipient@example.com")

email_reporter.send_daily_report(
    "日报",
    "Hello,\n\n这是今日报表。\n\nBest Regards",
)
```

#### 发送 HTML 邮件

```python
html = """
<html>
  <body>
    <h1>日报</h1>
    <table border="1">
      <tr><th>渠道</th><th>销售额</th></tr>
      <tr><td>电商</td><td>12,580</td></tr>
      <tr><td>门店</td><td>9,680</td></tr>
    </table>
  </body>
</html>
"""
email_reporter.send_daily_report("HTML 日报", html_content=html)
```

#### 发送带附件的邮件

```python
email_reporter.set_email_content(
    subject="带附件的报表",
    body="详见附件。",
    file_paths=["./attachments/"],
    file_names=["report.xlsx"],
)
email_reporter.send_email()
```

---

### 4. DateFormat（日期处理）

#### 生成格式化的日期 / 时间字符串

```python
from wei_data_shu.text import DateFormat

# 今天
today = DateFormat(interval_day=0, timeclass="date").get_timeparameter(Format="%Y-%m-%d")
print(today)  # 2026-03-17

# 昨天
yesterday = DateFormat(interval_day=1, timeclass="date").get_timeparameter(Format="%Y-%m-%d")

# 当前时间（时:分）
now = DateFormat(interval_day=0, timeclass="time").get_timeparameter(Format="%H:%M")
print(now)    # 14:30

# 当前时间戳
ts = DateFormat(interval_day=0, timeclass="timestamp").get_timeparameter()
print(ts)     # time.struct_time(...)

# 当前 datetime 对象
dt = DateFormat(interval_day=0, timeclass="datetime").get_timeparameter()
print(dt)     # datetime.datetime(...)
```

#### 标准化 DataFrame 中的日期列

```python
import pandas as pd
from wei_data_shu.text import DateFormat

df = pd.DataFrame({"日期": ["2026-01-01", "2026/01/02", "2026年1月3日"]})
df = DateFormat(interval_day=0, timeclass="date").datetime_standar(df, "日期")
print(df.dtypes)  # datetime64[ns]
```

---

### 5. StringBaba（字符串处理）

#### SQL 格式化

将多行文本拼接为 SQL `IN` 子句可用的格式：

```python
from wei_data_shu.text import StringBaba

text = """
苹果
香蕉
橘子
"""
result = StringBaba(text).format_string_sql()
print(result)  # "苹果","香蕉","橘子"
```

#### 字符串列表过滤

```python
from wei_data_shu.text import StringBaba

items = ["苹果手机", "香蕉牛奶", "橘子汽水", "笔记本"]
filtered = StringBaba(items).filter_string_list(["手机", "汽水"])
print(filtered)  # ['苹果手机', '橘子汽水']
```

---

### 6. TextAnalysis（文本分析）

需要安装可选依赖：`pip install wei-data-shu[analysis]`

#### 词频分析

```python
import pandas as pd
from wei_data_shu.text import TextAnalysis

data = {
    "Category": ["A", "A", "B", "B", "C"],
    "Text": [
        "我爱自然语言处理",
        "自然语言处理很有趣",
        "机器学习是一门很有前途的学科",
        "深度学习改变了人工智能",
        "数据科学包含统计与编程",
    ],
}
df = pd.DataFrame(data)

ta = TextAnalysis(df)
result = ta.get_word_freq(group_col="Category", text_col="Text", agg_func=" ".join)

print(result[["Category", "word_freq"]])
```

#### 词云绘制

```python
word_freqs = result["word_freq"].tolist()
titles = result["Category"].tolist()
ta.plot_wordclouds(word_freqs, titles, save_path="wordclouds.png")
```

---

### 7. TrendPredictor（趋势预测）

需要安装可选依赖：`pip install wei-data-shu[analysis]`

#### 单序列趋势预测

```python
import pandas as pd
from wei_data_shu.text import TrendPredictor

# 准备数据
dates = pd.date_range(start="2026-01-01", periods=100, freq="D")
values = [100 + i * 0.5 + (i % 7) * 3 for i in range(100)]  # 模拟趋势
df = pd.DataFrame({"日期": dates, "平滑均值": values})

# 创建预测器
predictor = TrendPredictor(
    market_trend_df=df,
    date_col="日期",
    smoothed_avg_col="平滑均值",
    steps=7,           # 预测未来 7 期
    order=(5, 1, 0),   # ARIMA 参数
    freq="D",          # 日频
)

# 查看原始数据（带趋势标签）
print(predictor.original_data())

# 获取预测结果
future_df, forecast, str_forecast, future_dates = predictor.forecast_data()
print(future_df)

# 模型评估
metrics = predictor.cross_validate(test_size=0.2)
print(metrics)

# 模型信息
info = predictor.get_model_info()
print(info)
```

#### 多序列趋势预测

```python
from wei_data_shu.text import MultipleTrendPredictor

# 多列数据，每列是一个独立序列
df_multi = pd.DataFrame({
    "电商": [100, 110, 120, 130, 140, 150, 160],
    "门店": [80, 82, 85, 88, 90, 95, 100],
    "分销": [50, 55, 60, 58, 62, 65, 70],
}, index=pd.date_range(start="2026-01-01", periods=7, freq="D"))

predictor = MultipleTrendPredictor(df_multi, steps=3)
predictions = predictor.predict()
print(predictions)
```

---

### 8. FileManagement（文件管理）

#### 查找最新文件夹

```python
from wei_data_shu.files import FileManagement

latest = FileManagement().find_latest_folder("./backups")
if latest:
    print(f"最新文件夹: {latest}")
```

#### 复制文件

```python
from wei_data_shu.files import FileManagement

fm = FileManagement()

# 复制单个文件
fm.copy_file_simple("./source/report.xlsx", "./dest/report.xlsx")

# 批量复制并重命名（提取文件名中的中文作为新文件名）
fm.copy_files(
    src_dir="./source",
    dest_dir="./dest",
    target_files=["data_2026.xls", "summary_2026.xls"],
    rename=True,
    file_type="xls",
)
```

#### 删除文件 / 文件夹

```python
fm.delete_folder_or_file("./temp/old_data.xlsx")
fm.delete_folder_or_file("./temp/archive")  # 递归删除目录
```

#### 创建文件夹

```python
fm.create_new_folder("./output/reports/2026")
```

---

### 9. ChatBot（AI 对话）

通过 Ollama API 接入本地大语言模型，支持流式输出和聊天记录持久化。

```python
from wei_data_shu.ai import ChatBot

bot = ChatBot(
    api_url="http://localhost:11434/api/chat",
    model="llama3.2",
    messages_file="messages.toml",       # 初始系统提示
    history_file="chat_history.toml",    # 聊天记录自动保存
)

# 流式对话
print("开始聊天（输入 'exit' 退出，输入 'new' 新建会话）")
while True:
    user_input = input("你: ")
    if user_input.lower() == "exit":
        break
    if user_input.lower() == "new":
        bot.start_new_chat()
        continue
    bot.send_message(user_input, stream=True)
```

参数说明：

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `api_url` | — | Ollama API 地址，如 `http://localhost:11434/api/chat` |
| `model` | `llama3.2` | 使用的模型名称 |
| `messages_file` | `messages.toml` | 初始消息配置文件（TOML 格式） |
| `history_file` | `chat_history.toml` | 聊天历史自动保存路径 |
| `stream` | `True` | 是否启用流式输出 |

---

### 10. Utils（通用工具）

#### 函数计时器

用装饰器测量函数执行时间：

```python
from wei_data_shu.utils import fn_timer

@fn_timer
def build_report():
    import time
    time.sleep(0.5)
    return "done"

result, elapsed = build_report()
print(f"耗时: {elapsed:.2f} 秒")  # Total time running build_report: 0.50 seconds
```

#### 密码生成

生成不含易混淆字符（`iIl1o0O`）的安全密码，适合临时密码/一次性密码：

```python
from wei_data_shu.utils import generate_password

# 默认长度 13
pwd = generate_password()
print(pwd)  # 8rY#FvQ7mK2$T

# 自定义长度
pwd16 = generate_password(16)
print(pwd16)

# 批量生成（通过 CLI）
# wei-data-shu password --count 5 --length 16
```

#### 颜色检索

内置 50+ 种常用颜色，支持英文名、中文名、HEX 码检索：

```python
from wei_data_shu.utils import search_colors, mav_colors

# 按英文名搜索
results = search_colors("mint")
print(results[0])
# {'index': 2, 'hex': '#5BC49F', 'name': 'mint green', 'name_zh': '薄荷绿'}

# 按中文名搜索
results = search_colors("薄荷")
print(results[0]["hex"])  # #5BC49F

# 按 HEX 搜索
results = search_colors("#5BC49F")
print(results[0]["name_zh"])  # 薄荷绿

# 查看所有颜色
print(len(mav_colors))   # 39
print(mav_colors[:3])    # ['#60ACFC', '#32D3EB', '#5BC49F']
```

通过 CLI 检索：

```bash
wei-data-shu colors
wei-data-shu colors mint
wei-data-shu colors 薄荷
wei-data-shu colors "#5BC49F"
```

输出格式：

```text
 2. #5BC49F | mint green | 薄荷绿
```

---

### 11. 数据分析（analysis）

需要安装可选依赖：`pip install wei-data-shu[analysis]`

#### 11.1 通用数据读取

```python
from wei_data_shu.analysis import read_csv, read_excel, read_any

df_csv = read_csv("sales.csv")            # CSV / TSV / TXT
df_xls = read_excel("sales.xlsx", sheet_name="6月")  # Excel 指定工作表
df_any = read_any("data.json")            # 按扩展名自动分发（csv/json/xlsx）
```

#### 11.2 DataCleaner — 链式数据清洗

```python
import pandas as pd
from wei_data_shu.analysis import DataCleaner

df = pd.DataFrame({
    "城市": ["北京", "上海", "北京", "深圳", None],
    "销售额": [100.0, 200.0, None, 300.0, 50.0],
    "成本":   [60.0, 120.0, 90.0, 180.0, 30.0],
})

cleaned = (
    DataCleaner(df)
    .drop_missing(subset=["城市"])            # 删除关键列缺失的行
    .fill_missing(strategy="median")          # 数值列按中位数填充
    .remove_duplicates()                      # 去重
    .clip_outliers(cols=["销售额"])           # 异常值缩尾（IQR 规则）
    .normalize(cols=["销售额", "成本"])       # min-max 归一化到 [0,1]
    .encode_categorical(cols=["城市"], method="onehot")  # 独热编码
    .get()
)

print(cleaned)
```

其他常用方法：`missing_summary()`（缺失统计）、`detect_outliers(method="iqr"/"zscore")`（异常值掩码）、`remove_outliers()`、`interpolate_missing()`、`to_datetime()` / `to_numeric()` / `infer_types()`。

#### 11.3 快速可视化

```python
from wei_data_shu.analysis import (
    plot_line, plot_bar, plot_hist, plot_box,
    plot_scatter, plot_pie, plot_corr_heatmap,
)

plot_line(df, x="日期", y="销售额", save_path="line.png")        # 折线
plot_bar(df, x="城市", y="销售额", save_path="bar.png")          # 柱状
plot_hist(df, col="销售额", bins=30, save_path="hist.png")       # 直方图
plot_box(df, cols=["销售额", "成本"], save_path="box.png")       # 箱线图
plot_scatter(df, x="销售额", y="成本", save_path="scatter.png")  # 散点
plot_pie(df, col="城市", save_path="pie.png")                    # 饼图
plot_corr_heatmap(df, method="pearson", save_path="corr.png")    # 相关热力图
```

所有绘图函数返回 `matplotlib.figure.Figure`，传 `save_path` 保存到文件，传 `show=True` 交互显示。中文标签需先配置中文字体：

```python
import matplotlib
matplotlib.rcParams["font.sans-serif"] = ["SimHei"]
matplotlib.rcParams["axes.unicode_minus"] = False
```

---

## 🗺 Roadmap（计划表）

以下功能已列入规划、尚未实现，欢迎贡献：

| 类别 | 功能 | 说明 | 优先级 |
| --- | --- | --- | --- |
| 数据接入 | SQLite / PostgreSQL 支持 | 数据库层目前仅 MySQL，计划扩展本地零配置的 SQLite 与常用 PostgreSQL | 中 |
| 数据接入 | HTTP/API 数据抓取封装 | 将 `requests` 封装为"拉取 → 解析 → DataFrame"的一站式接口 | 中 |
| 数据接入 | 数据导出封装 | 一键导出 DataFrame 到 CSV / JSON / Excel（多工作表） | 低 |
| 统计分析 | 描述性统计汇总 | 一键输出均值/分位数/偏度/峰度/缺失比例 | 高 |
| 统计分析 | 相关性分析 API | 独立的 Pearson / Spearman / Kendall 相关系数与显著性 | 高 |
| 统计分析 | 假设检验 | t 检验、卡方检验、ANOVA | 中 |
| 统计分析 | 透视表 / 抽样封装 | pivot table、随机抽样、分层抽样 | 中 |
| 建模 | 回归与分类 | 线性回归、逻辑回归封装 | 中 |
| 建模 | 聚类与降维 | KMeans、PCA | 中 |
| 建模 | 通用模型评估 | 分类/回归指标一键计算与交叉验证 | 低 |
| 交付 | 分析报告自动生成 | HTML / Word 模板化报告，自动嵌入图表与统计结论 | 中 |
| 交付 | 图表插入 Excel | 将 matplotlib 图写入 Excel 工作表，打通 analysis 与 excel 领域 | 中 |
| 工程 | 定时任务调度 | 报表/抓取任务的定时执行配置 | 低 |

---

## 🤝 参与贡献

**English:** We welcome contributions! If you have any questions, suggestions, or improvements, please feel free to:

- [Submit an Issue](https://github.com/phoenixlucky/wei-data-shu/issues) — Report bugs or request features
- [Submit a Pull Request](https://github.com/phoenixlucky/wei-data-shu/pulls) — Contribute code

**中文:** 我们欢迎并感谢您的贡献！如果您有任何问题、建议或改进，请随时：

- [提交 Issue](https://github.com/phoenixlucky/wei-data-shu/issues) — 报告 bug 或提出功能建议
- [提交 Pull Request](https://github.com/phoenixlucky/wei-data-shu/pulls) — 贡献代码

---

## 📄 许可证

**Copyright © 2026 Ethan Wilkins.**

**English:** This project is free software: you can redistribute it and/or modify it under the terms of the [GNU General Public License v3 (GPL-3.0)](https://www.gnu.org/licenses/gpl-3.0.html).

**中文:** 本项目为自由软件，您可以依据 [GNU General Public License v3 (GPL-3.0)](https://www.gnu.org/licenses/gpl-3.0.html) 的条款重新分发或修改。

完整的许可证文本请参见项目根目录的 [LICENSE](./LICENSE) 文件。

---

**免责声明 / Disclaimer:**

**English:** This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

**中文:** 本程序按"原样"分发，不附带任何明示或暗示的担保。有关详细信息，请参阅 GNU General Public License。
