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. 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, 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. 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: 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 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.

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.