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