olm2mbox 0.1.0__tar.gz

olm2mbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Wu
+
+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.

olm2mbox-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: olm2mbox
+Version: 0.1.0
+Summary: Convert Outlook for Mac .olm archives to standard mbox format, with a disk-space-efficient mbox splitter for oversized files.
+Author: Tony Wu
+License: MIT
+Project-URL: Homepage, https://github.com/tonywut/olm2mbox
+Project-URL: Repository, https://github.com/tonywut/olm2mbox
+Project-URL: Issues, https://github.com/tonywut/olm2mbox/issues
+Keywords: olm,mbox,outlook,email,mail,converter,thunderbird,apple-mail
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# olm2mbox
+
+olm2mbox 是一个将 Microsoft Outlook for Mac 的 `.olm` 邮件存档转换为标准 `mbox` 格式的命令行工具，可导入 Thunderbird、Apple Mail 等几乎所有支持 mbox 的邮件客户端或归档工具。
+
+olm2mbox is a command-line tool that converts Microsoft Outlook for Mac `.olm` mail archives into standard `mbox` format, ready to import into Thunderbird, Apple Mail, or any other mbox-compatible mail client or archival tool.
+
+## 缘起 / Backstory
+
+从 Outlook 迁移到 Apple Mail，官方并没有提供直接的一键迁移工具：唯一的路径是先把 Outlook for Mac 的邮箱导出成 `.olm` 存档，再想办法转换成 `mbox` 格式才能导入 Apple Mail。网上能搜到的现成转换工具要么收费不低，要么面对真实的大邮箱（几万封邮件、几十个多级子文件夹、上百 GB 附件）就处理不了——导入导到一半崩溃、中文乱码、子文件夹被漏掉等问题层出不穷。于是干脆让 AI（Claude Code）帮忙把这个工具从头写了出来，自己先拿一个 115GB、8.7万+封邮件的真实邮箱完整跑通、校验无损，现在开源出来，希望能帮到有同样需求的人。
+
+There's no official one-click way to migrate from Outlook to Apple Mail: the only path is exporting your Outlook for Mac mailbox as an `.olm` archive, then somehow converting it to `mbox` so Apple Mail can import it. The existing conversion tools I found online were either expensive or simply couldn't handle a real-world mailbox with tens of thousands of messages, dozens of nested subfolders, and hundreds of gigabytes of attachments — crashing mid-import, mangling CJK text, or silently dropping subfolders. So I had AI (Claude Code) build this tool from scratch instead, ran it end-to-end against my own 115GB, 87,000+ message mailbox, verified it byte-for-byte, and I'm open-sourcing it here in case it helps someone else in the same spot.
+
+## 特性 / Features
+
+- **完整保留嵌套子文件夹结构 / Full nested-subfolder support** — 不只处理收件箱/已发送/草稿等标准文件夹，用户在 Outlook 里自建的多级子文件夹也会被扫描并各自导出为独立的 mbox 文件，镜像原有目录结构。
+- **对脏数据健壮 / Resilient to malformed data** — 自动清理 XML 中的非法控制字符和噪声字符，修复包含换行符的邮件头导致的写入失败，处理地址中混入非 ASCII 字符导致标准库 `formataddr` 崩溃等真实遇到过的边界情况。
+- **中文 / CJK 友好** — 正文使用 8bit 传输编码而非 quoted-printable，避免中文等多字节字符被编码放大近 3 倍，转换前后文件体积基本 1:1。
+- **可续跑 / Resumable** — 超大邮箱转换到一半中断后，可用 `--resume` 跳过已完成的文件夹接着跑。
+- **零依赖 / Zero dependencies** — 只用 Python 标准库，无需安装任何第三方包。
+- **配套拆分工具 / Companion mbox splitter** — 转换后的单个 mbox 文件如果有几十 GB，导入 Apple Mail 等客户端容易直接闪退。`olm2mbox split` 可以把大 mbox 按体积拆成多份，采用"从文件尾部往前搬移 + 截断"的方式而非整份复制，拆分过程中几乎不额外占用磁盘空间，即使剩余空间小于原文件体积也能安全拆分。
+
+已在一个约 115GB、8.7万+封邮件（32个多级文件夹）的真实邮箱存档上完整跑通并校验字节级无损。
+Battle-tested end-to-end and byte-verified against a real ~115GB, 87,000+ message archive spanning 32 nested folders.
+
+## 安装 / Installation
+
+```bash
+git clone https://github.com/tonywut/olm2mbox.git
+cd olm2mbox
+pip install .
+```
+
+需要 Python 3.8+，无第三方依赖。
+Requires Python 3.8+, no third-party dependencies.
+
+## 使用方法 / Usage
+
+### 转换 .olm 为 mbox / Convert .olm to mbox
+
+```bash
+olm2mbox convert path/to/archive.olm path/to/output_dir
+```
+
+每个 OLM 文件夹（含嵌套子文件夹）会在 `output_dir` 下生成对应的 `.mbox` 文件，目录结构与原邮箱一致。
+Each OLM folder (including nested subfolders) becomes a matching `.mbox` file under `output_dir`, mirroring the original folder tree.
+
+常用参数 / Common options:
+
+```bash
+--folder NAME     # 只转换指定的顶层文件夹（原始显示名，如 Inbox）
+                   # only convert this top-level folder (its original display name, e.g. Inbox)
+--limit N          # 每个文件夹最多转换 N 封（用于测试）
+                   # convert at most N messages per folder (for testing)
+--resume           # 跳过已经生成过 .mbox 的文件夹，用于续跑中断的转换
+                   # skip folders whose .mbox already exists, to resume an interrupted run
+--stats-only       # 只扫描统计大小，不实际写出文件
+                   # scan and report sizes without writing any output
+```
+
+### 拆分超大 mbox 文件 / Split an oversized mbox file
+
+```bash
+olm2mbox split path/to/big.mbox --max-bytes 2000000000
+```
+
+会在原文件旁生成 `big_part01.mbox`、`big_part02.mbox` ... 等按时间顺序排列的小文件，原文件在确认每一份都安全写入磁盘后被逐步截断，最终整个替换掉，全程几乎不产生额外磁盘占用。
+This produces `big_part01.mbox`, `big_part02.mbox`, ... in chronological order alongside the source file. The source is progressively truncated as each part is safely flushed to disk, and is fully replaced by the parts at the end — with almost no extra disk usage along the way.
+
+常用参数 / Common options:
+
+```bash
+--max-bytes N   # 每份的最大字节数，默认 2,000,000,000（约2GB）
+                # maximum size per part in bytes, default 2,000,000,000 (~2GB)
+--dry-run        # 只生成拆分文件，不改动（截断/删除）原文件，用于先行校验
+                 # write part files without touching (truncating/deleting) the source
+--out-dir DIR    # 拆分文件的输出目录，默认与原文件同目录
+                 # directory to write part files into, default alongside the source
+```
+
+## 已知限制 / Known limitations
+
+- OLM 数据里正文的"纯文本版本"和"HTML 版本"在实践中几乎总是相同内容；当邮件是 HTML 格式时，纯文本备选版本是对 HTML 做简单去标签处理生成的近似结果，原始 HTML 始终完整保留在 HTML 分支里。
+  OLM rarely exposes a genuinely distinct plain-text body; for HTML messages, the plain-text alternative is a best-effort tag-stripped approximation, while the original HTML is always preserved verbatim.
+- 邮件时间在 OLM 中不带时区信息，统一按 UTC 处理。
+  OLM timestamps carry no timezone info and are treated as UTC.
+
+## 支持 / Support
+
+如果这个工具帮你省了不少事，欢迎请我喝一杯咖啡 ☕️
+
+If this tool saved you some time, feel free to buy me a coffee ☕️
+
+<p>
+  <img src="assets/alipay-qr.jpg" alt="支付宝 Alipay" width="220">
+  <img src="assets/wechat-qr.jpg" alt="微信支付 WeChat Pay" width="220">
+</p>
+
+## 许可证 / License
+
+[MIT](LICENSE)

