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

参考:

  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)

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

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