Python plistlib 怎样把配置写成二进制 plist

我在把一组 Python 配置交给 macOS 工具读取时，最容易踩的坑不是字典怎么组装，而是写出的 plist 格式不对。plistlib.dump() 和 plistlib.dumps() 默认使用 XML；要得到二进制 plist，需要显式传入 fmt=plistlib.FMT_BINARY。文件写入用 dump，需要先拿到字节再交给上传、缓存或原子替换逻辑时用 dumps。

官方地址：https://docs.python.org/3/library/plistlib.html

最小改法就是给 dump 或 dumps 加上 fmt=plistlib.FMT_BINARY。生产代码还应保证字典键是字符串、用二进制模式打开文件，并在写入失败时保留旧配置。

• 文件接口：dump(value, fp, fmt=plistlib.FMT_BINARY) 直接写入二进制文件对象。
• 内存接口：dumps(value, fmt=plistlib.FMT_BINARY) 返回 plist 字节。
• 稳定性：sort_keys=True 默认按排序后的键写出，便于生成可比较的配置包。
• 边界：非字符串字典键、无法支持的值和超出二进制 plist 表示范围的整数，都应单独处理。

先选 dump 还是 dumps

如果目标是一个配置文件，优先使用 dump；它要求传入可写的二进制文件对象。如果配置还要经过对象存储、HTTP 上传或签名流程，先使用 dumps 得到 bytes，再交给后续代码。两者接受的值模型相同，差别主要在输出位置。

这里的图是静态说明图，不是终端截图或运行证据。实际项目中可以先把配置对象整理好，再根据调用方选择文件路径或字节流，避免在不同模块里重复实现 XML 与二进制两套序列化逻辑。

用 FMT_BINARY 写出二进制 plist

下面的写法把一个带嵌套字典和列表的配置写成二进制 plist。文件必须以 wb 打开；如果误用文本模式，文件接口会和预期的二进制写入不匹配。

from pathlib import Path
import os
import plistlib
import tempfile

def write_binary_plist(value: dict, target: Path) -> None:
    """将配置以二进制 plist 形式安全替换到目标路径。"""
    target.parent.mkdir(parents=True, exist_ok=True)
    # 先在目标目录创建临时文件，避免跨文件系统替换带来的失败。
    fd, temp_name = tempfile.mkstemp(prefix=target.name + ".", dir=target.parent)
    try:
        with os.fdopen(fd, "wb") as fp:
            # FMT_BINARY 是关键参数；sort_keys 让同一配置更容易比较。
            plistlib.dump(value, fp, fmt=plistlib.FMT_BINARY, sort_keys=True)
            fp.flush()
            os.fsync(fp.fileno())
        # 写入成功后再替换旧文件，失败时不会先清掉旧配置。
        os.replace(temp_name, target)
    except (TypeError, OverflowError):
        # 类型或整数范围不满足 plist 约束时，保留异常给调用方处理。
        try:
            os.unlink(temp_name)
        except FileNotFoundError:
            pass
        raise
    except Exception:
        # 其他 IO 错误同样清理临时文件，避免目录留下半成品。
        try:
            os.unlink(temp_name)
        except FileNotFoundError:
            pass
        raise

config = {
    "service": {"host": "127.0.0.1", "port": 8080},
    "features": ["cache", "metrics"],
    "enabled": True,
}
write_binary_plist(config, Path("settings.plist"))

这段代码的重点不是临时文件本身，而是把格式选择、二进制文件模式和替换时机放在同一处。这样配置对象无法序列化时，不会把一个看似存在但内容不完整的目标文件留给下游。

生产环境要固定哪些边界

我实际更关注三类边界。第一，plist 字典的键应使用字符串；官方接口在 skipkeys=False 时遇到非字符串键会抛出 TypeError，不建议为了“写进去”而静默跳过配置。第二，sort_keys=True 是默认值，若需要保持输入字典的迭代顺序才改为 False，否则固定排序更利于审阅差异。第三，值类型应落在模块支持的字符串、数字、布尔值、列表、字典、字节串、日期等范围内。

官方文档还说明，无法用二进制 plist 表示的整数会触发 OverflowError；容器中包含不支持对象时也会触发 TypeError。这两种错误应回到配置输入处理，而不是简单改成 XML 或把异常吞掉。图中只表达静态关系，不代表已经执行过这段代码。

用 dumps 生成 bytes，再交给其他流程

如果不想在序列化函数里管理文件，可以先生成字节：

import plistlib

config = {"name": "demo", "retry": 3}
# 生成二进制 plist 字节，适合交给上传或缓存层。
payload = plistlib.dumps(config, fmt=plistlib.FMT_BINARY, sort_keys=True)

# 读取时让 plistlib 自动识别 XML 或二进制格式。
decoded = plistlib.loads(payload)
print(decoded["name"])

loads 可以从字节或字符串对象读取 plist；读取文件时对应使用 load。不指定读取格式时，模块会自动识别 XML 或二进制格式，因此写入端需要显式指定格式，读取端通常可以保持默认。

常见问题

为什么写出来还是 XML？

因为 dump 和 dumps 的默认 fmt 是 FMT_XML。写入时显式传入 fmt=plistlib.FMT_BINARY 即可。

能不能把非字符串键自动跳过？

可以把 skipkeys 设置为 True，但配置场景通常不建议静默丢字段。更稳妥的是在输入阶段把键规范化为字符串，并保留默认的异常提示。

读取二进制 plist 也要指定 FMT_BINARY 吗？

不一定。load 和 loads 在 fmt=None 时会自动检测格式；只有需要强制限制输入格式时才显式传入 FMT_BINARY。