olm2mbox-0.1.0/README.md

@@ -0,0 +1,100 @@
+# olm2mbox
+
+olm2mbox 是一个将 Microsoft Outlook for Mac 的 `.olm` 邮件存档转换为标准 `mbox` 格式的命令行工具，可导入 Thunderbird、Apple Mail 等几乎所有支持 mbox 的邮件客户端或归档工具。
+
+olm2mbox is a command-line tool that converts Microsoft Outlook for Mac `.olm` mail archives into standard `mbox` format, ready to import into Thunderbird, Apple Mail, or any other mbox-compatible mail client or archival tool.
+
+## 缘起 / Backstory
+
+从 Outlook 迁移到 Apple Mail，官方并没有提供直接的一键迁移工具：唯一的路径是先把 Outlook for Mac 的邮箱导出成 `.olm` 存档，再想办法转换成 `mbox` 格式才能导入 Apple Mail。网上能搜到的现成转换工具要么收费不低，要么面对真实的大邮箱（几万封邮件、几十个多级子文件夹、上百 GB 附件）就处理不了——导入导到一半崩溃、中文乱码、子文件夹被漏掉等问题层出不穷。于是干脆让 AI（Claude Code）帮忙把这个工具从头写了出来，自己先拿一个 115GB、8.7万+封邮件的真实邮箱完整跑通、校验无损，现在开源出来，希望能帮到有同样需求的人。
+
+There's no official one-click way to migrate from Outlook to Apple Mail: the only path is exporting your Outlook for Mac mailbox as an `.olm` archive, then somehow converting it to `mbox` so Apple Mail can import it. The existing conversion tools I found online were either expensive or simply couldn't handle a real-world mailbox with tens of thousands of messages, dozens of nested subfolders, and hundreds of gigabytes of attachments — crashing mid-import, mangling CJK text, or silently dropping subfolders. So I had AI (Claude Code) build this tool from scratch instead, ran it end-to-end against my own 115GB, 87,000+ message mailbox, verified it byte-for-byte, and I'm open-sourcing it here in case it helps someone else in the same spot.
+
+## 特性 / Features
+
+- **完整保留嵌套子文件夹结构 / Full nested-subfolder support** — 不只处理收件箱/已发送/草稿等标准文件夹，用户在 Outlook 里自建的多级子文件夹也会被扫描并各自导出为独立的 mbox 文件，镜像原有目录结构。
+- **对脏数据健壮 / Resilient to malformed data** — 自动清理 XML 中的非法控制字符和噪声字符，修复包含换行符的邮件头导致的写入失败，处理地址中混入非 ASCII 字符导致标准库 `formataddr` 崩溃等真实遇到过的边界情况。
+- **中文 / CJK 友好** — 正文使用 8bit 传输编码而非 quoted-printable，避免中文等多字节字符被编码放大近 3 倍，转换前后文件体积基本 1:1。
+- **可续跑 / Resumable** — 超大邮箱转换到一半中断后，可用 `--resume` 跳过已完成的文件夹接着跑。
+- **零依赖 / Zero dependencies** — 只用 Python 标准库，无需安装任何第三方包。
+- **配套拆分工具 / Companion mbox splitter** — 转换后的单个 mbox 文件如果有几十 GB，导入 Apple Mail 等客户端容易直接闪退。`olm2mbox split` 可以把大 mbox 按体积拆成多份，采用"从文件尾部往前搬移 + 截断"的方式而非整份复制，拆分过程中几乎不额外占用磁盘空间，即使剩余空间小于原文件体积也能安全拆分。
+
+已在一个约 115GB、8.7万+封邮件（32个多级文件夹）的真实邮箱存档上完整跑通并校验字节级无损。
+Battle-tested end-to-end and byte-verified against a real ~115GB, 87,000+ message archive spanning 32 nested folders.
+
+## 安装 / Installation
+
+```bash
+git clone https://github.com/tonywut/olm2mbox.git
+cd olm2mbox
+pip install .
+```
+
+需要 Python 3.8+，无第三方依赖。
+Requires Python 3.8+, no third-party dependencies.
+
+## 使用方法 / Usage
+
+### 转换 .olm 为 mbox / Convert .olm to mbox
+
+```bash
+olm2mbox convert path/to/archive.olm path/to/output_dir
+```
+
+每个 OLM 文件夹（含嵌套子文件夹）会在 `output_dir` 下生成对应的 `.mbox` 文件，目录结构与原邮箱一致。
+Each OLM folder (including nested subfolders) becomes a matching `.mbox` file under `output_dir`, mirroring the original folder tree.
+
+常用参数 / Common options:
+
+```bash
+--folder NAME     # 只转换指定的顶层文件夹（原始显示名，如 Inbox）
+                   # only convert this top-level folder (its original display name, e.g. Inbox)
+--limit N          # 每个文件夹最多转换 N 封（用于测试）
+                   # convert at most N messages per folder (for testing)
+--resume           # 跳过已经生成过 .mbox 的文件夹，用于续跑中断的转换
+                   # skip folders whose .mbox already exists, to resume an interrupted run
+--stats-only       # 只扫描统计大小，不实际写出文件
+                   # scan and report sizes without writing any output
+```
+
+### 拆分超大 mbox 文件 / Split an oversized mbox file
+
+```bash
+olm2mbox split path/to/big.mbox --max-bytes 2000000000
+```
+
+会在原文件旁生成 `big_part01.mbox`、`big_part02.mbox` ... 等按时间顺序排列的小文件，原文件在确认每一份都安全写入磁盘后被逐步截断，最终整个替换掉，全程几乎不产生额外磁盘占用。
+This produces `big_part01.mbox`, `big_part02.mbox`, ... in chronological order alongside the source file. The source is progressively truncated as each part is safely flushed to disk, and is fully replaced by the parts at the end — with almost no extra disk usage along the way.
+
+常用参数 / Common options:
+
+```bash
+--max-bytes N   # 每份的最大字节数，默认 2,000,000,000（约2GB）
+                # maximum size per part in bytes, default 2,000,000,000 (~2GB)
+--dry-run        # 只生成拆分文件，不改动（截断/删除）原文件，用于先行校验
+                 # write part files without touching (truncating/deleting) the source
+--out-dir DIR    # 拆分文件的输出目录，默认与原文件同目录
+                 # directory to write part files into, default alongside the source
+```
+
+## 已知限制 / Known limitations
+
+- OLM 数据里正文的"纯文本版本"和"HTML 版本"在实践中几乎总是相同内容；当邮件是 HTML 格式时，纯文本备选版本是对 HTML 做简单去标签处理生成的近似结果，原始 HTML 始终完整保留在 HTML 分支里。
+  OLM rarely exposes a genuinely distinct plain-text body; for HTML messages, the plain-text alternative is a best-effort tag-stripped approximation, while the original HTML is always preserved verbatim.
+- 邮件时间在 OLM 中不带时区信息，统一按 UTC 处理。
+  OLM timestamps carry no timezone info and are treated as UTC.
+
+## 支持 / Support
+
+如果这个工具帮你省了不少事，欢迎请我喝一杯咖啡 ☕️
+
+If this tool saved you some time, feel free to buy me a coffee ☕️
+
+<p>
+  <img src="assets/alipay-qr.jpg" alt="支付宝 Alipay" width="220">
+  <img src="assets/wechat-qr.jpg" alt="微信支付 WeChat Pay" width="220">
+</p>
+
+## 许可证 / License
+
+[MIT](LICENSE)

