plistlib: Tools for handling .plist files

class fontTools.misc.plistlib.Data(data: bytes)[source]

Bases: object

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: bool | None = None, dict_type: ~typing.Type[~typing.MutableMapping[str, ~typing.Any]] = <class 'dict'>)[source]

Bases: object

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.totree(value: bool | bytes | Data | datetime | float | Integral | Mapping[str, Any] | Sequence[Any] | str, sort_keys: bool = True, skipkeys: bool = False, use_builtin_types: bool | None = 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.

fontTools.misc.plistlib.fromtree(tree: ~lxml.etree.Element, use_builtin_types: bool | None = 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: bool | None = 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: bool | None = 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.dump(value: 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: bool | None = 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: bool | bytes | Data | datetime | float | Integral | Mapping[str, Any] | Sequence[Any] | str, sort_keys: bool = True, skipkeys: bool = False, use_builtin_types: bool | None = 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.