plistlib: Tools for handling .plist files¶
-
fontTools.misc.plistlib.
dump
(value: Union[bool, bytes, fontTools.misc.plistlib.Data, datetime.datetime, float, int, Mapping[str, Any], Sequence[Any], str], fp: IO[bytes], sort_keys: bool = True, skipkeys: bool = False, use_builtin_types: Optional[bool] = None, pretty_print: bool = True) → None[source]¶ Write a Python object to a plist file.
- Parameters
value – An object to write.
fp – A file opened for writing.
sort_keys (bool) – Whether keys of dictionaries should be sorted.
skipkeys (bool) – Whether to silently skip non-string dictionary keys.
use_builtin_types (bool) – If true, byte strings will be encoded in Base-64 and wrapped in a
data
tag; if false, they will be either stored as ASCII strings or an exception raised if they cannot be represented. Defaultspretty_print (bool) – Whether to indent the output.
indent_level (int) – Level of indentation when serializing.
- Raises
TypeError – if non-string dictionary keys are serialized and
skipkeys
is false.ValueError – if non-representable binary data is present and use_builtin_types is false.
-
fontTools.misc.plistlib.
dumps
(value: Union[bool, bytes, fontTools.misc.plistlib.Data, datetime.datetime, float, int, Mapping[str, Any], Sequence[Any], str], sort_keys: bool = True, skipkeys: bool = False, use_builtin_types: Optional[bool] = None, pretty_print: bool = True) → bytes[source]¶ Write a Python object to a string in plist format.
- Parameters
value – An object to write.
sort_keys (bool) – Whether keys of dictionaries should be sorted.
skipkeys (bool) – Whether to silently skip non-string dictionary keys.
use_builtin_types (bool) – If true, byte strings will be encoded in Base-64 and wrapped in a
data
tag; if false, they will be either stored as strings or an exception raised if they cannot be represented. Defaultspretty_print (bool) – Whether to indent the output.
indent_level (int) – Level of indentation when serializing.
- Returns
A plist representation of the Python object.
- Return type
string
- Raises
TypeError – if non-string dictionary keys are serialized and
skipkeys
is false.ValueError – if non-representable binary data is present and use_builtin_types is false.
-
fontTools.misc.plistlib.
fromtree
(tree: lxml.etree.Element, use_builtin_types: Optional[bool] = None, dict_type: Type[MutableMapping[str, Any]] = <class 'dict'>) → Any[source]¶ Convert an XML tree to a plist structure.
- Parameters
tree – An
etree
Element
.use_builtin_types – If True, binary data is deserialized to bytes strings. If False, it is wrapped in
Data
objects. Defaults to True if not provided. Deprecated.dict_type – What type to use for dictionaries.
Returns: An object (usually a dictionary).
-
fontTools.misc.plistlib.
load
(fp: IO[bytes], use_builtin_types: Optional[bool] = None, dict_type: Type[MutableMapping[str, Any]] = <class 'dict'>) → Any[source]¶ Load a plist file into an object.
- Parameters
fp – An opened file.
use_builtin_types – If True, binary data is deserialized to bytes strings. If False, it is wrapped in
Data
objects. Defaults to True if not provided. Deprecated.dict_type – What type to use for dictionaries.
- Returns
An object (usually a dictionary) representing the top level of the plist file.
-
fontTools.misc.plistlib.
loads
(value: bytes, use_builtin_types: Optional[bool] = None, dict_type: Type[MutableMapping[str, Any]] = <class 'dict'>) → Any[source]¶ Load a plist file from a string into an object.
- Parameters
value – A bytes string containing a plist.
use_builtin_types – If True, binary data is deserialized to bytes strings. If False, it is wrapped in
Data
objects. Defaults to True if not provided. Deprecated.dict_type – What type to use for dictionaries.
- Returns
An object (usually a dictionary) representing the top level of the plist file.
-
fontTools.misc.plistlib.
totree
(value: Union[bool, bytes, fontTools.misc.plistlib.Data, datetime.datetime, float, int, Mapping[str, Any], Sequence[Any], str], sort_keys: bool = True, skipkeys: bool = False, use_builtin_types: Optional[bool] = None, pretty_print: bool = True, indent_level: int = 1) → lxml.etree.Element[source]¶ Convert a value derived from a plist into an XML tree.
- Parameters
value – Any kind of value to be serialized to XML.
sort_keys – Whether keys of dictionaries should be sorted.
skipkeys (bool) – Whether to silently skip non-string dictionary keys.
use_builtin_types (bool) – If true, byte strings will be encoded in Base-64 and wrapped in a
data
tag; if false, they will be either stored as ASCII strings or an exception raised if they cannot be decoded as such. Defaults toTrue
if not present. Deprecated.pretty_print (bool) – Whether to indent the output.
indent_level (int) – Level of indentation when serializing.
Returns: an
etree
Element
object.- Raises
TypeError – if non-string dictionary keys are serialized and
skipkeys
is false.ValueError – if non-ASCII binary data is present and use_builtin_types is false.
-
class
fontTools.misc.plistlib.
Data
(data: bytes)[source]¶ Represents binary data when
use_builtin_types=False.
This class wraps binary data loaded from a plist file when the
use_builtin_types
argument to the loading function (fromtree()
,load()
,loads()
) is false.The actual binary data is retrieved using the
data
attribute.