# plistlib: Tools for handling .plist files

class fontTools.misc.plistlib.Data(data: bytes)

  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'>)

  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

  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

  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

  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

  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

  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

  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.