olm2mbox-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "olm2mbox"
+version = "0.1.0"
+description = "Convert Outlook for Mac .olm archives to standard mbox format, with a disk-space-efficient mbox splitter for oversized files."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Tony Wu" }]
+keywords = ["olm", "mbox", "outlook", "email", "mail", "converter", "thunderbird", "apple-mail"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Communications :: Email",
+    "Topic :: Utilities",
+    "Environment :: Console",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/tonywut/olm2mbox"
+Repository = "https://github.com/tonywut/olm2mbox"
+Issues = "https://github.com/tonywut/olm2mbox/issues"
+
+[project.scripts]
+olm2mbox = "olm2mbox.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

olm2mbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

olm2mbox-0.1.0/src/olm2mbox/__init__.py

@@ -0,0 +1,7 @@
+"""olm2mbox: convert Outlook for Mac .olm archives to mbox, and split oversized mbox files."""
+
+from .convert import convert
+from .split import split
+
+__version__ = "0.1.0"
+__all__ = ["convert", "split", "__version__"]

olm2mbox-0.1.0/src/olm2mbox/cli.py

@@ -0,0 +1,83 @@
+"""Command-line interface for olm2mbox."""
+import argparse
+import sys
+
+from . import __version__
+from .convert import convert
+from .split import split
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog='olm2mbox',
+        description='Convert Outlook for Mac .olm archives to mbox, and split oversized mbox files.',
+    )
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+    sub = parser.add_subparsers(dest='command', required=True)
+
+    p_convert = sub.add_parser(
+        'convert',
+        help='Convert an .olm archive to one mbox file per folder',
+        description='Convert an .olm archive to one mbox file per folder, mirroring the original folder tree.',
+    )
+    p_convert.add_argument('input', help='Path to the source .olm file')
+    p_convert.add_argument('output_dir', help='Directory to write the .mbox files into')
+    p_convert.add_argument(
+        '--folder', default=None,
+        help="Only convert this top-level OLM folder (matches the folder's original display name, e.g. Inbox)",
+    )
+    p_convert.add_argument(
+        '--limit', type=int, default=None,
+        help='Convert at most N messages per folder (useful for testing)',
+    )
+    p_convert.add_argument(
+        '--stats-only', action='store_true',
+        help='Scan and report sizes without writing any output',
+    )
+    p_convert.add_argument(
+        '--resume', action='store_true',
+        help='Skip folders whose output .mbox file already exists, to continue an interrupted run',
+    )
+
+    p_split = sub.add_parser(
+        'split',
+        help='Split an oversized mbox file into size-capped parts',
+        description='Split an oversized mbox file into size-capped parts, without needing extra disk space for a full copy.',
+    )
+    p_split.add_argument('source', help='Path to the mbox file to split')
+    p_split.add_argument(
+        '--max-bytes', type=int, default=2_000_000_000,
+        help='Maximum size per part, in bytes (default: 2,000,000,000, about 2 GB)',
+    )
+    p_split.add_argument(
+        '--dry-run', action='store_true',
+        help='Write part files without touching (truncating or deleting) the source',
+    )
+    p_split.add_argument(
+        '--out-dir', default=None,
+        help='Directory to write part files into (default: alongside the source file)',
+    )
+
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == 'convert':
+        convert(
+            args.input, args.output_dir,
+            only_folder=args.folder, limit=args.limit,
+            stats_only=args.stats_only, resume=args.resume,
+        )
+    elif args.command == 'split':
+        split(
+            args.source, args.max_bytes,
+            dry_run=args.dry_run, out_dir=args.out_dir,
+        )
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

olm2mbox-0.1.0/src/olm2mbox/convert.py

