1:mod:`plistlib` --- Generate and parse Apple ``.plist`` files
2=============================================================
3
4.. module:: plistlib
5   :synopsis: Generate and parse Apple plist files.
6
7.. moduleauthor:: Jack Jansen
8.. sectionauthor:: Georg Brandl <georg@python.org>
9.. (harvested from docstrings in the original file)
10
11**Source code:** :source:`Lib/plistlib.py`
12
13.. index::
14   pair: plist; file
15   single: property list
16
17--------------
18
19This module provides an interface for reading and writing the "property list"
20files used by Apple, primarily on macOS and iOS. This module supports both binary
21and XML plist files.
22
23The property list (``.plist``) file format is a simple serialization supporting
24basic object types, like dictionaries, lists, numbers and strings.  Usually the
25top level object is a dictionary.
26
27To write out and to parse a plist file, use the :func:`dump` and
28:func:`load` functions.
29
30To work with plist data in bytes objects, use :func:`dumps`
31and :func:`loads`.
32
33Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
34(but only with string keys), :class:`bytes`, :class:`bytearray`
35or :class:`datetime.datetime` objects.
36
37.. versionchanged:: 3.4
38   New API, old API deprecated.  Support for binary format plists added.
39
40.. versionchanged:: 3.8
41   Support added for reading and writing :class:`UID` tokens in binary plists as used
42   by NSKeyedArchiver and NSKeyedUnarchiver.
43
44.. versionchanged:: 3.9
45   Old API removed.
46
47.. seealso::
48
49   `PList manual page <https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/>`_
50      Apple's documentation of the file format.
51
52
53This module defines the following functions:
54
55.. function:: load(fp, *, fmt=None, dict_type=dict)
56
57   Read a plist file. *fp* should be a readable and binary file object.
58   Return the unpacked root object (which usually is a
59   dictionary).
60
61   The *fmt* is the format of the file and the following values are valid:
62
63   * :data:`None`: Autodetect the file format
64
65   * :data:`FMT_XML`: XML file format
66
67   * :data:`FMT_BINARY`: Binary plist format
68
69   The *dict_type* is the type used for dictionaries that are read from the
70   plist file.
71
72   XML data for the :data:`FMT_XML` format is parsed using the Expat parser
73   from :mod:`xml.parsers.expat` -- see its documentation for possible
74   exceptions on ill-formed XML.  Unknown elements will simply be ignored
75   by the plist parser.
76
77   The parser for the binary format raises :exc:`InvalidFileException`
78   when the file cannot be parsed.
79
80   .. versionadded:: 3.4
81
82
83.. function:: loads(data, *, fmt=None, dict_type=dict)
84
85   Load a plist from a bytes object. See :func:`load` for an explanation of
86   the keyword arguments.
87
88   .. versionadded:: 3.4
89
90
91.. function:: dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)
92
93   Write *value* to a plist file. *Fp* should be a writable, binary
94   file object.
95
96   The *fmt* argument specifies the format of the plist file and can be
97   one of the following values:
98
99   * :data:`FMT_XML`: XML formatted plist file
100
101   * :data:`FMT_BINARY`: Binary formatted plist file
102
103   When *sort_keys* is true (the default) the keys for dictionaries will be
104   written to the plist in sorted order, otherwise they will be written in
105   the iteration order of the dictionary.
106
107   When *skipkeys* is false (the default) the function raises :exc:`TypeError`
108   when a key of a dictionary is not a string, otherwise such keys are skipped.
109
110   A :exc:`TypeError` will be raised if the object is of an unsupported type or
111   a container that contains objects of unsupported types.
112
113   An :exc:`OverflowError` will be raised for integer values that cannot
114   be represented in (binary) plist files.
115
116   .. versionadded:: 3.4
117
118
119.. function:: dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)
120
121   Return *value* as a plist-formatted bytes object. See
122   the documentation for :func:`dump` for an explanation of the keyword
123   arguments of this function.
124
125   .. versionadded:: 3.4
126
127
128The following classes are available:
129
130.. class:: UID(data)
131
132   Wraps an :class:`int`.  This is used when reading or writing NSKeyedArchiver
133   encoded data, which contains UID (see PList manual).
134
135   It has one attribute, :attr:`data`, which can be used to retrieve the int value
136   of the UID.  :attr:`data` must be in the range ``0 <= data < 2**64``.
137
138   .. versionadded:: 3.8
139
140
141The following constants are available:
142
143.. data:: FMT_XML
144
145   The XML format for plist files.
146
147   .. versionadded:: 3.4
148
149
150.. data:: FMT_BINARY
151
152   The binary format for plist files
153
154   .. versionadded:: 3.4
155
156
157Examples
158--------
159
160Generating a plist::
161
162    pl = dict(
163        aString = "Doodah",
164        aList = ["A", "B", 12, 32.1, [1, 2, 3]],
165        aFloat = 0.1,
166        anInt = 728,
167        aDict = dict(
168            anotherString = "<hello & hi there!>",
169            aThirdString = "M\xe4ssig, Ma\xdf",
170            aTrueValue = True,
171            aFalseValue = False,
172        ),
173        someData = b"<binary gunk>",
174        someMoreData = b"<lots of binary gunk>" * 10,
175        aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
176    )
177    with open(fileName, 'wb') as fp:
178        dump(pl, fp)
179
180Parsing a plist::
181
182    with open(fileName, 'rb') as fp:
183        pl = load(fp)
184    print(pl["aKey"])
185