14.5. plistlib — Generate and parse Mac OS X .plist files — Python 3.3.5 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Python »
- 3.3.5 Documentation »
- The Python Standard Library »
- 14. File Formats »

# 14.5. `plistlib` — Generate and parse Mac OS X `.plist` files

Source code: Lib/plistlib.py

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 `writePlist()` and `readPlist()` functions.

To work with plist data in bytes objects, use `writePlistToBytes()` and `readPlistFromBytes()`.

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries (but only with string keys), `Data` or `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 `Data` class. This is a thin wrapper around a Python bytes object. Use `Data` if your strings contain control characters.

See also

PList manual page
  Apple’s documentation of the file format.

This module defines the following functions:

`plistlib.` `readPlist`(pathOrFile)

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

  The XML data 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.

`plistlib.` `writePlist`(rootObject, pathOrFile)

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

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

`plistlib.` `readPlistFromBytes`(data)

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

`plistlib.` `writePlistToBytes`(rootObject)

  Return rootObject as a plist-formatted bytes object.

The following class is available:

class `plistlib.` `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, `data`, that can be used to retrieve the Python bytes object stored in it.

## 14.5.1. 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 = 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)
    print(pl["aKey"])

### Navigation

- index
- modules |
- next |
- previous |
- Python »
- 3.3.5 Documentation »
- The Python Standard Library »
- 14. File Formats »