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 で NSKeyedArchiver や NSKeyedUnarchiver によって使用される UID トークンの読み込み・書き込みのサポートが追加されました。

バージョン 3.9 で変更: 古い API が削除されました。

参考

PList マニュアルページ

このファイル形式の Apple の文書。

このモジュールは以下の関数を定義しています:

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

plist ファイルを読み込みます。fp は読み込み可能かつバイナリのファイルオブジェクトです。展開されたルートオブジェクト (通常は辞書です) を返します。

fmt はファイルの形式で、次の値が有効です。

  • None: ファイル形式を自動検出します

  • FMT_XML: XML ファイル形式です

  • FMT_BINARY: バイナリの plist 形式です

dict_type は、 plist ファイルから読み出された辞書に使われる型です。

aware_datetime が true の場合、 datetime.datetime 型によるフィールドは、 datetime.UTC の tzinfo 付きで aware オブジェクト として作成されます。

FMT_XML 形式の XML データは xml.parsers.expat にある Expat パーサーを使って解析されます。不正な形式の XML に対して送出される可能性のある例外については、そちらの文書を参照してください。plist 解析器では、未知の要素は単純に無視されます。

バイナリ形式のパーサーは、ファイルを解析できない場合に InvalidFileException を送出します。

Added in version 3.4.

バージョン 3.13 で変更: キーワード専用引数 aware_datetime が追加されました。

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

バイナリまたは文字列オブジェクトから plist をロードします。キーワード引数の説明については、 load() を参照してください。

Added in version 3.4.

バージョン 3.13 で変更: fmt が FMT_XML の場合、 data は文字列たり得ます。

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

plist ファイルに value を書き込みます。Fp は、書き込み可能なバイナリファイルオブジェクトにしてください。

fmt 引数は plist ファイルの形式を指定し、次のいずれかの値をとることができます。

  • FMT_XML: XML 形式の plist ファイルです

  • FMT_BINARY: バイナリ形式の plist ファイルです

sort_keys が真 (デフォルト) の場合、辞書内のキーは、plist にソートされた順序で書き込まれます。偽の場合、ディクショナリのイテレートの順序で書き込まれます。

skipkeys が偽 (デフォルト) の場合、この関数は辞書のキーが文字列でない場合に TypeError を送出します。真の場合、そのようなキーは読み飛ばされます。

When aware_datetime is true and any field with type datetime.datetime is set as an aware object, it will convert to UTC timezone before writing it.

TypeError が、オブジェクトがサポート外の型のものであったりサポート外の型のオブジェクトを含むコンテナだった場合に、送出されます。

(バイナリの) plist ファイル内で表現できない整数値に対しては、 OverflowError が送出されます。

Added in version 3.4.

バージョン 3.13 で変更: キーワード専用引数 aware_datetime が追加されました。

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

value を plist 形式のバイトオブジェクトとして返します。この関数のキーワード引数の説明については、 dump() を参照してください。

Added in version 3.4.

以下のクラスが使用可能です:

class plistlib.UID(data)

int をラップします。これは NSKeyedArchiver でエンコードされた UID を含むデータ、の読み込みや書き込みに使用されます (PList マニュアルを参照) 。

これは一つ、 data 属性を持ち、これにより UID の int 値を取得することができます。 data は 0 <= data < 2**64 の範囲内でなければなりません。

Added in version 3.8.

以下の定数が利用可能です:

plistlib.FMT_XML

plist ファイルの XML 形式です

Added in version 3.4.

plistlib.FMT_BINARY

plist ファイルのバイナリ形式です

Added in version 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"])