✨ 特性

• 九大领域一站覆盖 — MySQL 数据库、Excel 电子表格、文档（Markdown / Word / PowerPoint 读写与互转，Excel 工作簿可作转换来源）、文件管理、文本分析（词频/词云/趋势预测）、数据分析（通用读取/清洗/可视化）、邮件发送、Ollama AI 对话、通用工具
• 文档格式自由互转 — md / docx / pptx 任意方向互转，并可直接读取 xlsx 工作簿（一个工作表一页），共享一套 Document 中间模型；一行式 API 把 DataFrame 直接变成 Word 或 PPT
• 领域化分包设计 — 每个领域一个包，根包仅暴露入口，结构清晰、职责单一
• 惰性导入零开销 — 各领域包按需懒加载，import wei_data_shu 不拖慢启动
• 开箱即用 — 统一 wei_data_shu.<domain> 导入约定，配合完整示例，5 分钟上手
• 可选依赖按需安装 — Word/PPT/Excel 源、文本分析、Excel App 等重量能力通过 extras 安装，核心包轻量
• Jupyter 友好 — 图表返回 Figure 直接内联显示，中文字体自动配置，Document 在 notebook 中渲染带边框的 HTML 表格预览

📖 目录

• 快速开始
  • 安装
  • 导入方式
  • 文档读写与互转
  • 命令行工具
  • 5 分钟上手
• 功能概览
• 项目结构
• 用法示例
  • 使用手册（完整分域示例）
• 参与贡献
• 发布
• 许可证

🚀 快速开始

安装

pip install wei-data-shu

核心包仅依赖 toml 与 requests，开箱即用（Markdown 读写零额外依赖）；重量能力按需安装：

# 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]"

# Word / PowerPoint 读写、Excel(.xlsx) 读取与 md / docx / pptx 互转
# 依赖: python-docx, python-pptx, openpyxl（Markdown 与 HTML 预览零额外依赖）
pip install "wei-data-shu[docs]"

升级到最新版本：

pip install --upgrade wei-data-shu

导入方式

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

from wei_data_shu.database import MySQLDatabase, MySQLDatabaseError
from wei_data_shu.excel import ExcelManager, OpenExcel, ExcelOperation, quick_excel
from wei_data_shu.docs import Document, to_markdown, to_word, to_ppt, convert
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, in_notebook

文档读写与互转

docs 域的格式共享一套 Document 中间模型：md / docx / pptx 可读可写， xlsx 只作为读取来源（每个工作表渲染为一页）。任意两方互转即自动成立：

from wei_data_shu.docs import Document, convert, to_markdown, to_ppt, to_word

rows = [["渠道", "销售额"], ["电商", 12580], ["门店", 9680]]

# 一行式：二维数据 / DataFrame -> Markdown、Word、PPT
to_markdown(rows, "report.md", title="月度报告")   # 零依赖
to_word(rows, "report.docx", title="月度报告")     # 需要 wei-data-shu[docs]
to_ppt(rows, "report.pptx", title="月度报告")      # 需要 wei-data-shu[docs]

# 链式构造更复杂的文档
Document(title="月度报告").add_heading("月度报告", 1).add_table(rows).add_bullets(
    ["电商同比 +12%", "门店同比 +3%"]
).save("report.md")

# 跨格式互转：md / docx / pptx 任意方向（按扩展名自动分派）
convert("report.md", "report.docx")
convert("report.docx", "outline.pptx")

# Excel 工作簿作为来源：整本读入（一个工作表一页）
convert("sales.xlsx", "sales.md")

在 Jupyter 中把 Document 作为单元格最后一个表达式，会渲染带边框的 HTML 表格预览 （_repr_html_）；也可显式调用 document.to_html() / document.to_markdown()。

缺少可选依赖时会抛出带安装命令的 ImportError，例如 pip install wei-data-shu[docs]。

Excel 宏操作

.xlsm 和 .xltm 文件通过 ExcelManager 读写时会自动保留 VBA 内容。运行宏或控制宏安全级别需要 Windows 本机安装 Microsoft Excel，并安装 excel-client 可选依赖：

pip install "wei-data-shu[excel-client]"

from wei_data_shu.excel import OpenExcel

# 启用宏打开，执行操作后自动保存
with OpenExcel("report.xlsm").open_with_macros_enabled() as workbook:
    workbook.api.RefreshAll()