@@ -0,0 +1,348 @@
+"""Convert a Microsoft Outlook for Mac .olm archive to standard mbox file(s).
+
+An .olm file is a zip archive containing one XML file per message
+(message_NNNNN.xml) plus a sibling directory of raw attachment files, laid
+out per mail folder. This module walks every folder in the archive -
+including user-created subfolders nested arbitrarily deep under the standard
+Inbox/Sent/Drafts/etc. folders - and writes one standard mbox file per
+folder, mirroring the original folder tree under the given output directory.
+
+Design notes
+------------
+* Message bodies are attached with Content-Transfer-Encoding "8bit" rather
+  than the email package's default "quoted-printable". For CJK-heavy text,
+  quoted-printable roughly triples the encoded size (each multi-byte UTF-8
+  character becomes a string of "=XX" escapes); 8bit keeps output size close
+  to 1:1 with input size.
+* OLM data is occasionally malformed in ways that trip up the standard
+  library: raw control characters or noncharacters (U+FFFE/U+FFFF) that
+  break XML well-formedness, header values containing embedded newlines
+  (rejected by EmailMessage's header assignment), and non-ASCII characters
+  in the address part of a From/To/Cc field (which makes
+  email.utils.formataddr raise). All three are sanitized/worked around here.
+* FOLDER_MAP renames a handful of well-known localized default folder names
+  (as produced by a Chinese-localized Outlook) to their canonical English
+  equivalents purely for nicer output filenames. Any folder name not in the
+  map - including default folders in other languages - passes through
+  unchanged.
+"""
+import sys
+import os
+import re
+import time
+import html as htmllib
+import zipfile
+import xml.etree.ElementTree as ET
+from email.message import EmailMessage
+from email import policy
+from email.utils import format_datetime
+import datetime
+
+TAG_RE = re.compile(r'<[^>]+>')
+HEADER_UNSAFE_RE = re.compile(r'[\r\n]+')
+# XML 1.0 disallows most C0 control chars and the U+FFFE/U+FFFF
+# noncharacters; strip anything not in the allowed set before parsing, since
+# some OLM message bodies embed raw control bytes or the odd noncharacter
+# that break well-formedness.
+XML_INVALID_RE = re.compile(
+    '[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff￾￿]'
+)
+ADDR_SPECIALS_RE = re.compile(r'[",()<>@:;\\\[\]]')
+
+# Cosmetic only: rename a few well-known localized default folder names to
+# their canonical English equivalents. Anything not listed here passes
+# through unchanged (see module docstring).
+FOLDER_MAP = {
+    '收件箱': 'Inbox',
+    '发件箱': 'Outbox',
+    '已发送邮件': 'Sent',
+    '草稿': 'Drafts',
+    '已删除邮件': 'Deleted',
+    '垃圾邮件': 'Junk',
+}
+
+# Fixed internal path prefix used by Microsoft's OLM exporter, independent of
+# Outlook's UI language.
+PREFIX = 'Local/com.microsoft.__Messages/'
+
+
+def clean_header(s):
+    """Collapse embedded CR/LF in a header value to a single space.
+
+    EmailMessage's header assignment raises on values containing newlines;
+    OLM data sometimes has them (e.g. a Subject copy-pasted from elsewhere).
+    """
+    if not s:
+        return s
+    return HEADER_UNSAFE_RE.sub(' ', s).strip()
+
+
+def sanitize_xml(raw_bytes):
+    """Strip characters that are not legal in XML 1.0 content."""
+    text = raw_bytes.decode('utf-8', errors='replace')
+    return XML_INVALID_RE.sub('', text).encode('utf-8')
+
+
+def strip_html_to_text(htmltext):
+    """Very small HTML->text fallback, used when no distinct plain-text body exists."""
+    text = TAG_RE.sub(' ', htmltext)
+    text = htmllib.unescape(text)
+    text = re.sub(r'[ \t]+', ' ', text)
+    text = re.sub(r'\n\s*\n+', '\n\n', text)
+    return text.strip()
+
+
+def parse_olm_datetime(s):
+    if not s:
+        return None
+    try:
+        # OLM stores e.g. "2026-05-27T03:12:52" (naive, assumed UTC).
+        dt = datetime.datetime.strptime(s.strip(), '%Y-%m-%dT%H:%M:%S')
+        return dt.replace(tzinfo=datetime.timezone.utc)
+    except ValueError:
+        return None
+
+
+def addr_list(el):
+    out = []
+    if el is None:
+        return out
+    for a in el.findall('emailAddress'):
+        addr = clean_header(a.get('OPFContactEmailAddressAddress') or '')
+        name = clean_header(a.get('OPFContactEmailAddressName') or '')
+        if not addr:
+            continue
+        if name and name != addr:
+            out.append((name, addr))
+        else:
+            out.append((None, addr))
+    return out
+
+
+def format_one_addr(name, addr):
+    # Avoid email.utils.formataddr: it hard-fails (UnicodeEncodeError) on a
+    # non-ASCII addr-spec, which OLM data sometimes contains. Build manually
+    # instead and let the email policy's header registry RFC 2047-encode
+    # whatever needs it at serialization time.
+    if name:
+        if ADDR_SPECIALS_RE.search(name):
+            name = '"' + name.replace('\\', '\\\\').replace('"', '\\"') + '"'
+        return f'{name} <{addr}>'
+    return addr
+
+
+def format_addrs(pairs):
+    return ', '.join(format_one_addr(name, addr) for name, addr in pairs)
+
+
+def text_of(root, tag):
+    el = root.find(tag)
+    if el is None or el.text is None:
+        return ''
+    return el.text
+
+
+def truthy_flag(root, tag):
+    el = root.find(tag)
+    if el is None or el.text is None:
+        return False
+    try:
+        return float(el.text) != 0
+    except ValueError:
+        return el.text.strip() not in ('', '0')
+
+
+def build_message(zf, email_el, folder_path):
+    """Build an EmailMessage from one OLM <email> element."""
+    subject = clean_header(text_of(email_el, 'OPFMessageCopySubject'))
+    message_id = clean_header(text_of(email_el, 'OPFMessageCopyMessageID').strip())
+    sent_time = parse_olm_datetime(text_of(email_el, 'OPFMessageCopySentTime'))
+    received_time = parse_olm_datetime(text_of(email_el, 'OPFMessageCopyReceivedTime'))
+    dt = sent_time or received_time or datetime.datetime.now(datetime.timezone.utc)
+
+    from_addrs = addr_list(email_el.find('OPFMessageCopyFromAddresses'))
+    to_addrs = addr_list(email_el.find('OPFMessageCopyToAddresses'))
+    cc_addrs = addr_list(email_el.find('OPFMessageCopyCCAddresses'))
+    reply_to_addrs = addr_list(email_el.find('OPFMessageCopyReplyToAddresses'))
+
+    has_html = truthy_flag(email_el, 'OPFMessageGetHasHTML')
+    body_raw = text_of(email_el, 'OPFMessageCopyBody')
+
+    msg = EmailMessage(policy=policy.default)
+    if subject:
+        msg['Subject'] = subject
+    if from_addrs:
+        msg['From'] = format_addrs(from_addrs)
+    if to_addrs:
+        msg['To'] = format_addrs(to_addrs)
+    if cc_addrs:
+        msg['Cc'] = format_addrs(cc_addrs)
+    if reply_to_addrs:
+        msg['Reply-To'] = format_addrs(reply_to_addrs)
+    msg['Date'] = format_datetime(dt)
+    if message_id:
+        mid = message_id if message_id.startswith('<') else f'<{message_id}>'
+        msg['Message-ID'] = mid
+    in_reply_to = clean_header(text_of(email_el, 'OPFMessageCopyInReplyTo').strip())
+    if in_reply_to:
+        msg['In-Reply-To'] = in_reply_to if in_reply_to.startswith('<') else f'<{in_reply_to}>'
+    references = clean_header(text_of(email_el, 'OPFMessageCopyReferences').strip())
+    if references:
+        msg['References'] = references
+    msg['X-OLM-Source-Folder'] = folder_path
+
+    if has_html and body_raw:
+        # OLM does not reliably expose a distinct plain-text body, so the
+        # "plain" alternative is a best-effort tag-strip of the HTML rather
+        # than a source-accurate plain-text version. The original HTML is
+        # always preserved verbatim in the html alternative.
+        plain_fallback = strip_html_to_text(body_raw) or ' '
+        msg.set_content(plain_fallback, cte='8bit')
+        msg.add_alternative(body_raw, subtype='html', cte='8bit')
+    else:
+        msg.set_content(body_raw or ' ', cte='8bit')
+
+    attach_list_el = email_el.find('OPFMessageCopyAttachmentList')
+    if attach_list_el is not None:
+        for att in attach_list_el.findall('messageAttachment'):
+            url = att.get('OPFAttachmentURL')
+            if not url:
+                continue
+            ctype = att.get('OPFAttachmentContentType') or 'application/octet-stream'
+            if '/' in ctype:
+                maintype, subtype = ctype.split('/', 1)
+            else:
+                maintype, subtype = 'application', 'octet-stream'
+            name = clean_header(att.get('OPFAttachmentName') or os.path.basename(url))
+            cid = clean_header(att.get('OPFAttachmentContentID') or '')
+            try:
+                data = zf.read(url)
+            except KeyError:
+                continue
+            kwargs = dict(maintype=maintype, subtype=subtype, filename=name)
+            if cid:
+                kwargs['cid'] = f'<{cid}>' if not cid.startswith('<') else cid
+            try:
+                msg.add_attachment(data, **kwargs)
+            except Exception:
+                msg.add_attachment(data, maintype='application', subtype='octet-stream', filename=name)
+
+    return msg, dt
+
+
+def mbox_from_line(from_addr, dt):
+    ts = dt.astimezone(datetime.timezone.utc).strftime('%a %b %d %H:%M:%S %Y')
+    addr = from_addr if from_addr else 'MAILER-DAEMON'
+    return f'From {addr} {ts}\n'
+
+
+def escape_mbox_body(raw_bytes):
+    # mboxrd style: escape any line starting with "From " (or ">" + "From ") by prefixing '>'.
+    return re.sub(rb'(?m)^(>*From )', rb'>\1', raw_bytes)
+
+
+def iter_folder_messages(zf, folder_path):
+    names = sorted(
+        n for n in zf.namelist()
+        if n.startswith(folder_path + '/message_') and n.endswith('.xml')
+    )
+    for n in names:
+        yield n
+
+
+def discover_message_dirs(zf):
+    """Find every directory (at any depth) that directly contains message_*.xml files.
+
+    OLM mailboxes commonly have user-created subfolders nested under the
+    standard top-level folders (e.g. Inbox/ProjectX/message_0000.xml), and
+    those would otherwise be silently skipped if only the standard folders
+    were scanned.
+    """
+    dirs = set()
+    for n in zf.namelist():
+        if n.endswith('.xml') and '/message_' in n:
+            d = n.rsplit('/message_', 1)[0]
+            if d.startswith(PREFIX):
+                dirs.add(d)
+    return dirs
+
+
+def out_path_for_dir(output_dir, folder_path):
+    rel = folder_path[len(PREFIX):]
+    parts = rel.split('/')
+    parts[0] = FOLDER_MAP.get(parts[0], parts[0])
+    out_dir = os.path.join(output_dir, *parts[:-1]) if len(parts) > 1 else output_dir
+    return os.path.join(out_dir, f'{parts[-1]}.mbox'), '/'.join(parts)
+
+
+def convert(input_path, output_dir, only_folder=None, limit=None, stats_only=False, resume=False):
+    """Convert every folder in the .olm archive at input_path into a matching
+    mbox file tree under output_dir.
+
+    :param only_folder: if set, only convert the top-level OLM folder with
+        this exact display name (e.g. "Inbox" or a localized name).
+    :param limit: convert at most this many messages per folder (for testing).
+    :param stats_only: scan and report sizes without writing any output.
+    :param resume: skip folders whose output .mbox file already exists,
+        letting an interrupted run be continued without redoing completed
+        folders.
+    :returns: dict of {folder_name: {count, errors, bytes, seconds}}.
+    """
+    os.makedirs(output_dir, exist_ok=True)
+    zf = zipfile.ZipFile(input_path)
+    folders = discover_message_dirs(zf)
+
+    total_stats = {}
+    for folder_path in sorted(folders):
+        top_folder_name = folder_path[len(PREFIX):].split('/', 1)[0]
+        if only_folder and top_folder_name != only_folder:
+            continue
+        out_path, out_name = out_path_for_dir(output_dir, folder_path)
+        if resume and os.path.exists(out_path):
+            print(f'-- skipping {out_name} (already done, {os.path.getsize(out_path)/1e9:.2f} GB)', flush=True)
+            continue
+        os.makedirs(os.path.dirname(out_path), exist_ok=True)
+        count = 0
+        errors = 0
+        t0 = time.time()
+        out_f = None if stats_only else open(out_path, 'wb')
+        bytes_written = 0
+        try:
+            for n in iter_folder_messages(zf, folder_path):
+                if limit and count >= limit:
+                    break
+                try:
+                    raw_xml = sanitize_xml(zf.read(n))
+                    root = ET.fromstring(raw_xml)
+                    email_el = root.find('email')
+                    if email_el is None:
+                        errors += 1
+                        continue
+                    msg, dt = build_message(zf, email_el, folder_path)
+                    from_hdr = msg.get('From', '')
+                    m = re.search(r'[\w.+-]+@[\w.-]+', from_hdr)
+                    from_addr = m.group(0) if m else ''
+                    payload_bytes = msg.as_bytes()
+                    if out_f is not None:
+                        fl = mbox_from_line(from_addr, dt).encode('utf-8')
+                        body = escape_mbox_body(payload_bytes)
+                        if not body.endswith(b'\n'):
+                            body += b'\n'
+                        out_f.write(fl)
+                        out_f.write(body)
+                        out_f.write(b'\n')
+                        bytes_written += len(fl) + len(body) + 1
+                except Exception as e:
+                    errors += 1
+                    print(f'  ! error on {n}: {e}', file=sys.stderr)
+                count += 1
+                if count % 2000 == 0:
+                    elapsed = time.time() - t0
+                    print(f'  [{out_name}] {count} messages, {bytes_written/1e9:.2f} GB, {elapsed:.0f}s elapsed', flush=True)
+        finally:
+            if out_f is not None:
+                out_f.close()
+        elapsed = time.time() - t0
+        total_stats[out_name] = dict(count=count, errors=errors, bytes=bytes_written, seconds=elapsed)
+        print(f'== {out_name}: {count} messages, {errors} errors, {bytes_written/1e9:.2f} GB, {elapsed:.1f}s', flush=True)
+    return total_stats

