plistlib — 生成和解析 Apple .plist 文件

源代码: Lib/plistlib.py

此模块提供了一个接口，用于读取和写入 Apple 使用的“属性列表”文件，主要在 macOS 和 iOS 上。此模块同时支持二进制和 XML plist 文件。

属性列表 (.plist) 文件格式是一种简单的序列化，支持基本对象类型，例如字典、列表、数字和字符串。通常，顶级对象是一个字典。

要写入和解析 plist 文件，请使用 dump() 和 load() 函数。

要处理字节或字符串对象中的 plist 数据，请使用 dumps() 和 loads()。

值可以是字符串、整数、浮点数、布尔值、元组、列表、字典（但仅限字符串键）、bytes、bytearray 或 datetime.datetime 对象。

3.4 版本中的变化: 新 API，旧 API 已弃用。增加了对二进制格式 plist 的支持。

3.8 版本中的变化: 增加了对读取和写入 NSKeyedArchiver 和 NSKeyedUnarchiver 使用的二进制 plist 中的 UID 令牌的支持。

3.9 版本中的变化: 旧 API 已删除。

参见

PList 手册页

Apple 的文件格式文档。

该模块定义了以下函数：

plistlib.load(fp, *, fmt=None, dict_type=dict, aware_datetime=False)

读取 plist 文件。fp 应该是一个可读的二进制文件对象。返回解包后的根对象（通常是一个字典）。

fmt 是文件的格式，以下值是有效的

dict_type 是从 plist 文件中读取的字典所使用的类型。

当 aware_datetime 为真时，类型为 datetime.datetime 的字段将作为 感知对象 创建，其 tzinfo 为 datetime.UTC。

FMT_XML 格式的 XML 数据使用 xml.parsers.expat 中的 Expat 解析器进行解析——有关格式错误的 XML 可能产生的异常，请参阅其文档。未知元素将被 plist 解析器简单地忽略。

当文件无法解析时，解析器会引发 InvalidFileException。

在 3.4 版本加入。

3.13 版本中的变化: 增加了仅限关键字参数 aware_datetime。

plistlib.loads(data, *, fmt=None, dict_type=dict, aware_datetime=False)

从字节或字符串对象加载 plist。有关关键字参数的解释，请参阅 load()。

在 3.4 版本加入。

3.13 版本中的变化: 当 fmt 等于 FMT_XML 时，data 可以是字符串。

plistlib.dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False, aware_datetime=False)

将 value 写入 plist 文件。fp 应该是一个可写的二进制文件对象。

fmt 参数指定 plist 文件的格式，可以是以下值之一

当 sort_keys 为真（默认值）时，字典的键将按排序顺序写入 plist，否则将按字典的迭代顺序写入。

当 skipkeys 为假（默认值）时，如果字典的键不是字符串，函数会引发 TypeError，否则会跳过此类键。

当 aware_datetime 为真并且类型为 datetime.datetime 的任何字段被设置为 感知对象 时，它将在写入之前转换为 UTC 时区。

如果对象是不支持的类型或包含不支持类型的对象的容器，将引发 TypeError。

对于无法在（二进制）plist 文件中表示的整数值，将引发 OverflowError。

在 3.4 版本加入。

3.13 版本中的变化: 增加了仅限关键字参数 aware_datetime。

plistlib.dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False, aware_datetime=False)

将 value 作为 plist 格式的字节对象返回。有关此函数的关键字参数的解释，请参阅 dump() 的文档。

在 3.4 版本加入。

以下类可用

class plistlib.UID(data)

包装一个 int。这在读取或写入包含 UID 的 NSKeyedArchiver 编码数据时使用（参见 PList 手册）。

data

UID 的整数值。它必须在范围 0 <= data < 2**64 内。

在 3.8 版本加入。

以下常量可用

plistlib.FMT_XML

plist 文件的 XML 格式。

在 3.4 版本加入。

plistlib.FMT_BINARY

plist 文件的二进制格式

在 3.4 版本加入。

该模块定义了以下异常

exception plistlib.InvalidFileException

当文件无法解析时引发。

在 3.4 版本加入。

示例

生成 plist

import datetime
import plistlib

pl = dict(
    aString = "Doodah",
    aList = ["A", "B", 12, 32.1, [1, 2, 3]],
    aFloat = 0.1,
    anInt = 728,
    aDict = dict(
        anotherString = "<hello & hi there!>",
        aThirdString = "M\xe4ssig, Ma\xdf",
        aTrueValue = True,
        aFalseValue = False,
    ),
    someData = b"<binary gunk>",
    someMoreData = b"<lots of binary gunk>" * 10,
    aDate = datetime.datetime.now()
)
print(plistlib.dumps(pl).decode())

解析 plist

import plistlib

plist = b"""<plist version="1.0">
<dict>
    <key>foo</key>
    <string>bar</string>
</dict>
</plist>"""
pl = plistlib.loads(plist)
print(pl["foo"])