基于Python打造简单的周报邮件附件自动下载工具_Python

背景：重复劳动的困境

在企业项目管理场景中，项目组成员每周需向负责人发送周报邮件。邮件标题通常遵循统一规范，格式如 [周报]年度周次_项目名称_公司名称，附件为 word 文档（.docx），记录本周工作内容、下周计划及问题反馈。

随着项目数量增加，负责人每周需要手动打开邮箱、逐一筛选周报邮件、逐个下载附件，再统一归档到本地文件夹。这一过程枯燥、易出错，当邮件数量达到数十封时，人工操作耗时可能超过 15 分钟，且存在遗漏风险。

痛点总结：手动筛选效率低、附件遗漏风险高、重复劳动消耗精力，缺乏自动化工具支持。

目标：一键自动化收取

设计并开发一款带图形界面的桌面工具，实现以下核心目标：

可配置的邮件连接：支持 imap 协议，可配置服务器地址、端口、ssl 开关及账户密码
按日期范围筛选邮件：通过日期选择器指定发件日期区间，精准缩小搜索范围
标题正则匹配过滤：仅处理标题以 [周报] 或【周报】开头的邮件，自动跳过无关邮件
附件批量下载归档：提取符合条件邮件中的 docx/xlsx/pdf 等文档附件，保存到指定目录，自动处理同名冲突
实时日志与进度反馈：界面内彩色日志实时显示处理状态，进度条直观呈现完成进度，支持随时中断

方法：技术选型与架构设计

技术栈选型

模块	选用库	理由
图形界面	wxpython	原生控件风格、跨平台、支持 datepickerctrl、richtext 等高级组件
邮件协议	imaplib（标准库）	python 内置，支持 imap4 和 imap4_ssl，无需额外安装
邮件解析	email（标准库）	完整的 mime 解析、多编码头字段解码能力
正则匹配	re（标准库）	灵活匹配全角/半角括号格式的周报标题
并发处理	threading（标准库）	将网络 io 操作移入后台线程，防止界面冻结

整体架构

程序采用经典的 主线程 ui + 后台工作线程 模式，通过 wx.callafter() 实现线程安全的 ui 更新。

核心架构关系：

mainframe（主线程）
  ├─ _build_ui()　　　　  → 构建所有 ui 控件
  ├─ on_start()　　　　  → 收集配置 → 启动 emailworker
  ├─ on_worker_callback()　→ 接收后台回调 → 更新 ui
  └─ log_msg()　　　　  → 彩色日志渲染

emailworker（后台线程，继承 threading.thread）
  ├─ run()　　→ imap 连接 → 搜索 → 筛选 → 下载
  ├─ log()　　→ wx.callafter 回调主线程
  └─ stop()　 → 设置 _stop_event 优雅退出

关键算法设计

① mime 头解码：邮件标题可能使用 utf-8、gbk、base64 等多种编码方式，需逐段解码后拼接：

pythondecode_mime_header()

def decode_mime_header(header_str):
    decoded_parts = email.header.decode_header(header_str)
    result = []
    for part, charset in decoded_parts:
        if isinstance(part, bytes):
            if charset:
                try:
                    result.append(part.decode(charset, errors='replace'))
                except (lookuperror, unicodedecodeerror):
                    result.append(part.decode('utf-8', errors='replace'))
            else:
                result.append(part.decode('utf-8', errors='replace'))
        else:
            result.append(str(part))
    return "".join(result)

② 正则标题匹配：同时兼容半角 [周报] 与全角【周报】两种括号形式：

pythonis_weekly_report_subject()

def is_weekly_report_subject(subject):
    subject = subject.strip()
    # [\[【] 匹配半角左括号或全角左括号
    # [\]】] 匹配半角右括号或全角右括号
    pattern = r'^[\[【]周报[\]】]'
    return bool(re.match(pattern, subject))

③ imap 日期搜索边界修正：imap 协议的 before 语义是"严格小于"，因此结束日期需 +1 天才能包含当天的邮件：

python日期边界处理

since_str = cfg['date_from'].strftime("%d-%b-%y").upper()
# before 为严格小于，结束日 +1 天以包含当天
before_dt = cfg['date_to'] + timedelta(days=1)
before_str = before_dt.strftime("%d-%b-%y").upper()
search_criteria = f'(since "{since_str}" before "{before_str}")'

④ 两阶段邮件获取策略：先只拉取邮件头（轻量），完成标题筛选后，再对匹配邮件获取完整内容（rfc822），显著减少网络流量：

python分阶段 fetch

# 阶段一：仅获取标题头，快速过滤
status, header_data = mail.fetch(
    msg_id,
    "(body[header.fields (subject date from)])"
)

# 阶段二：仅对匹配邮件获取完整内容
status, msg_data = mail.fetch(msg_id, "(rfc822)")

过程：代码实现详解

ui 构建：sizer 布局体系

wxpython 使用 sizer（布局管理器） 而非绝对坐标来组织控件，程序中使用了 wx.boxsizer、wx.flexgridsizer 和 wx.staticboxsizer 三种 sizer 的组合嵌套。

sizer 层级结构：

