# `plistlib` --- 產生和剖析 Apple `.plist` 檔案

原始碼：Lib/plistlib.py

This module provides an interface for reading and writing the "property list" files used by Apple, primarily on macOS and iOS. This module supports both binary and XML plist files.

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.

To write out and to parse a plist file, use the `dump()` and `load()` functions.

To work with plist data in bytes or string objects, use `dumps()` and `loads()`.

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries (but only with string keys), `bytes`, `bytearray` or `datetime.datetime` objects.

在 3.4 版的變更: New API, old API deprecated. Support for binary format plists added.

在 3.8 版的變更: Support added for reading and writing `UID` tokens in binary plists as used by NSKeyedArchiver and NSKeyedUnarchiver.

在 3.9 版的變更: Old API removed.

也參考

PList manual page

  Apple's documentation of the file format.

此模組定義了以下函式：

plistlib.load(fp, *, fmt=None, dict_type=dict, aware_datetime=False)

  Read a plist file. fp should be a readable and binary file object. Return the unpacked root object (which usually is a dictionary).

  The fmt is the format of the file and the following values are valid:

  - `None`：自動偵測檔案格式

  - `FMT_XML`：XML 檔案格式

  - `FMT_BINARY`：二進位 plist 格式

  The dict_type is the type used for dictionaries that are read from the plist file.

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

  XML data for the `FMT_XML` format is parsed using the Expat parser from `xml.parsers.expat` -- see its documentation for possible exceptions on ill-formed XML. Unknown elements will simply be ignored by the plist parser.

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

  在 3.4 版被加入.

  在 3.13 版的變更: 新增僅限關鍵字參數 aware_datetime。

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

  Load a plist from a bytes or string object. See `load()` for an explanation of the keyword arguments.

  在 3.4 版被加入.

  在 3.13 版的變更: data 在 fmt 等於 `FMT_XML` 時可以是一個字串。

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.

  The fmt argument specifies the format of the plist file and can be one of the following values:

  - `FMT_XML`: XML formatted plist file

  - `FMT_BINARY`: Binary formatted plist file

  When sort_keys is true (the default) the keys for dictionaries will be written to the plist in sorted order, otherwise they will be written in the iteration order of the dictionary.

  When skipkeys is false (the default) the function raises `TypeError` when a key of a dictionary is not a string, otherwise such keys are skipped.

  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.

  A `TypeError` will be raised if the object is of an unsupported type or a container that contains objects of unsupported types.

  An `OverflowError` will be raised for integer values that cannot be represented in (binary) plist files.

  在 3.4 版被加入.

  在 3.13 版的變更: 新增僅限關鍵字參數 aware_datetime。

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

  Return value as a plist-formatted bytes object. See the documentation for `dump()` for an explanation of the keyword arguments of this function.

  在 3.4 版被加入.

The following classes are available:

class plistlib.UID(data)

  Wraps an `int`. This is used when reading or writing NSKeyedArchiver encoded data, which contains UID (see PList manual).

  data

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

  在 3.8 版被加入.

以下常數可供使用：

plistlib.FMT_XML

  The XML format for plist files.

  在 3.4 版被加入.

plistlib.FMT_BINARY

  The binary format for plist files

  在 3.4 版被加入.

這個模組定義了以下例外：

exception plistlib.InvalidFileException

  當檔案無法被剖析時引發。

  在 3.4 版被加入.

## 範例

Generating a 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())

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