"plistlib" --- Apple ".plist" ファイルを生成・解析する
******************************************************

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

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

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

The property list (".plist") file format is a simple serialization
supporting basic object types, like dictionaries, lists, numbers and
strings.  Usually the top level object is a dictionary or a frozen
dictionary.

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, aware_datetime=False)

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

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

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

   * "FMT_XML": XML ファイル形式です

   * "FMT_BINARY": バイナリの plist 形式です

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

   When *aware_datetime* is true, fields with type "datetime.datetime"
   will be created as aware object, with "tzinfo" as "datetime.UTC".

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

   The parser raises "InvalidFileException" when the file cannot be
   parsed.

   Added in version 3.4.

   バージョン 3.13 で変更: キーワード専用引数 *aware_datetime* が追加
   されました。

plistlib.loads(data, *, fmt=None, dict_type=dict, aware_datetime=False)

   バイナリまたは文字列オブジェクトから plist をロードします。キーワー
   ド引数の説明については、 "load()" を参照してください。

   Added in version 3.4.

   バージョン 3.13 で変更: *fmt* が "FMT_XML" の場合、 *data* は文字列
   たり得ます。

plistlib.dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False, aware_datetime=False)

   Write *value* to a plist file. *fp* should be a writable, binary
   file object.

   *fmt* 引数は plist ファイルの形式を指定し、次のいずれかの値をとるこ
   とができます。

   * "FMT_XML": XML 形式の plist ファイルです

   * "FMT_BINARY": バイナリ形式の plist ファイルです

   *sort_keys* が真 (デフォルト) の場合、辞書内のキーは、plist にソー
   トされた順序で書き込まれます。偽の場合、ディクショナリのイテレート
   の順序で書き込まれます。

   *skipkeys* が偽 (デフォルト) の場合、この関数は辞書のキーが文字列で
   ない場合に "TypeError" を送出します。真の場合、そのようなキーは読み
   飛ばされます。

   When *aware_datetime* is true and any field with type
   "datetime.datetime" is set as an aware object, it will convert to
   UTC timezone before writing it.

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

   (バイナリの) plist ファイル内で表現できない整数値に対しては、
   "OverflowError" が送出されます。

   Added in version 3.4.

   バージョン 3.13 で変更: キーワード専用引数 *aware_datetime* が追加
   されました。

plistlib.dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False, aware_datetime=False)

   *value* を plist 形式のバイトオブジェクトとして返します。この関数の
   キーワード引数の説明については、 "dump()" を参照してください。

   Added in version 3.4.

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

class plistlib.UID(data)

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

   data

      Int value of the UID.  It must be in the range "0 <= data <
      2**64".

   Added in version 3.8.

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

plistlib.FMT_XML

   plist ファイルの XML 形式です

   Added in version 3.4.

plistlib.FMT_BINARY

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

   Added in version 3.4.

The module defines the following exceptions:

exception plistlib.InvalidFileException

   Raised when a file cannot be parsed.

   Added in version 3.4.


使用例
======

plist を作ります:

   import datetime as dt
   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 = dt.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"])
