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 版本中变更: 添加了对读取和写入二进制 plist 中 UID 令牌的支持，这些令牌由 NSKeyedArchiver 和 NSKeyedUnarchiver 使用。

在 3.9 版本中变更: 删除了旧的 API。

参见

PList 手册页

Apple 的文件格式文档。

此模块定义了以下函数

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

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

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

dict_type 是用于从 plist 文件读取的字典的类型。

当 aware_datetime 为 true 时，类型为 datetime.datetime 的字段将创建为 aware 对象，其中 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 为 true（默认值）时，字典的键将按排序顺序写入 plist，否则将按字典的迭代顺序写入。

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

当 aware_datetime 为 true 且任何类型为 datetime.datetime 的字段设置为 aware 对象时，它会在写入之前转换为 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的整数值。data 必须在 0 <= data < 2**64 范围内。

在 3.8 版本中添加。

以下常量可用

plistlib.FMT_XML

plist文件的XML格式。

在 3.4 版本中添加。

plistlib.FMT_BINARY

plist文件的二进制格式。

在 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"])