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