:mod:plistlib --- Generate and parse Mac OS X .plist files

.. module:: plistlib :synopsis: Generate and parse Mac OS X plist files.

.. moduleauthor:: Jack Jansen .. sectionauthor:: Georg Brandl [email protected] .. (harvested from docstrings in the original file)

Source code: :source:Lib/plistlib.py

.. index:: pair: plist; file single: property list

This module provides an interface for reading and writing the "property list" files used mainly by Mac OS X and 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.

To write out and to parse a plist file, use the :func:dump and :func:load functions.

To work with plist data in bytes objects, use :func:dumps and :func:loads.

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries (but only with string keys), :class:Data, :class:bytes, :class:bytesarray or :class:datetime.datetime objects.

.. versionchanged:: 3.4 New API, old API deprecated. Support for binary format plists added.

.. seealso::

PList manual page <https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/>_ Apple's documentation of the file format.

This module defines the following functions:

.. function:: load(fp, *, fmt=None, use_builtin_types=True, dict_type=dict)

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:

• :data:None: Autodetect the file format

• :data:FMT_XML: XML file format

• :data:FMT_BINARY: Binary plist format

If use_builtin_types is true (the default) binary data will be returned as instances of :class:bytes, otherwise it is returned as instances of :class:Data.

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

XML data for the :data:FMT_XML format is parsed using the Expat parser from :mod: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 for the binary format raises :exc:InvalidFileException when the file cannot be parsed.

.. versionadded:: 3.4

.. function:: loads(data, *, fmt=None, use_builtin_types=True, dict_type=dict)

Load a plist from a bytes object. See :func:load for an explanation of the keyword arguments.

.. versionadded:: 3.4

.. function:: dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=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:

• :data:FMT_XML: XML formatted plist file

• :data: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 :exc:TypeError when a key of a dictionary is not a string, otherwise such keys are skipped.

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

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

.. versionadded:: 3.4

.. function:: dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

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

.. versionadded:: 3.4

The following functions are deprecated:

.. function:: readPlist(pathOrFile)

Read a plist file. pathOrFile may be either a file name or a (readable and binary) file object. Returns the unpacked root object (which usually is a dictionary).

This function calls :func:load to do the actual work, see the documentation of :func:that function <load> for an explanation of the keyword arguments.

.. deprecated:: 3.4 Use :func:load instead.

.. versionchanged:: 3.7 Dict values in the result are now normal dicts. You no longer can use attribute access to access items of these dictionaries.

.. function:: writePlist(rootObject, pathOrFile)

Write rootObject to an XML plist file. pathOrFile may be either a file name or a (writable and binary) file object

.. deprecated:: 3.4 Use :func:dump instead.

.. function:: readPlistFromBytes(data)

Read a plist data from a bytes object. Return the root object.

See :func:load for a description of the keyword arguments.

.. deprecated:: 3.4 Use :func:loads instead.

.. versionchanged:: 3.7 Dict values in the result are now normal dicts. You no longer can use attribute access to access items of these dictionaries.

.. function:: writePlistToBytes(rootObject)

Return rootObject as an XML plist-formatted bytes object.

.. deprecated:: 3.4 Use :func:dumps instead.

The following classes are available:

.. class:: Data(data)

Return a "data" wrapper object around the bytes object data. This is used in functions converting from/to plists to represent the <data> type available in plists.

It has one attribute, :attr:data, that can be used to retrieve the Python bytes object stored in it.

.. deprecated:: 3.4 Use a :class:bytes object instead.

The following constants are available:

.. data:: FMT_XML

The XML format for plist files.

.. versionadded:: 3.4

.. data:: FMT_BINARY

The binary format for plist files

.. versionadded:: 3.4

Examples

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

Parsing a plist::

with open(fileName, 'rb') as fp:
    pl = load(fp)
print(pl["aKey"])