wei-data-shu

Domain-oriented office automation and data utility toolkit.

wei-data-shu 是一个面向办公自动化和数据处理的 Python 工具库，覆盖数据库、Excel、文件处理、文本分析、邮件发送、AI 对话和常用工具函数等场景。

当前文档对应版本：5.0.2

当前版本的使用原则：

• 根包 wei_data_shu 只暴露领域包
• 所有公开用法统一为 wei_data_shu.<domain> 导入
• 历史平铺模块路径已移除

快速开始

安装

pip install wei-data-shu

按需安装可选能力：

# 文本分析 / 词云 / 趋势预测
pip install "wei-data-shu[analysis]"

# 需要通过本机 Excel 应用操作工作簿
pip install "wei-data-shu[excel-client]"

升级：

pip install --upgrade wei-data-shu

导入方式

from wei_data_shu.database import MySQLDatabase
from wei_data_shu.excel import ExcelManager
from wei_data_shu.files import FileManagement
from wei_data_shu.mail import DailyEmailReport
from wei_data_shu.text import DateFormat, StringBaba, TextAnalysis
from wei_data_shu.ai import ChatBot
from wei_data_shu.utils import fn_timer, generate_password, mav_colors, search_colors

命令行

安装后可直接使用：

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 password --count 10 --length 13

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

today = DateFormat(interval_day=0, timeclass="date").get_timeparameter(Format="%Y-%m-%d")
report_path = Path(f"demo-report-{today}.xlsx")

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)

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-03-17.xlsx
首行数据： ['日期', '渠道', '销售额']
颜色搜索： #5BC49F mint green 薄荷绿
临时密码： 8rY#FvQ7mK2$T

功能概览

领域	导入路径	主要用途
数据库	wei_data_shu.database	MySQL 连接、查询、执行 SQL
Excel	wei_data_shu.excel	读写工作簿、样式、拆分合并、Excel App 操作
文件	wei_data_shu.files	查找最新文件、复制、重命名
邮件	wei_data_shu.mail	发送日报、HTML 邮件
文本	wei_data_shu.text	日期处理、字符串清洗、词频分析
AI	wei_data_shu.ai	对接 Ollama 聊天接口
工具	wei_data_shu.utils	计时器、颜色表、密码生成、颜色搜索

项目结构

wei_data_shu/
├─ wei_data_shu/            # 核心包
│  ├─ _api.py               # 统一公开 API 注册表
│  ├─ ai/                   # AI 能力
│  ├─ database/             # 数据库能力
│  ├─ docs/                 # 文档工作流导出
│  ├─ excel/                # Excel 能力
│  ├─ files/                # 文件处理能力
│  ├─ mail/                 # 邮件能力
│  ├─ text/                 # 文本处理能力
│  └─ utils/                # 通用工具
├─ tests/                   # 单元测试
├─ docs/plans/              # 架构设计文档
├─ pyproject.toml           # 包配置
└─ README.md

结构说明：

• 核心代码统一放在 wei_data_shu/ 包下；
• 根包通过 _api.py 统一维护公开导出，且根包只暴露领域包；
• 优先使用按领域划分的子包，如 wei_data_shu.excel、wei_data_shu.text、wei_data_shu.files；
• 测试代码放在 tests/，避免和发布包混在一起；
• 构建产物（build/、dist/、*.egg-info）不纳入版本控制。

用法示例

1. MySQLDatabase

用于快速连接 MySQL、执行 SQL、读取结果。

from wei_data_shu.database import MySQLDatabase

mysql_config = {
    "host": "your_host",
    "port": 3306,
    "user": "your_user",
    "password": "your_password",
    "database": "your_database",
}

db = MySQLDatabase(mysql_config)

insert_query = "INSERT INTO your_table (column1, column2) VALUES (%s, %s)"
insert_params = ("value1", "value2")
db.execute_query(insert_query, insert_params)

