python-clinic / Doc / library / plistlib.rst

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

Source code: :source:`Lib/`

This module provides an interface for reading and writing the "property list" XML files used mainly by Mac OS X.

The property list (.plist) file format is a simple XML pickle 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:`writePlist` and :func:`readPlist` functions.

To work with plist data in bytes objects, use :func:`writePlistToBytes` and :func:`readPlistFromBytes`.

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries (but only with string keys), :class:`Data` or :class:`datetime.datetime` objects. String values (including dictionary keys) have to be unicode strings -- they will be written out as UTF-8.

The <data> plist type is supported through the :class:`Data` class. This is a thin wrapper around a Python bytes object. Use :class:`Data` if your strings contain control characters.

This module defines the following functions:

The following class is available:

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.


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 = Data(b"<binary gunk>"),
    someMoreData = Data(b"<lots of binary gunk>" * 10),
    aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
writePlist(pl, fileName)

Parsing a plist:

pl = readPlist(pathOrFile)