olm2mbox-0.1.0/src/olm2mbox/split.py

@@ -0,0 +1,138 @@
+"""Split an oversized mbox file into size-capped parts without needing 2x disk space.
+
+A single multi-gigabyte mbox file is a common cause of mail clients (Apple
+Mail in particular) crashing on import. The straightforward way to split one
+- read the whole file and write out N smaller files - needs as much free
+disk space as the original file's size, on top of the original itself. That
+is often not available for a mailbox archive large enough to need splitting
+in the first place.
+
+This module avoids that by carving chunks off the *end* of the source file
+first: write the last chunk's bytes to a new part file, fsync it, then
+os.truncate() the source down to the start of that chunk. Because truncate
+only needs to shrink a file (no rewrite of the remaining data), peak extra
+disk usage is about one chunk's size, not the whole file. Repeating this
+from the last chunk back to the first "moves" the data out of the source
+into the part files, leaving an empty source file that is removed at the
+end.
+
+Message boundaries are found by scanning for lines that start a new mbox
+"From " envelope, so no message is ever split across two part files.
+"""
+import os
+import re
+import argparse
+
+FROM_LINE_RE = re.compile(rb'From [^\r\n]*\d{4}\r?\n')
+SCAN_BLOCK = 64 * 1024 * 1024
+OVERLAP = 4096
+
+
+def find_message_offsets(path):
+    """Return the sorted list of byte offsets where a message ("From ") begins."""
+    offsets = [0]
+    size = os.path.getsize(path)
+    with open(path, 'rb') as f:
+        pos = 0
+        carry = b''
+        while pos < size:
+            f.seek(pos)
+            block = f.read(SCAN_BLOCK)
+            if not block:
+                break
+            search_area = carry + block
+            base = pos - len(carry)
+            # Find every "\nFrom " boundary in this window.
+            idx = 0
+            while True:
+                i = search_area.find(b'\nFrom ', idx)
+                if i == -1:
+                    break
+                start = base + i + 1
+                # Confirm it looks like a real envelope line (From <addr> ... <year>).
+                line_end = search_area.find(b'\n', i + 1)
+                if line_end == -1:
+                    line = search_area[i + 1:i + 1 + 200]
+                else:
+                    line = search_area[i + 1:line_end + 1]
+                if FROM_LINE_RE.match(line):
+                    offsets.append(start)
+                idx = i + 1
+            carry = search_area[-OVERLAP:] if len(search_area) >= OVERLAP else search_area
+            pos += len(block)
+    offsets = sorted(set(offsets))
+    return offsets, size
+
+
+def build_chunks(offsets, size, max_bytes):
+    chunks = []  # list of (start, end)
+    chunk_start = offsets[0]
+    prev = offsets[0]
+    for off in offsets[1:] + [size]:
+        if off - chunk_start > max_bytes and prev != chunk_start:
+            chunks.append((chunk_start, prev))
+            chunk_start = prev
+        prev = off
+    chunks.append((chunk_start, size))
+    return chunks
+
+
+def part_name(base_path, idx, total):
+    root, ext = os.path.splitext(base_path)
+    width = max(2, len(str(total)))
+    return f'{root}_part{str(idx).zfill(width)}{ext}'
+
+
+def split(source, max_bytes, dry_run=False, out_dir=None):
+    """Split source into <= max_bytes parts, numbered oldest-first.
+
+    :param dry_run: write part files but do not touch (truncate/delete) the
+        source, for verification before committing to the destructive path.
+    :param out_dir: directory to write part files into; defaults to
+        alongside the source file.
+    :returns: (part_paths, offsets, size)
+    """
+    print(f'scanning {source} for message boundaries...', flush=True)
+    offsets, size = find_message_offsets(source)
+    print(f'found {len(offsets)} messages, {size/1e9:.2f} GB total', flush=True)
+    chunks = build_chunks(offsets, size, max_bytes)
+    print(f'planned {len(chunks)} parts', flush=True)
+
+    total = len(chunks)
+    part_paths = []
+    for i, (start, end) in enumerate(chunks, 1):
+        if out_dir:
+            base = os.path.join(out_dir, os.path.basename(source))
+        else:
+            base = source
+        part_paths.append(part_name(base, i, total))
+
+    # Process chunks from LAST to FIRST so the source can be truncated after
+    # each part is safely written, keeping peak extra disk usage to ~one chunk.
+    with open(source, 'r+b' if not dry_run else 'rb') as src:
+        for i in range(len(chunks) - 1, -1, -1):
+            start, end = chunks[i]
+            out_path = part_paths[i]
+            length = end - start
+            print(f'  part {i+1}/{total}: bytes [{start},{end}) -> {out_path} ({length/1e9:.2f} GB)', flush=True)
+            src.seek(start)
+            remaining = length
+            with open(out_path, 'wb') as outf:
+                while remaining > 0:
+                    buf = src.read(min(SCAN_BLOCK, remaining))
+                    if not buf:
+                        break
+                    outf.write(buf)
+                    remaining -= len(buf)
+                outf.flush()
+                os.fsync(outf.fileno())
+            if not dry_run:
+                src.flush()
+                os.truncate(source, start)
+                print(f'    truncated source to {start/1e9:.2f} GB', flush=True)
+
+    if not dry_run:
+        os.remove(source)
+        print(f'removed emptied source {source}', flush=True)
+
+    return part_paths, offsets, size