select_query = "SELECT * FROM your_table"
results = db.fetch_query(select_query)
for row in results:
    print(row)

update_query = "UPDATE your_table SET column1 = %s WHERE column2 = %s"
update_params = ("new_value", "value2")
db.execute_query(update_query, update_params)

delete_query = "DELETE FROM your_table WHERE column1 = %s"
delete_params = ("new_value",)
db.execute_query(delete_query, delete_params)

db.close()

如果你希望在数据库对象上直接启用 AI 聊天：

from wei_data_shu.database import MySQLDatabase

cfg = {
    "user": "root",
    "password": "你的密码",
    "host": "127.0.0.1",
    "port": 3306,
    "database": "mlcorpus",
}
db = MySQLDatabase(cfg)
db.run_ai_chatbot(chat_history_size=5, system_msg="System: You are a helpful AI assistant.")

2. Excel

Excel 相关能力分成 4 类：日常读写、快捷方法、Excel App 操作、高级文件处理。

推荐优先使用 ExcelManager。

from pathlib import Path
from wei_data_shu.excel import ExcelManager, ExcelHandler, OpenExcel, ExcelOperation, quick_excel, read_excel_quick

2.1 ExcelManager

from wei_data_shu.excel import ExcelManager

wb = ExcelManager("data.xlsx")

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)

with ExcelManager("data.xlsx") as wb:
    wb.fast_write("Sheet1", [[1, 2], [3, 4]], 1, 1)

wb.save()
wb.close()

DataFrame 支持：

import pandas as pd
from wei_data_shu.excel import ExcelManager

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

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

with ExcelManager("data.xlsx") as wb:
    df = wb.read_dataframe("Sheet1")

工作表管理：

from wei_data_shu.excel import ExcelManager

wb = ExcelManager("data.xlsx")

wb.create_sheet("NewSheet")
info = wb.get_sheet_info("Sheet1")
print(info)
wb.copy_sheet("Sheet1", "Sheet1_Copy")
wb.delete_sheet("OldSheet")

2.2 quick_excel / read_excel_quick

from wei_data_shu.excel import quick_excel, read_excel_quick

wb = quick_excel("data.xlsx", [["Name", "Age"], ["Alice", 25]])
data = read_excel_quick("data.xlsx")
df = read_excel_quick("data.xlsx", as_dataframe=True)

2.3 ExcelHandler

from wei_data_shu.excel import ExcelHandler

eh = ExcelHandler("data.xlsx")

eh.excel_write("Sheet1", [[1, 2], [3, 4]], 1, 1, 2, 2)
data = eh.excel_read("Sheet1", 1, 1, 2, 2)
eh.excel_save_as("output.xlsx")
eh.excel_quit()

2.4 OpenExcel

适合需要通过本机 Excel 应用执行 RefreshAll() 等操作。 注意：需要安装 Microsoft Excel。

from wei_data_shu.excel import OpenExcel

with OpenExcel("data.xlsx").my_open() as wb:
    wb.fast_write("Sheet1", [[1, 2], [3, 4]], 1, 1)

with OpenExcel("data.xlsx").open_save_Excel() as appwb:
    appwb.api.RefreshAll()

sheets = OpenExcel("data.xlsx").file_show(filter=["sheet", "报表"])
print(sheets)

2.5 ExcelOperation

from wei_data_shu.excel import ExcelOperation

op = ExcelOperation("data.xlsx", "output_folder")
files = op.split_table()
op.merge_tables(["file1.xlsx", "file2.xlsx"], "merged.xlsx")
csv_path = op.convert_to_csv()

2.6 完整流水线示例

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

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

with ExcelManager(f) as wb:
    wb.fast_write("Sheet1", [["Name", "Age"], ["Alice", 25], ["Bob", 30]], 1, 1)

with OpenExcel(f).open_save_Excel() as appwb:
    appwb.api.RefreshAll()

op = ExcelOperation(f, str(base / "output"))
op.split_table()

