:mod:`!plistlib` --- Generate and parse Apple ``.plist`` files
Python 3.14 Docs · نسخهٔ 3.14.10 · PSF License
:mod:!plistlib --- Generate and parse Apple `.plist` files
:synopsis: Generate and parse Apple plist files.
Source code: Lib/plistlib.py
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 dump and load functions.
To work with plist data in bytes or string objects, use dumps and loads.
Values can be strings, integers, floats, booleans, tuples, lists, dictionaries (but only with string keys), bytes, bytearray or datetime.datetime objects.
New API, old API deprecated. Support for binary format plists added.
Support added for reading and writing UID tokens in binary plists as used by NSKeyedArchiver and NSKeyedUnarchiver.
Old API removed.
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:
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:
None: Autodetect the file format
FMT_XML: XML file format
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 aware object <datetime-naive-aware>, with !tzinfo as datetime.UTC`.
XML data for the FMT_XML format 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.
The parser raises InvalidFileException when the file cannot be parsed.
The keyword-only parameter *aware_datetime* has been added.
Load a plist from a bytes or string object. See load for an explanation of the keyword arguments.
*data* can be a string when *fmt* equals FMT_XML.
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:
FMT_XML: XML formatted plist file
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 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 an aware object <datetime-naive-aware>`, it will convert to UTC timezone before writing it.
A TypeError will be raised if the object is of an unsupported type or a container that contains objects of unsupported types.
An OverflowError will be raised for integer values that cannot be represented in (binary) plist files.
The keyword-only parameter *aware_datetime* has been added.
Return *value* as a plist-formatted bytes object. See the documentation for dump for an explanation of the keyword arguments of this function.
The following classes are available:
Wraps an int. This is used when reading or writing NSKeyedArchiver encoded data, which contains UID (see PList manual).
Int value of the UID. It must be in the range `0 <= data < 2**64`.
The following constants are available:
The XML format for plist files.
The binary format for plist files
The module defines the following exceptions:
Raised when a file cannot be parsed.
Examples
Generating a plist::
import datetime as dt 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 = dt.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"])