main_sizer（boxsizer 垂直）
  ├─ srv_sizer（staticboxsizer）→ flexgridsizer 4列网格
  ├─ date_sizer（staticboxsizer 水平）→ 两个 datepickerctrl
  ├─ dir_outer（staticboxsizer 垂直）
  │　  ├─ dir_sizer（boxsizer 水平）→ 路径输入框 + 浏览按钮
  │　  └─ chk_only_docx（checkbox）
  ├─ btn_sizer（boxsizer 水平）→ 三个操作按钮
  ├─ gauge（进度条）
  └─ log_sizer（staticboxsizer）→ 多行文本框 + 清空按钮

踩坑记录：同一个控件（如 checkbox）不能同时被加入两个不同的 sizer，否则 wxpython 会在运行时抛出 wxassertionerror: adding a window already in a sizer。解决方案是确保每个控件只归属于唯一一个 sizer。

多线程：防止界面冻结

邮件收取涉及大量网络 io，若在主线程中执行会导致界面完全卡死（无响应）。程序将所有网络操作封装在继承自 threading.thread 的 emailworker 类中，在后台线程运行。

wxpython 要求所有 ui 操作必须在主线程执行，因此后台线程通过 wx.callafter() 将回调函数"投递"到主线程的事件队列，再由主线程安全地更新日志、进度条等控件。

python线程安全的 ui 更新

# 后台线程中 —— 不直接操作 ui，而是通过 callafter 委托
def log(self, msg, level="info"):
    wx.callafter(self.callback, "log", msg, level)

# 主线程中 —— 统一在此处实际操作 ui 控件
def on_worker_callback(self, action, *args):
    if action == "log":
        msg, level = args
        self.log_msg(msg, level)   # 安全地写入文本框
    elif action == "progress":
        current, total = args
        pct = int(current / total * 100) if total else 0
        self.gauge.setvalue(pct)

附件提取：mime 结构遍历

一封邮件的 mime 结构是树状的，正文、html 版本和附件分别存储在不同的 part 中。程序使用 msg.walk() 遍历所有 part，通过 content-disposition: attachment 头字段识别附件：

pythonmime 附件提取

for part in msg.walk():
    content_disp = str(part.get("content-disposition", ""))
    if "attachment" not in content_disp.lower():
        continue              # 跳过正文、html 等非附件 part

    filename = part.get_filename()
    if not filename:
        continue

    filename = decode_mime_header(filename)   # 解码文件名编码
    payload  = part.get_payload(decode=true)    # 解码 base64/qp

    with open(save_path, 'wb') as f:
        f.write(payload)

同名文件冲突处理

不同项目组可能发来文件名相同的 word 附件（如 "周报.docx"）。程序在写入前检查目标路径是否存在，若存在则自动添加序号后缀 _1、_2 避免覆盖：

python同名文件自动重命名

save_path = os.path.join(save_dir, filename)
if os.path.exists(save_path):
    base, ext = os.path.splitext(filename)
    counter = 1
    while os.path.exists(save_path):
        save_path = os.path.join(
            save_dir, f"{base}_{counter}{ext}"
        )
        counter += 1

彩色日志渲染

日志区域使用 wx.te_rich2 模式的 textctrl，配合 wx.textattr 为不同级别的消息设置不同颜色，在深色背景下形成类似终端的视觉效果：

级别	颜色	含义
title	■ 蓝色	任务开始/结束分隔线
info	■ 浅灰	常规进度信息
success	■ 绿色	附件保存成功
warn	■ 金色	跳过/无附件等警告
error	■ 红色	连接失败、获取错误

遇到的 bug 与修复

1.syntaxerror：中文引号嵌入 f-string

f-string 内使用了中文弯引号 "[周报]"，被 python 解析器当作字符串终止符，导致语法错误。修复：去掉引号，改为 f"符合[周报]格式的邮件：{n} 封"。

2.wxassertionerror：控件被重复加入两个 sizer

chk_only_docx checkbox 先被加入临时的 opt_sizer，又被加入 dir_outer，触发 wxpython c++ 断言。修复：删除冗余的 opt_sizer，只保留 dir_outer 管理该控件。

结果：运行效果与实测

程序最终实现完整运行，核心工作流程如下：

填写配置 → 点击"开始下载"：程序验证输入后，创建 emailworker 后台线程，主界面按钮切换为"停止"状态
ssl 连接 imap.exmail.qq.com:993：使用企业邮箱客户端授权码登录，选择 inbox 收件箱
imap search 按日期区间筛选：仅拉取邮件头，对标题执行正则匹配，收集符合 [周报] 格式的邮件列表
逐封下载附件：进度条实时推进，日志输出每个附件的保存路径（绿色）或跳过原因（金色）
任务完成统计：状态栏显示"共下载 n 个，跳过 m 个，出错 k 个"，可点击"打开目录"直接查看文件

实测结果：连接腾讯企业邮箱（imap.exmail.qq.com:993），在一个月的日期范围内，程序可在 30 秒内完成数十封周报邮件的扫描与附件下载，相比手动操作效率提升约 95%，且无遗漏。

企业邮箱配置要点

通过 dns mx 记录查询确认邮件服务商后，腾讯企业邮箱的正确接入参数为：

参数	值
imap 服务器	imap.exmail.qq.com
端口	993（ssl）
密码	客户端专用授权码（非登录密码）
imap 开关	需在企业邮箱 web 端"客户端设置"中手动开启
收取范围	建议设置"全部"或与目标日期匹配的范围