这库是给谁用的

• 天天和表格打交道的人 — 批量读 Excel、拆分合并工作簿、把数据一键变成 Word / PPT 汇报材料
• 要清洗和可视化数据的人 — 读 CSV / Excel，处理缺失值和异常值，画折线图、热力图，跑趋势预测
• 写自动化脚本的人 — 把「取数 → 出报表 → 发邮件」串成一条流水线
• 想用 AI 又不想上云的人 — 连本机 Ollama 对话，聊天记录还能存下来

你不需要背一堆库名和参数：所有能力都挂在 wei_data_shu.<领域> 下，代码里用到哪个域，才加载哪个域。

✨ 特性

• 九大领域一个入口 — 数据库（MySQL）、Excel、文档、文件、文本、数据分析、邮件、AI 对话、通用工具，都在 wei_data_shu 下面
• 文档格式自由互转 — md / docx / pptx 任意方向互转，xlsx 也能整本读进来当数据源；底层共用一套 Document 中间模型，所以格式之间可以随意组合
• 一行出文档 — 二维列表或 DataFrame 直接变成 Markdown / Word / PPT 文件
• 启动不为它买单 — 根包只暴露领域名，import wei_data_shu 不会顺手把 pandas / matplotlib 拉起来
• 核心包很轻 — 只依赖 toml 和 requests；Excel、Word、数据库、图表这些重能力各占一个 extras，按需安装
• Jupyter 里顺手 — 图表返回 Figure 直接内联显示，中文字体自动配好，Document 渲染成带边框的表格预览

📖 目录

• 这库是给谁用的？
• 特性
• 快速开始
  • 安装
  • 按需安装额外能力
  • 第一个例子
  • 5 分钟上手
  • 导入方式
  • 文档读写与互转
  • Excel 宏操作
  • 命令行工具
• 常见场景速查
• 功能概览
• 项目结构
  • 设计原则
• 用法示例
  • 使用手册（完整分域示例）
• Roadmap 路线图
• 发布
• 参与贡献
• 许可证

🚀 快速开始

安装

pip install wei-data-shu

核心包只依赖 toml 和 requests。Markdown 读写和 HTML 预览零额外依赖，装完就能用。

按需安装额外能力

需要什么装什么，不必为了写一个 Word 把整条数据分析链都拖进来：

邮件、文件管理、AI 对话、颜色 / 密码 / 日期这些工具都在核心包里（只用标准库和 requests），不用装 extras。

升级到最新版本：

pip install --upgrade wei-data-shu

第一个例子

这段不需要任何 extras，装完核心包就能跑：

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=0).get_timeparameter(Format="%Y-%m-%d"))  # 今天
print(DateFormat(interval_day=1).get_timeparameter())                   # 昨天，默认 %Y%m%d
print(generate_password(13))                                            # 13 位安全密码

mint = search_colors("薄荷")[0]                                         # 按中文名找颜色
print(mint["hex"], mint["name"], mint["name_zh"])

print(to_markdown([["渠道", "销售额"], ["电商", 12580]], title="月报"))

输出类似（日期取决于运行当天，密码每次都不一样）：

2026-09-16
20260915
8rY#FvQ7mK2$T
#5BC49F mint green 薄荷绿
# 月报

| 渠道 | 销售额 |
| --- | --- |
| 电商 | 12580 |

to_markdown 不给路径就返回文本，给了路径写文件并返回 Path。要在 Jupyter 里看更漂亮的预览，把 Document 放在单元格最后一行即可。

5 分钟上手

下面这段是真能干活的例子，需要先装 wei-data-shu[excel]（用到 ExcelManager）：

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. 写一张日报表，再读回来看一眼
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("薄荷")
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-09-16.xlsx
首行数据： ['日期', '渠道', '销售额']
颜色搜索： #5BC49F mint green 薄荷绿
临时密码： 8rY#FvQ7mK2$T

导入方式

所有公开 API 都从 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-09-16
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
wei-data-shu md2html report.md -o report.html    # 渲染成 HTML 页面（--fragment 只要片段）

# 文件与文本小工具（核心包，无需 extras）
wei-data-shu files latest "D:\downloads"        # 找创建时间最新的子文件夹
wei-data-shu text clean notes.txt               # 去重 + 重新编号
wei-data-shu text clean notes.txt --mode sql    # 转成 SQL IN 列表
wei-data-shu table report.md                    # Markdown 表格 -> CSV

# 数据分析（需要 analysis extras）
wei-data-shu data info sales.csv                # 行列数 / 缺失值 / 前 5 行
wei-data-shu plot sales.csv -k line -x 月份 -y 销量 -o line.png

# 邮件与数据库（密码建议放环境变量，别写进 shell 历史）
wei-data-shu mail send --host smtp.qq.com --user me@qq.com \
  --to boss@corp.com --subject "日报" --body-file report.html --html
wei-data-shu db query --user root --database shop --sql "SELECT * FROM users LIMIT 5"

🔍 常见场景速查

不知道用哪个域时，先在这里找：

🧭 功能概览

docs 域里还包含 ExcelHandler / ExcelOperation / OpenExcel / FileManagement，用于把 Excel 和文件操作编排成复合工作流。

🗂 项目结构

wei_data_shu/
├─ wei_data_shu/            # 核心包
│  ├─ __init__.py           # 根包入口，按需惰性加载各个领域包
│  ├─ __main__.py           # python -m 入口
│  ├─ _api.py               # 统一公开 API 注册表
│  ├─ cli.py                # 命令行接口（14 个子命令，见 docs/USAGE.md 第 1 节）
│  ├─ 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 环境探测）
│     └─ textio.py          #   read_text, bom_tolerant_encoding（BOM 安全读取）
├─ tests/                   # 单元测试
├─ examples/                # 可运行示例（quickstart / excel / chatbot / docs_demo）
├─ docs/plans/              # 架构设计文档
├─ pyproject.toml           # 包配置 & 依赖
├─ LICENSE                  # GPL-3.0 许可证
└─ README.md                # 本文件

设计原则

💻 用法示例

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

这里保留一个不依赖任何第三方服务、也不需要 extras 的最小例子：

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.9.2）并推送，CI 会自动构建并发布到 PyPI：

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

前提：仓库需配置 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。