olm2mbox-0.1.0/src/olm2mbox.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: olm2mbox
+Version: 0.1.0
+Summary: Convert Outlook for Mac .olm archives to standard mbox format, with a disk-space-efficient mbox splitter for oversized files.
+Author: Tony Wu
+License: MIT
+Project-URL: Homepage, https://github.com/tonywut/olm2mbox
+Project-URL: Repository, https://github.com/tonywut/olm2mbox
+Project-URL: Issues, https://github.com/tonywut/olm2mbox/issues
+Keywords: olm,mbox,outlook,email,mail,converter,thunderbird,apple-mail
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# olm2mbox
+
+olm2mbox 是一个将 Microsoft Outlook for Mac 的 `.olm` 邮件存档转换为标准 `mbox` 格式的命令行工具，可导入 Thunderbird、Apple Mail 等几乎所有支持 mbox 的邮件客户端或归档工具。
+
+olm2mbox is a command-line tool that converts Microsoft Outlook for Mac `.olm` mail archives into standard `mbox` format, ready to import into Thunderbird, Apple Mail, or any other mbox-compatible mail client or archival tool.
+
+## 缘起 / Backstory
+
+从 Outlook 迁移到 Apple Mail，官方并没有提供直接的一键迁移工具：唯一的路径是先把 Outlook for Mac 的邮箱导出成 `.olm` 存档，再想办法转换成 `mbox` 格式才能导入 Apple Mail。网上能搜到的现成转换工具要么收费不低，要么面对真实的大邮箱（几万封邮件、几十个多级子文件夹、上百 GB 附件）就处理不了——导入导到一半崩溃、中文乱码、子文件夹被漏掉等问题层出不穷。于是干脆让 AI（Claude Code）帮忙把这个工具从头写了出来，自己先拿一个 115GB、8.7万+封邮件的真实邮箱完整跑通、校验无损，现在开源出来，希望能帮到有同样需求的人。
+
+There's no official one-click way to migrate from Outlook to Apple Mail: the only path is exporting your Outlook for Mac mailbox as an `.olm` archive, then somehow converting it to `mbox` so Apple Mail can import it. The existing conversion tools I found online were either expensive or simply couldn't handle a real-world mailbox with tens of thousands of messages, dozens of nested subfolders, and hundreds of gigabytes of attachments — crashing mid-import, mangling CJK text, or silently dropping subfolders. So I had AI (Claude Code) build this tool from scratch instead, ran it end-to-end against my own 115GB, 87,000+ message mailbox, verified it byte-for-byte, and I'm open-sourcing it here in case it helps someone else in the same spot.
+
+## 特性 / Features
+
+- **完整保留嵌套子文件夹结构 / Full nested-subfolder support** — 不只处理收件箱/已发送/草稿等标准文件夹，用户在 Outlook 里自建的多级子文件夹也会被扫描并各自导出为独立的 mbox 文件，镜像原有目录结构。
+- **对脏数据健壮 / Resilient to malformed data** — 自动清理 XML 中的非法控制字符和噪声字符，修复包含换行符的邮件头导致的写入失败，处理地址中混入非 ASCII 字符导致标准库 `formataddr` 崩溃等真实遇到过的边界情况。
+- **中文 / CJK 友好** — 正文使用 8bit 传输编码而非 quoted-printable，避免中文等多字节字符被编码放大近 3 倍，转换前后文件体积基本 1:1。
+- **可续跑 / Resumable** — 超大邮箱转换到一半中断后，可用 `--resume` 跳过已完成的文件夹接着跑。
+- **零依赖 / Zero dependencies** — 只用 Python 标准库，无需安装任何第三方包。
+- **配套拆分工具 / Companion mbox splitter** — 转换后的单个 mbox 文件如果有几十 GB，导入 Apple Mail 等客户端容易直接闪退。`olm2mbox split` 可以把大 mbox 按体积拆成多份，采用"从文件尾部往前搬移 + 截断"的方式而非整份复制，拆分过程中几乎不额外占用磁盘空间，即使剩余空间小于原文件体积也能安全拆分。
+
+已在一个约 115GB、8.7万+封邮件（32个多级文件夹）的真实邮箱存档上完整跑通并校验字节级无损。
+Battle-tested end-to-end and byte-verified against a real ~115GB, 87,000+ message archive spanning 32 nested folders.
+
+## 安装 / Installation
+
+```bash
+git clone https://github.com/tonywut/olm2mbox.git
+cd olm2mbox
+pip install .
+```
+
+需要 Python 3.8+，无第三方依赖。
+Requires Python 3.8+, no third-party dependencies.
+
+## 使用方法 / Usage
+
+### 转换 .olm 为 mbox / Convert .olm to mbox
+
+```bash
+olm2mbox convert path/to/archive.olm path/to/output_dir
+```
+
+每个 OLM 文件夹（含嵌套子文件夹）会在 `output_dir` 下生成对应的 `.mbox` 文件，目录结构与原邮箱一致。
+Each OLM folder (including nested subfolders) becomes a matching `.mbox` file under `output_dir`, mirroring the original folder tree.
+
+常用参数 / Common options:
+
+```bash
+--folder NAME     # 只转换指定的顶层文件夹（原始显示名，如 Inbox）
+                   # only convert this top-level folder (its original display name, e.g. Inbox)
+--limit N          # 每个文件夹最多转换 N 封（用于测试）
+                   # convert at most N messages per folder (for testing)
+--resume           # 跳过已经生成过 .mbox 的文件夹，用于续跑中断的转换
+                   # skip folders whose .mbox already exists, to resume an interrupted run
+--stats-only       # 只扫描统计大小，不实际写出文件
+                   # scan and report sizes without writing any output
+```
+
+### 拆分超大 mbox 文件 / Split an oversized mbox file
+
+```bash
+olm2mbox split path/to/big.mbox --max-bytes 2000000000
+```
+
+会在原文件旁生成 `big_part01.mbox`、`big_part02.mbox` ... 等按时间顺序排列的小文件，原文件在确认每一份都安全写入磁盘后被逐步截断，最终整个替换掉，全程几乎不产生额外磁盘占用。
+This produces `big_part01.mbox`, `big_part02.mbox`, ... in chronological order alongside the source file. The source is progressively truncated as each part is safely flushed to disk, and is fully replaced by the parts at the end — with almost no extra disk usage along the way.
+
+常用参数 / Common options:
+
+```bash
+--max-bytes N   # 每份的最大字节数，默认 2,000,000,000（约2GB）
+                # maximum size per part in bytes, default 2,000,000,000 (~2GB)
+--dry-run        # 只生成拆分文件，不改动（截断/删除）原文件，用于先行校验
+                 # write part files without touching (truncating/deleting) the source
+--out-dir DIR    # 拆分文件的输出目录，默认与原文件同目录
+                 # directory to write part files into, default alongside the source
+```
+
+## 已知限制 / Known limitations
+
+- OLM 数据里正文的"纯文本版本"和"HTML 版本"在实践中几乎总是相同内容；当邮件是 HTML 格式时，纯文本备选版本是对 HTML 做简单去标签处理生成的近似结果，原始 HTML 始终完整保留在 HTML 分支里。
+  OLM rarely exposes a genuinely distinct plain-text body; for HTML messages, the plain-text alternative is a best-effort tag-stripped approximation, while the original HTML is always preserved verbatim.
+- 邮件时间在 OLM 中不带时区信息，统一按 UTC 处理。
+  OLM timestamps carry no timezone info and are treated as UTC.
+
+## 支持 / Support
+
+如果这个工具帮你省了不少事，欢迎请我喝一杯咖啡 ☕️
+
+If this tool saved you some time, feel free to buy me a coffee ☕️
+
+<p>
+  <img src="assets/alipay-qr.jpg" alt="支付宝 Alipay" width="220">
+  <img src="assets/wechat-qr.jpg" alt="微信支付 WeChat Pay" width="220">
+</p>
+
+## 许可证 / License
+
+[MIT](LICENSE)

