plistlib: Tools for handling .plist files

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.

class fontTools.misc.plistlib.PlistTarget(use_builtin_types: ~typing.Optional[bool] = None, dict_type: ~typing.Type[~typing.MutableMapping[str, ~typing.Any]] = <class 'dict'>)[source]

Event handler using the ElementTree Target API that can be passed to a XMLParser to produce property list objects from XML. It is based on the CPython plistlib module’s _PlistParser class, but does not use the expat parser.

>>> from fontTools.misc import etree
>>> parser = etree.XMLParser(target=PlistTarget())
>>> result = etree.XML(
...     "<dict>"
...     "    <key>something</key>"
...     "    <string>blah</string>"
...     "</dict>",
...     parser=parser)
>>> result == {"something": "blah"}
True

Links: https://github.com/python/cpython/blob/main/Lib/plistlib.py http://lxml.de/parsing.html#the-target-parser-interface

fontTools.misc.plistlib.dump(value: Union[bool, bytes, Data, datetime, float, Integral, 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. Defaults
pretty_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, Data, datetime, float, Integral, 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. Defaults
pretty_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: ~typing.Optional[bool] = None, dict_type: ~typing.Type[~typing.MutableMapping[str, ~typing.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: ~typing.IO[bytes], use_builtin_types: ~typing.Optional[bool] = None, dict_type: ~typing.Type[~typing.MutableMapping[str, ~typing.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: ~typing.Optional[bool] = None, dict_type: ~typing.Type[~typing.MutableMapping[str, ~typing.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, Data, datetime, float, Integral, 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) → 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 to True 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.