# 禁用宏打开不受信任的工作簿
with OpenExcel("untrusted.xlsm").open_with_macros_disabled() as workbook:
    print(workbook.name)

# 调用指定 VBA 宏，可传递参数并保存到新文件
result = OpenExcel("report.xlsm", "report-result.xlsm").run_macro(
    "Module1.RefreshReport",
    args=["2026-09"],
)

也可以直接使用 open_save_Excel(macro_security="enable|disable|default") 控制当前 Excel 会话的宏安全级别。该设置不会修改 Excel 的全局安全配置。

命令行工具

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

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

# 颜色检索
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  # 列出各工作表行数

# 文档互转与预览
wei-data-shu convert report.md -o report.docx   # md -> docx / pptx
wei-data-shu md report.docx                     # 把任意支持的文档打印为 Markdown

5 分钟上手

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

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

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 文件，并在终端看到类似输出：

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

🧭 功能概览

🗂 项目结构

wei_data_shu/
├─ wei_data_shu/            # 核心包
│  ├─ __init__.py           # 根包入口，按需惰性加载各个领域包
│  ├─ __main__.py           # python -m 入口
│  ├─ _api.py               # 统一公开 API 注册表
│  ├─ cli.py                # 命令行接口（colors / password / date / excel / convert / md）
│  ├─ 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/                 # 文档能力
│  │  ├─ model.py           #   中间模型: Document 与各类节点
│  │  ├─ md.py              #   Markdown 读写（零第三方依赖）
│  │  ├─ html.py            #   HTML 片段渲染（零第三方依赖，notebook 预览）
│  │  ├─ word.py            #   Word 读写（python-docx）
│  │  ├─ slides.py          #   PowerPoint 读写（python-pptx）
│  │  ├─ sheet.py           #   Excel 工作簿读取（openpyxl，仅作源格式）
│  │  ├─ conversion.py      #   跨格式互转 convert()
│  │  ├─ quick.py           #   一行式 API: to_markdown / to_word / to_ppt
│  │  ├─ workflow.py        #   文档工作流（Excel + 文件处理组合）
│  │  └─ _deps.py           #   可选依赖守卫
│  ├─ 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
│     └─ notebook.py        #   in_notebook（Jupyter 环境探测）
├─ tests/                   # 单元测试
├─ examples/                # 可运行示例（quickstart / excel / chatbot / docs_demo）
├─ docs/plans/              # 架构设计文档
├─ pyproject.toml           # 包配置 & 依赖
├─ LICENSE                  # GPL-3.0 许可证
└─ README.md                # 本文件

设计原则

💻 用法示例

完整的分域示例（数据库 / Excel / 文档读写与互转 / 邮件 / 日期 / 字符串 / 文本分析 / 趋势预测 / 文件管理 / AI 对话 / 通用工具 / 数据分析）请参阅 📖 使用手册。

这里仅保留一个不依赖任何第三方服务的最小示例：

from wei_data_shu.docs import to_markdown
from wei_data_shu.text import DateFormat
from wei_data_shu.utils import generate_password, search_colors

print(DateFormat(interval_day=1).get_timeparameter())  # 昨天日期
print(generate_password(13))                           # 安全密码
print(search_colors("薄荷")[0])                        # 颜色检索
print(to_markdown([["渠道", "销售额"], ["电商", 12580]], title="月报"))

🗺 Roadmap（计划表）

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

🚢 发布

打 wei-data-shu-<版本> 格式的 tag（如 wei-data-shu-0.8.0）并推送，CI 会自动构建并发布到 PyPI：

git tag wei-data-shu-0.8.0
git push origin wei-data-shu-0.8.0

前提：仓库需配置 PYPI_TOKEN secret（见 release.yml）。 发布前请先在 pyproject.toml 与 CHANGELOG.md 中更新版本号与变更记录。

🤝 参与贡献

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

• Submit an Issue — Report bugs or request features
• Submit a Pull Request — Contribute code

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

• 提交 Issue — 报告 bug 或提出功能建议
• 提交 Pull Request — 贡献代码

📄 许可证

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).

中文: 本项目为自由软件，您可以依据 GNU General Public License v3 (GPL-3.0) 的条款重新分发或修改。

完整的许可证文本请参见项目根目录的 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。