olm2mbox-0.1.0/src/olm2mbox.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/olm2mbox/__init__.py
+src/olm2mbox/cli.py
+src/olm2mbox/convert.py
+src/olm2mbox/split.py
+src/olm2mbox.egg-info/PKG-INFO
+src/olm2mbox.egg-info/SOURCES.txt
+src/olm2mbox.egg-info/dependency_links.txt
+src/olm2mbox.egg-info/entry_points.txt
+src/olm2mbox.egg-info/requires.txt
+src/olm2mbox.egg-info/top_level.txt
+tests/test_convert.py
+tests/test_split.py

olm2mbox-0.1.0/src/olm2mbox.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

olm2mbox-0.1.0/src/olm2mbox.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+olm2mbox = olm2mbox.cli:main

olm2mbox-0.1.0/src/olm2mbox.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7.0

olm2mbox-0.1.0/src/olm2mbox.egg-info/top_level.txt

@@ -0,0 +1 @@
+olm2mbox

olm2mbox-0.1.0/tests/test_convert.py

@@ -0,0 +1,136 @@
+"""Tests for olm2mbox.convert against a small synthetic .olm-shaped zip.
+
+Real .olm files can be tens or hundreds of gigabytes and contain private
+mail, so they can't be checked into the repo. Instead these tests build a
+minimal zip archive that mimics the on-disk layout OLM uses, covering the
+cases the converter specifically has to handle: a nested user subfolder, a
+name attribute on an address, an attachment with a Content-ID, and a header
+value containing an embedded newline.
+"""
+import email.policy
+import mailbox
+import os
+import zipfile
+from xml.sax.saxutils import escape as xml_escape
+
+import pytest
+
+from olm2mbox.convert import convert
+
+PREFIX = 'Local/com.microsoft.__Messages/'
+
+MESSAGE_XML_TEMPLATE = """<emails xml:space="preserve" elementCount="1"><email xml:space="preserve">{attachments}<OPFMessageCopyBody xml:space="preserve">{body}</OPFMessageCopyBody><OPFMessageCopyFromAddresses xml:space="preserve"><emailAddress xml:space="preserve" OPFContactEmailAddressAddress="{from_addr}" OPFContactEmailAddressName="{from_name}" OPFContactEmailAddressType="0"></emailAddress></OPFMessageCopyFromAddresses><OPFMessageCopyHTMLBody xml:space="preserve">{body}</OPFMessageCopyHTMLBody><OPFMessageCopyMessageID xml:space="preserve">{message_id}</OPFMessageCopyMessageID><OPFMessageCopyReceivedTime xml:space="preserve">2026-05-27T03:12:52</OPFMessageCopyReceivedTime><OPFMessageCopySentTime xml:space="preserve">2026-05-27T03:12:52</OPFMessageCopySentTime><OPFMessageCopySubject xml:space="preserve">{subject}</OPFMessageCopySubject><OPFMessageCopyToAddresses xml:space="preserve"><emailAddress xml:space="preserve" OPFContactEmailAddressAddress="{to_addr}" OPFContactEmailAddressType="0"></emailAddress></OPFMessageCopyToAddresses><OPFMessageGetHasHTML xml:space="preserve">1E0</OPFMessageGetHasHTML></email></emails>"""
+
+ATTACHMENT_XML = (
+    '<messageAttachment xml:space="preserve" OPFAttachmentContentExtension="png" '
+    'OPFAttachmentContentFileSize="4.22E2" OPFAttachmentContentID="{cid}" '
+    'OPFAttachmentContentType="image/png" OPFAttachmentName="{name}" '
+    'OPFAttachmentURL="{url}"></messageAttachment>'
+)
+
+
+def _build_olm(path, extra_subject_has_newline=False):
+    with zipfile.ZipFile(path, 'w') as zf:
+        # A message directly in the Inbox, with an attachment.
+        attach_url = f'{PREFIX}收件箱/com.microsoft.__Attachments/att0000_0000'
+        zf.writestr(attach_url, b'\x89PNG\r\n\x1a\nfake-png-bytes')
+        subject = 'Hello\r\nWorld' if extra_subject_has_newline else 'Hello World'
+        xml = MESSAGE_XML_TEMPLATE.format(
+            attachments=(
+                '<OPFMessageCopyAttachmentList xml:space="preserve">'
+                + ATTACHMENT_XML.format(cid='img1@example.com', name='pic.png', url=attach_url)
+                + '</OPFMessageCopyAttachmentList>'
+            ),
+            # OLM stores the HTML body double-escaped: it's XML-escaped text
+            # content whose *value* is itself HTML markup.
+            body=xml_escape('<html><body>Hi &amp; welcome, 你好</body></html>'),
+            from_addr='alice@example.com', from_name='Alice',
+            message_id='msg1@example.com',
+            subject=subject,
+            to_addr='bob@example.com',
+        )
+        zf.writestr(f'{PREFIX}收件箱/message_00000.xml', xml)
+
+        # A message in a nested, user-created subfolder.
+        xml2 = MESSAGE_XML_TEMPLATE.format(
+            attachments='',
+            body=xml_escape('<html><body>Second message</body></html>'),
+            from_addr='carol@example.com', from_name='carol@example.com',
+            message_id='msg2@example.com',
+            subject='Nested folder message',
+            to_addr='bob@example.com',
+        )
+        zf.writestr(f'{PREFIX}收件箱/ProjectX/message_00000.xml', xml2)
+
+
+@pytest.fixture
+def olm_path(tmp_path):
+    path = tmp_path / 'sample.olm'
+    _build_olm(path)
+    return path
+
+
+def test_discovers_top_level_and_nested_folders(olm_path, tmp_path):
+    out_dir = tmp_path / 'out'
+    stats = convert(str(olm_path), str(out_dir))
+
+    assert os.path.exists(out_dir / 'Inbox.mbox')
+    assert os.path.exists(out_dir / 'Inbox' / 'ProjectX.mbox')
+    assert stats['Inbox']['count'] == 1
+    assert stats['Inbox/ProjectX']['count'] == 1
+    assert stats['Inbox']['errors'] == 0
+    assert stats['Inbox/ProjectX']['errors'] == 0
+
+
+def test_message_headers_body_and_attachment(olm_path, tmp_path):
+    out_dir = tmp_path / 'out'
+    convert(str(olm_path), str(out_dir))
+
+    mb = mailbox.mbox(
+        str(out_dir / 'Inbox.mbox'),
+        factory=lambda f: email.message_from_binary_file(f, policy=email.policy.default),
+    )
+    messages = list(mb)
+    assert len(messages) == 1
+    msg = messages[0]
+
+    assert msg['Subject'] == 'Hello World'
+    assert msg['From'] == 'Alice <alice@example.com>'
+    assert msg['To'] == 'bob@example.com'
+    assert msg['Message-ID'] == '<msg1@example.com>'
+
+    html_part = msg.get_body(preferencelist=('html',))
+    assert '你好' in html_part.get_content()  # CJK preserved, not entity-escaped
+
+    attachments = list(msg.iter_attachments())
+    assert len(attachments) == 1
+    assert attachments[0].get_filename() == 'pic.png'
+    assert attachments[0].get_content_type() == 'image/png'
+    assert attachments[0].get_content() == b'\x89PNG\r\n\x1a\nfake-png-bytes'
+
+
+def test_embedded_newline_in_subject_does_not_crash(tmp_path):
+    olm = tmp_path / 'sample.olm'
+    _build_olm(olm, extra_subject_has_newline=True)
+    out_dir = tmp_path / 'out'
+
+    stats = convert(str(olm), str(out_dir))
+    assert stats['Inbox']['errors'] == 0
+
+    mb = mailbox.mbox(
+        str(out_dir / 'Inbox.mbox'),
+        factory=lambda f: email.message_from_binary_file(f, policy=email.policy.default),
+    )
+    msg = list(mb)[0]
+    assert '\n' not in msg['Subject']
+    assert '\r' not in msg['Subject']
+
+
+def test_resume_skips_completed_folders(olm_path, tmp_path):
+    out_dir = tmp_path / 'out'
+    convert(str(olm_path), str(out_dir))
+    mtime_before = os.path.getmtime(out_dir / 'Inbox.mbox')
+
+    stats = convert(str(olm_path), str(out_dir), resume=True)
+    assert 'Inbox' not in stats  # skipped, not reprocessed
+    assert os.path.getmtime(out_dir / 'Inbox.mbox') == mtime_before

