14.5. 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 がサポートされました。
参考
- 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 ファイルから読み出された辞書に使用される型です。
collections.OrderedDict
を使用すると、plist の正確な構造を復元できます (ただし、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()
を呼び出します。キーワード引数の説明については、その関数
のドキュメントを参照してください。注釈
結果の辞書の値は、
__getitem_
につながる__getattr__
メソッドを持ちます。つまり、属性アクセスを使用して、これらの辞書の項目にアクセスすることができます。バージョン 3.4 で撤廃: 代わりに
load()
を使ってください。
-
plistlib.
writePlist
(rootObject, pathOrFile)¶ rootObject を XML plist ファイルに書き込みます。 pathOrFile は、ファイル名もしくは (書き込み可能かつバイナリの) ファイルオブジェクトです。
バージョン 3.4 で撤廃: 代わりに
dump()
を使ってください。
-
plistlib.
readPlistFromBytes
(data)¶ バイト列オブジェクトから plist データを読み取ります。ルートオブジェクトを返します。
キーワード引数の説明については、
load()
を参照してください。注釈
結果の辞書の値は、
__getitem_
につながる__getattr__
メソッドを持ちます。つまり、属性アクセスを使用して、これらの辞書の項目にアクセスすることができます。バージョン 3.4 で撤廃: 代わりに
loads()
を使ってください。
-
plistlib.
writePlistToBytes
(rootObject)¶ rootObject を XML plist 形式のバイト列オブジェクトとして返します。
バージョン 3.4 で撤廃: 代わりに
dumps()
を使ってください。
以下のクラスが使用可能です:
-
Dict([dict]):
辞書 dict と同じ値を持つ拡張マップ型オブジェクトを返します。
このクラスは、
dict
のサブクラスで、属性アクセスを使用して項目にアクセスできます。つまり、マッピング内の項目を取得、設定、削除する上で、aDict.key
はaDict['key']
と等価です。バージョン 3.0 で撤廃.
-
class
plistlib.
Data
(data)¶ バイト列オブジェクト data を包むラッパオブジェクトを返します。plist 中に入れられる
<data>
型を表すものとして plist への/からの変換関数で使われます。これには
data
という一つの属性があり、そこに収められた Python バイト列オブジェクトを取り出すのに使えます。バージョン 3.4 で撤廃: 代わりに
bytes
オブジェクトを使ってください。
以下の定数が利用可能です:
-
plistlib.
FMT_XML
¶ plist ファイルの XML 形式です
バージョン 3.4 で追加.
-
plistlib.
FMT_BINARY
¶ plist ファイルのバイナリ形式です
バージョン 3.4 で追加.
14.5.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!>",
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"])