plistlib --- Generate and parse Apple .plist files

ソースコード: Lib/plistlib.py


This module provides an interface for reading and writing the "property list" files used by Apple, primarily on macOS and iOS. This module supports both binary and XML plist files.

プロパティーリスト (.plist) ファイル形式は基本的型のオブジェクト、たとえば辞書やリスト、数、文字列など、に対する単純な直列化です。たいてい、トップレベルのオブジェクトは辞書です。

plist ファイルを書き出したり解析したりするには dump()load() 関数を利用します。

バイトオブジェクトの plist データを扱うためには dumps()loads() を利用します。

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries (but only with string keys), bytes, bytearray or datetime.datetime objects.

バージョン 3.4 で変更: 新しい API。古い API は撤廃されました。バイナリ形式の plist がサポートされました。

バージョン 3.8 で変更: Support added for reading and writing UID tokens in binary plists as used by NSKeyedArchiver and NSKeyedUnarchiver.

バージョン 3.9 で変更: Old API removed.

参考

PList マニュアルページ

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

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

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

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

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

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

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

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

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

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

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

バージョン 3.4 で追加.

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

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

バージョン 3.4 で追加.

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

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

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

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

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

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

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

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

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

バージョン 3.4 で追加.

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

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

バージョン 3.4 で追加.

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

class plistlib.UID(data)

Wraps an int. This is used when reading or writing NSKeyedArchiver encoded data, which contains UID (see PList manual).

It has one attribute, data, which can be used to retrieve the int value of the UID. data must be in the range 0 <= data < 2**64.

バージョン 3.8 で追加.

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

plistlib.FMT_XML

plist ファイルの XML 形式です

バージョン 3.4 で追加.

plistlib.FMT_BINARY

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

バージョン 3.4 で追加.

使用例

plist を作ります:

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.fromtimestamp(time.mktime(time.gmtime())),
)
with open(fileName, 'wb') as fp:
    dump(pl, fp)

plist を解析します:

with open(fileName, 'rb') as fp:
    pl = load(fp)
print(pl["aKey"])