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 檔案的格式，可以是以下值之一

  • FMT_XML：XML 格式的 plist 檔案

  • FMT_BINARY：二進位制格式的 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"])