Python Maildir 怎样创建和枚举邮件子文件夹

Python 处理 Maildir 文件夹时，不要直接把物理目录当成普通目录树遍历。使用 mailbox.Maildir 打开根邮箱，用 add_folder() 创建文件夹，用 list_folders() 枚举当前层级，再用 get_folder() 取得可以继续读写的子邮箱对象。Maildir 的逻辑嵌套通常用点号连接，例如 Projects.2026，而不是在子文件夹里继续套 Maildir。

Python Maildir 的文件夹命名规则

Maildir 根目录本身包含 tmp、new、cur 三个关键子目录。Python 文档把名字以点号开头的同级目录识别为文件夹，例如物理目录 .Projects 对应逻辑名称 Projects。为了表达层级，可以把多个名称用点号连接成 .Projects.2026，Python 返回的文件夹名则是 Projects.2026。

这也是为什么不建议用 os.listdir() 自己拼路径：你还要自行过滤隐藏目录、理解点号前缀，并保证创建出来的目录符合 Maildir 约定。文件夹 API 会把这些命名细节集中起来。

用 add_folder 创建邮件子文件夹

下面的例子创建一个归档文件夹，再创建一个逻辑嵌套文件夹。示例只依赖本地 Maildir，不会连接 SMTP 或 IMAP；调用方只需要把 root_path 换成实际根目录。

from pathlib import Path
import mailbox

root_path = Path("./maildir")
root = mailbox.Maildir(root_path, create=True)

try:
    # 让 API 创建符合 Maildir 约定的文件夹对象。
    archive = root.add_folder("Archive")
    year_folder = root.add_folder("Projects.2026")

    # 返回值仍是 Maildir，可继续用 add() 写入邮件消息。
    print("created:", archive, year_folder)
finally:
    # Maildir 当前不需要锁，但显式 close 便于兼容其他 Mailbox 类型。
    root.close()

add_folder() 的返回值很重要：它是对应文件夹的 Maildir 实例，可以继续调用 add()、keys() 或 list_folders()。创建逻辑嵌套目录时只传入一个带点号的名称，不要先创建 Projects 再把 2026 当成它的物理子目录。

用 list_folders 和 get_folder 枚举目录

读取文件夹时先用 list_folders() 得到根 Maildir 的文件夹名称，再交给 get_folder()。返回列表中的名称已经去掉物理目录的开头点号，因此可以直接保存为同步任务的逻辑标识。

import mailbox

root = mailbox.Maildir("./maildir", create=False)

try:
    # 只枚举当前 Maildir 识别到的文件夹，不把 tmp/new/cur 当文件夹。
    for folder_name in sorted(root.list_folders()):
        try:
            folder = root.get_folder(folder_name)
            print(folder_name, len(folder))
        except mailbox.NoSuchMailboxError:
            # 目录可能被另一个进程刚好移除，跳过这次快照即可。
            continue
finally:
    root.close()

枚举与访问之间存在时间差，所以同步程序不应假设名称永远有效。get_folder() 找不到目标时会抛出 NoSuchMailboxError；捕获它比重新扫描整个磁盘更符合“以当前 Maildir 快照为准”的处理方式。

处理逻辑嵌套、空目录与删除

Maildir 的“子文件夹”更准确地说是根 Maildir 下的文件夹集合。点号只是逻辑层级分隔符，并不代表 Python 会递归进入一个真实的子 Maildir。需要展示层级时，可以在业务层把 Projects.2026 按点号拆分；访问时仍把完整字符串交给 get_folder()。

删除也要先定义业务规则。remove_folder() 只适合删除空文件夹；文件夹中仍有消息时会抛出 mailbox.NotEmptyError，目标不存在则应处理 NoSuchMailboxError。不要为了“强制清理”直接删除物理目录，这会绕过 Maildir 的消息与状态约定。

常见问题

list_folders 为什么看不到 tmp、new、cur？

它们是 Maildir 的消息存储目录，不是 Courier 风格的邮件文件夹；只有点号开头的同级目录才会进入文件夹列表。

Projects.2026 是不是两层真实目录？

不是。它是用点号表示的逻辑嵌套名称，物理上仍属于根 Maildir 下的文件夹。

get_folder 找不到刚创建的目录怎么办？

先使用 add_folder() 返回的对象，或重新调用 list_folders() 获取最新名称；同时捕获 NoSuchMailboxError 应对并发删除。

删除 Maildir 文件夹前必须清空消息吗？

是。remove_folder() 遇到非空文件夹会抛出 NotEmptyError，应先完成归档或逐条删除，再执行文件夹删除。