13.6. "plistlib" --- Mac OS X ".plist" ファイルの生成と解析
***********************************************************

バージョン 2.6 で変更: このモジュールは以前は Mac 専用ライブラリだけに
ありましたが、全てのプラットフォームで使えるようにしました。

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

======================================================================

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

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

値は文字列、整数、浮動小数点数、ブール型、タプル、リスト、辞書 (ただし
文字列だけがキーになれます)、 "Data" または "datetime.datetime" のオブ
ジェクトです。文字列の値は(辞書のキーも含めて) Unicode 文字列であって
構いません -- それらは UTF-8 で書き出されます。

"<data>" plist 型は "Data" クラスを通じてサポートされます。これは
Python の文字列に対する薄いラッパです。文字列に制御文字を含めなければ
ならない場合は "Data" を使って下さい。

参考:

  PList マニュアルページ
     このファイル形式の Apple の文書。

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

plistlib.readPlist(pathOrFile)

   plist ファイルを読み込みます。 *pathOrFile* はファイル名でも (読み
   込み可能な) ファイルオブジェクトでも構いません。展開されたルートオ
   ブジェクト (たいていは辞書です) を返します。

   XML データは "xml.parsers.expat" にある Expat パーサを使って解析さ
   れます -- 間違いのある XML に対して送られる可能性のある例外について
   はそちらの文書を参照して下さい。未知の要素は plist 解析器から単純に
   無視されます。

plistlib.writePlist(rootObject, pathOrFile)

   *rootObject* を plist ファイルに書き込みます。 *pathOrFile* はファ
   イル名でも (書き込み可能な) ファイルオブジェクトでも構いません。

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

plistlib.readPlistFromString(data)

   文字列から plist を読み取ります。ルートオブジェクトを返します。

plistlib.writePlistToString(rootObject)

   *rootObject* を plist 形式の文字列として返します。

plistlib.readPlistFromResource(path, restype='plst', resid=0)

   *path* のリソースフォークの中の *restype* タイプのリソースから
   plist を読み込みます。使用可能: Mac OS X。

   注釈: Python 3.x でこの関数は削除されました。

plistlib.writePlistToResource(rootObject, path, restype='plst', resid=0)

   *rootObject* を *path* のリソースフォークの中に *restype* タイプの
   リソースとして書き込みます。使用可能: Mac OS X。

   注釈: Python 3.x でこの関数は削除されました。

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

class plistlib.Data(data)

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

   これには "data" という一つの属性があり、そこに収められた Python 文
   字列を取り出すのに使えます。


13.6.1. 例
==========

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!>",
           aUnicodeValue=u'M\xe4ssig, Ma\xdf',
           aTrueValue=True,
           aFalseValue=False,
       ),
       someData = Data("<binary gunk>"),
       someMoreData = Data("<lots of binary gunk>" * 10),
       aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
   )
   # unicode keys are possible, but a little awkward to use:
   pl[u'\xc5benraa'] = "That was a unicode key."
   writePlist(pl, fileName)

plist を解析します:

   pl = readPlist(pathOrFile)
   print pl["aKey"]