olm2mbox-0.1.0/tests/test_split.py

@@ -0,0 +1,79 @@
+"""Tests for olm2mbox.split.
+
+Builds a small synthetic mbox file (valid "From " envelopes + mboxrd-style
+body escaping) and exercises the chunking, dry-run, and real truncate-based
+split paths against it.
+"""
+import glob
+import os
+
+import pytest
+
+from olm2mbox.split import split
+
+MSG_TEMPLATE = (
+    b'From sender%d@example.com Fri Aug %02d 10:00:00 2022\n'
+    b'Subject: message %d\n'
+    b'\n'
+    b'%s\n'
+)
+
+
+def _build_mbox(path, n_messages, payload_size):
+    with open(path, 'wb') as f:
+        for i in range(n_messages):
+            body = (b'x' * payload_size)
+            f.write(MSG_TEMPLATE % (i, (i % 28) + 1, i, body))
+            f.write(b'\n')
+
+
+def test_dry_run_leaves_source_untouched(tmp_path):
+    src = tmp_path / 'test.mbox'
+    _build_mbox(src, n_messages=20, payload_size=1000)
+    original_bytes = src.read_bytes()
+
+    part_paths, offsets, size = split(str(src), max_bytes=5000, dry_run=True)
+
+    assert src.read_bytes() == original_bytes  # untouched
+    assert len(part_paths) > 1
+    assert all(os.path.exists(p) for p in part_paths)
+    for p in part_paths:
+        os.remove(p)
+
+
+def test_real_split_is_byte_exact_and_message_exact(tmp_path):
+    src = tmp_path / 'test.mbox'
+    _build_mbox(src, n_messages=37, payload_size=2000)
+    original_bytes = src.read_bytes()
+    original_message_count = original_bytes.count(b'\nFrom sender') + 1
+
+    part_paths, offsets, size = split(str(src), max_bytes=8000, dry_run=False)
+
+    # Source is fully consumed and removed.
+    assert not os.path.exists(src)
+    assert len(part_paths) > 1
+
+    # Reassembling the parts in order reproduces the original exactly.
+    reassembled = b''.join(open(p, 'rb').read() for p in sorted(part_paths))
+    assert reassembled == original_bytes
+
+    # No message is split across a part boundary, and the total count matches.
+    total_messages = sum(
+        open(p, 'rb').read().count(b'\nFrom sender')
+        + (1 if open(p, 'rb').read().startswith(b'From sender') else 0)
+        for p in part_paths
+    )
+    assert total_messages == original_message_count
+
+
+def test_out_dir_places_parts_elsewhere(tmp_path):
+    src = tmp_path / 'test.mbox'
+    _build_mbox(src, n_messages=10, payload_size=500)
+    out_dir = tmp_path / 'parts'
+    out_dir.mkdir()
+
+    part_paths, offsets, size = split(str(src), max_bytes=3000, dry_run=True, out_dir=str(out_dir))
+
+    assert all(p.startswith(str(out_dir)) for p in part_paths)
+    for p in part_paths:
+        os.remove(p)