# `plistlib` --- Mac OS X `.plist` ファイルの生成と解析

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

このモジュールは主に Mac OS X で使われる「プロパティーリスト」ファイルを読み書きするインターフェイスを提供します。バイナリと XML の plist ファイルの両方をサポートします。

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

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

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

値は文字列、整数、浮動小数点数、ブール型、タプル、リスト、辞書 (ただし文字列だけがキーになれます)、 `Data`、`bytes`、`bytesarray` または `datetime.datetime` のオブジェクトです。

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

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

参考

PList マニュアルページ

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

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

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

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

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

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

  - `FMT_XML`: XML ファイル形式です

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

  use_builtin_types が真 (デフォルト) の場合、バイナリデータが `bytes` のインスタンスとして返されます。偽の場合、 `Data` のインスタンスとして返されます。

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

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

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

  バージョン 3.4 で追加.

`plistlib.``loads`(data, *, fmt=None, use_builtin_types=True, 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 で追加.

以下の関数は廃止されています。

`plistlib.``readPlist`(pathOrFile)

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

  この関数は、実際の動作のために `load()` を呼び出します。キーワード引数の説明については、`その関数` のドキュメントを参照してください。

  バージョン 3.4 で非推奨: 代わりに `load()` を使ってください。

  バージョン 3.7 で変更: 結果にある辞書値は通常の辞書となりました。 属性アクセスを使って、辞書の項目にアクセスできなくなりました。

`plistlib.``writePlist`(rootObject, pathOrFile)

  rootObject を XML plist ファイルに書き込みます。 pathOrFile は、ファイル名もしくは (書き込み可能かつバイナリの) ファイルオブジェクトです。

  バージョン 3.4 で非推奨: 代わりに `dump()` を使ってください。

`plistlib.``readPlistFromBytes`(data)

  バイト列オブジェクトから plist データを読み取ります。ルートオブジェクトを返します。

  キーワード引数の説明については、 `load()` を参照してください。

  バージョン 3.4 で非推奨: 代わりに `loads()` を使ってください。

  バージョン 3.7 で変更: 結果にある辞書値は通常の辞書となりました。 属性アクセスを使って、辞書の項目にアクセスできなくなりました。

`plistlib.``writePlistToBytes`(rootObject)

  rootObject を XML plist 形式のバイト列オブジェクトとして返します。

  バージョン 3.4 で非推奨: 代わりに `dumps()` を使ってください。

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

class `plistlib.``Data`(data)

  バイト列オブジェクト data を包むラッパオブジェクトを返します。plist 中に入れられる `<data>` 型を表すものとして plist への/からの変換関数で使われます。

  これには `data` という一つの属性があり、そこに収められた Python バイト列オブジェクトを取り出すのに使えます。

  バージョン 3.4 で非推奨: 代わりに `bytes` オブジェクトを使ってください。

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