"plistlib" --- Apple ".plist" ファイルの生成と解析
**************************************************

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

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

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

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

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

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

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

バージョン 3.4 で変更: 新しい API となり、古い API は非推奨となりまし
た。バイナリ形式の plist がサポートされました。

バージョン 3.8 で変更: バイナリの plist で NSKeyedArchiver や
NSKeyedUnarchiver によって使用される "UID" トークンの読み込み・書き込
みのサポートが追加されました。

バージョン 3.9 で変更: 古い API が削除されました。

参考:

  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)

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

   これは一つ、 "data" 属性を持ち、これにより UID の int 値を取得する
   ことができます。 "data" は "0 <= data < 2**64" の範囲内でなければな
   りません。

   バージョン 3.8 で追加.

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

plistlib.FMT_XML

   plist ファイルの XML 形式です

   バージョン 3.4 で追加.

plistlib.FMT_BINARY

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

   バージョン 3.4 で追加.


使用例
======

plist を作ります:

   import datetime
   import plistlib

   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.now()
   )
   print(plistlib.dumps(pl).decode())

plist を解析します:

   import plistlib

   plist = b"""<plist version="1.0">
   <dict>
       <key>foo</key>
       <string>bar</string>
   </dict>
   </plist>"""
   pl = plistlib.loads(plist)
   print(pl["foo"])
