mirror of https://github.com/python/cpython
210 lines
6.1 KiB
ReStructuredText
210 lines
6.1 KiB
ReStructuredText
:mod:`plistlib` --- Generate and parse Apple ``.plist`` files
|
|
=============================================================
|
|
|
|
.. module:: plistlib
|
|
:synopsis: Generate and parse Apple plist files.
|
|
|
|
.. moduleauthor:: Jack Jansen
|
|
.. sectionauthor:: Georg Brandl <georg@python.org>
|
|
.. (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 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.
|
|
|
|
To write out and to parse a plist file, use the :func:`dump` and
|
|
:func:`load` functions.
|
|
|
|
To work with plist data in bytes or string objects, use :func:`dumps`
|
|
and :func:`loads`.
|
|
|
|
Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
|
|
(but only with string keys), :class:`bytes`, :class:`bytearray`
|
|
or :class:`datetime.datetime` objects.
|
|
|
|
.. versionchanged:: 3.4
|
|
New API, old API deprecated. Support for binary format plists added.
|
|
|
|
.. versionchanged:: 3.8
|
|
Support added for reading and writing :class:`UID` tokens in binary plists as used
|
|
by NSKeyedArchiver and NSKeyedUnarchiver.
|
|
|
|
.. versionchanged:: 3.9
|
|
Old API removed.
|
|
|
|
.. seealso::
|
|
|
|
`PList manual page <https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/>`_
|
|
Apple's documentation of the file format.
|
|
|
|
|
|
This module defines the following functions:
|
|
|
|
.. function:: 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:
|
|
|
|
* :data:`None`: Autodetect the file format
|
|
|
|
* :data:`FMT_XML`: XML file format
|
|
|
|
* :data:`FMT_BINARY`: Binary plist format
|
|
|
|
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 :ref:`aware object <datetime-naive-aware>`, with
|
|
:attr:`!tzinfo` as :attr:`datetime.UTC`.
|
|
|
|
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
|
|
|
|
.. versionchanged:: 3.13
|
|
The keyword-only parameter *aware_datetime* has been added.
|
|
|
|
|
|
.. function:: loads(data, *, fmt=None, dict_type=dict, aware_datetime=False)
|
|
|
|
Load a plist from a bytes or string object. See :func:`load` for an
|
|
explanation of the keyword arguments.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. versionchanged:: 3.13
|
|
*data* can be a string when *fmt* equals :data:`FMT_XML`.
|
|
|
|
.. function:: 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:
|
|
|
|
* :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.
|
|
|
|
When *aware_datetime* is true and any field with type ``datetime.datetime``
|
|
is set as a :ref:`aware object <datetime-naive-aware>`, it will convert to
|
|
UTC timezone before writing it.
|
|
|
|
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
|
|
|
|
.. versionchanged:: 3.13
|
|
The keyword-only parameter *aware_datetime* has been added.
|
|
|
|
|
|
.. function:: 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 :func:`dump` for an explanation of the keyword
|
|
arguments of this function.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
|
|
The following classes are available:
|
|
|
|
.. class:: UID(data)
|
|
|
|
Wraps an :class:`int`. This is used when reading or writing NSKeyedArchiver
|
|
encoded data, which contains UID (see PList manual).
|
|
|
|
It has one attribute, :attr:`data`, which can be used to retrieve the int value
|
|
of the UID. :attr:`data` must be in the range ``0 <= data < 2**64``.
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
|
|
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::
|
|
|
|
import datetime
|
|
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 = datetime.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"])
|