csv_file = op.convert_to_csv()

3. DailyEmailReport

用于发送纯文本或 HTML 邮件。

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

text_content = """
Hello,

Here is your daily report.

[Insert your report content here.]

Regards,
Your Name
"""
email_reporter.send_daily_report("Daily Report", text_content)

html_content = """
<html>
  <body>
    <h1>Daily Report</h1>
    <p>Hello,</p>
    <p>Here is your <b>daily report</b>.</p>
    <ul>
      <li>Item 1</li>
      <li>Item 2</li>
    </ul>
    <p>Regards,<br>
    Your Name</p>
  </body>
</html>
"""
email_reporter.send_daily_report("HTML Report", html_content, is_html=True)

4. DateFormat

用于快速生成日期、时间、时间戳，以及对 DataFrame 列进行格式化。

from wei_data_shu.text import DateFormat

x = DateFormat(interval_day=0, timeclass="date").get_timeparameter(Format="%Y-%m-%d")
print(x)

df = DateFormat(interval_day=0, timeclass="date").datetime_standar(df, "日期")

5. FileManagement

用于寻找最新目录、复制文件和批量重命名。

from wei_data_shu.files import FileManagement

FileManagement().copy_files(
    latest_folder2,
    destination_directory,
    target_files2,
    rename=True,
    file_type="xls",
)

latest_folder = FileManagement().find_latest_folder(base_directory)

6. StringBaba

用于字符串清洗和 SQL 拼接辅助。

from wei_data_shu.text import StringBaba

text = """
萝卜
白菜
"""
formatted_str = StringBaba(text).format_string_sql()

7. TextAnalysis

用于中文文本词频分析和词云绘制。

import pandas as pd
from wei_data_shu.text import TextAnalysis

data = {
    "Category": ["A", "A", "B", "D", "C"],
    "Text": [
        "我爱自然语言处理",
        "自然语言处理很有趣",
        "机器学习是一门很有前途的学科",
        "我对机器学习很感兴趣",
        "数据科学包含很多有趣的内容",
    ],
}

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

word_freqs = result["word_freq"].tolist()
titles = result["Category"].tolist()
ta.plot_wordclouds(word_freqs, titles)

8. ChatBot

用于连接 Ollama 聊天接口。

from wei_data_shu.ai import ChatBot

bot = ChatBot(api_url="http://localhost:11434/api/chat")

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)

9. Utils

提供通用计时器、调色板、密码生成和颜色搜索能力。

from wei_data_shu.utils import fn_timer, generate_password, mav_colors, search_colors

@fn_timer
def build_report():
    return "done"

result, elapsed = build_report()
print(result, elapsed)
print(generate_password())
print(mav_colors[:3])
print(search_colors("薄荷"))

颜色检索支持英文、HEX、中文关键字，并返回中英文名称：

from wei_data_shu.utils import search_colors

print(search_colors("mint"))
print(search_colors("薄荷"))
print(search_colors("#5BC49F"))

命令行查看颜色和生成密码：

wei-data-shu colors
wei-data-shu colors mint
wei-data-shu colors 薄荷
wei-data-shu colors "#5BC49F"
wei-data-shu password --count 50 --length 13

Contributing / 参与贡献

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 - 贡献代码

---

License / 许可证

Copyright © 2026 Ethan Wilkins. All rights reserved.

English: This project is licensed under the MIT License.

中文: 本项目采用 MIT 许可证 开源许可。

MIT License

Copyright (c) 2026 Ethan Wilkins

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

免责声明 / Disclaimer:

English: This software is provided "as is", without warranty of any kind, express or implied. The authors or copyright holders shall not be liable for any claims, damages, or other liabilities arising from the use of this software.

中文: 本软件按"原样"提供，不附带任何明示或暗示的担保。在任何情况下，作者或版权所有者均不对因使用本软件而产生的任何索赔、损害或其他责任承担责任。