Source code for dictdumper.plist

# -*- coding: utf-8 -*-
"""dumper a PLIST file

:mod:`dictdumper.plist` contains :class:`~dictdumper.plist.PLIST`
only, which dumpers an Apple property list (PLIST) file. Usage
sample is described as below.

.. code:: python

    >>> dumper = PLIST(file_name)
    >>> dumper(content_dict_1, name=content_name_1)
    >>> dumper(content_dict_2, name=content_name_2)
    ............

"""
# Dumper for PLIST files
# Write a macOS Property List file

import base64
import datetime
import os
from xml.sax.saxutils import escape

from dictdumper._types import bytes_type, str_type
from dictdumper.xml import XML

__all__ = ['PLIST']

#: PLIST head string.
_HEADER_START = '''\
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
'''

#: PLIST tail string.
_HEADER_END = '''\
</dict>
</plist>
'''


[docs] def encode_xml(value): """Escape ``value`` for use as XML character data. Args: value (Any): object to escape, converted to :obj:`str` beforehand should it not be one already Returns: str: The escaped text, with ``&``, ``<`` and ``>`` replaced by the corresponding XML entity references. Notes: Both mapping keys and string values are escaped through this function, so that a key is always written exactly as the string beside it would be. """ return escape(value if isinstance(value, str_type) else str_type(value))
[docs] def _format_date(value): """Render ``value`` in the property list ``<date>`` format. Args: value (Union[datetime.date, datetime.datetime]): date to render Returns: str: The date as ``YYYY-MM-DDThh:mm:ssZ``. Notes: The format carries whole seconds only, so microseconds on ``value`` are discarded; this is the same rendering :func:`plistlib.dump` produces. A :obj:`datetime.date` has no time of day and is rendered at midnight. The fields are formatted rather than passed through :meth:`~datetime.date.strftime` because ``%Y`` is not guaranteed to be zero padded, and the reader requires a four digit year. """ if isinstance(value, datetime.datetime): clock = (value.hour, value.minute, value.second) else: clock = (0, 0, 0) return '{0:04d}-{1:02d}-{2:02d}T{3:02d}:{4:02d}:{5:02d}Z'.format( value.year, value.month, value.day, *clock)
[docs] class PLIST(XML): """Dump Apple property list (PLIST) format file. .. code:: python >>> dumper = PLIST(file_name) >>> dumper(content_dict_1, name=content_name_1) >>> dumper(content_dict_2, name=content_name_2) ............ Attributes: _file (str): output file name _sptr (int): indicates start of appending point (file pointer) _tctr (int): tab level counter _hsrt (str): start string (:data:`~dictdumper.plist._HEADER_START`) _hend (str): end string (:data:`~dictdumper.plist._HEADER_END`) .. note:: Terminology: .. code:: value ::= array | dict | string | data | date | integer | real | bool array ::= "<array>" value* "</array>" dict ::= "<dict>" ("<key>" str "</key>" value)* "</dict>" string ::= "<string>" str "</string>" data ::= "<data>" bytes "</data>" date ::= "<date>" datetime "</date>" integer ::= "<integer>" int "</integer>" real ::= "<real>" float "</real>" bool ::= "<true/>" | "<false/>" """ ########################################################################## # Properties. ########################################################################## @property def kind(self): """File format of current dumper. :rtype: Literal['plist'] """ return 'plist' ########################################################################## # Type codes. ########################################################################## #: Tuple[Tuple[type, str]]: Type codes. __type__ = ( # string (str_type, 'string'), # bool (bool, 'bool'), # dict (dict, 'dict'), # date (datetime.date, 'date'), (datetime.datetime, 'date'), # integer (int, 'integer'), # real (float, 'real'), # data (bytes_type, 'data'), # array (list, 'array'), ) ########################################################################## # Attributes. ########################################################################## #: PLIST head string. _hsrt = _HEADER_START #: PLIST tail string. _hend = _HEADER_END ########################################################################## # Utilities. ##########################################################################
[docs] def _encode_value(self, o): # pylint: disable=unused-argument """Check content type for function call. Args: o (Any): object to convert Returns: Any: the converted object See Also: The function is a direct wrapper for :meth:`~dictdumper.dumper.Dumper.object_hook`. Notes: The function will by default converts :obj:`bytearray`, ``None``, :obj:`memoryview`, :obj:`tuple`, :obj:`set`, :obj:`frozenset` to PLIST serialisable data. """ if o is None: return self.make_object(o, 'None') if isinstance(o, bytearray): return self.make_object(o, bytes_type(o)) if isinstance(o, memoryview): return self.make_object(o, o.tobytes()) if isinstance(o, (tuple, set, frozenset)): return self.make_object(o, list(o)) return self.object_hook(o)
[docs] def _append_value(self, value, file, name): """Call this function to write contents. Args: value (Dict[str, Any]): content to be dumped file (io.TextIOWrapper): output file name (str): name of current content block """ tabs = '\t' * self._tctr keys = '{tabs}<key>{name}</key>\n'.format(tabs=tabs, name=encode_xml(name)) file.seek(self._sptr, os.SEEK_SET) file.write(keys) self._append_dict(value, file)
########################################################################## # Functions. ##########################################################################
[docs] def _append_dict(self, value, file): """Call this function to write dict contents. Args: value (Dict[str, Any]): content to be dumped file (io.TextIOWrapper): output file """ tabs = '\t' * self._tctr labs = '{tabs}<dict>\n'.format(tabs=tabs) file.write(labs) self._tctr += 1 for (item, text) in value.items(): if text is None: continue tabs = '\t' * self._tctr keys = '{tabs}<key>{item}</key>\n'.format(tabs=tabs, item=encode_xml(item)) file.write(keys) enc_text = self._encode_value(text) func = self._encode_func(enc_text) func(enc_text, file) self._tctr -= 1 tabs = '\t' * self._tctr labs = '{tabs}</dict>\n'.format(tabs=tabs) file.write(labs)
[docs] def _append_array(self, value, file): """Call this function to write array contents. Args: value (List[Any]): content to be dumped file (io.TextIOWrapper): output file """ tabs = '\t' * self._tctr labs = '{tabs}<array>\n'.format(tabs=tabs) file.write(labs) self._tctr += 1 for item in value: if item is None: continue enc_text = self._encode_value(item) func = self._encode_func(enc_text) func(enc_text, file) self._tctr -= 1 tabs = '\t' * self._tctr labs = '{tabs}</array>\n'.format(tabs=tabs) file.write(labs)
[docs] def _append_string(self, value, file): """Call this function to write string contents. Args: value (str): content to be dumped file (io.TextIOWrapper): output file """ tabs = '\t' * self._tctr text = encode_xml(value) labs = '{tabs}<string>{text}</string>\n'.format(tabs=tabs, text=text) file.write(labs)
[docs] def _append_data(self, value, file): """Call this function to write data contents. Args: value (bytes): content to be dumped file (io.TextIOWrapper): output file """ # binascii.b2a_base64(value) -> plistlib.Data # binascii.a2b_base64(Data) -> value(bytes) tabs = '\t' * self._tctr text = base64.b64encode(value).decode() labs = '{tabs}<data>{text}</data>\n'.format(tabs=tabs, text=text) file.write(labs)
[docs] def _append_date(self, value, file): """Call this function to write date contents. Args: value (Union[datetime.date, datetime.datetime]): content to be dumped file (io.TextIOWrapper): output file Notes: A property list ``<date>`` carries whole seconds only, so any microseconds on ``value`` are discarded -- the same thing :func:`plistlib.dump` does. Callers needing sub-second precision have to record it in a field of their own. """ tabs = '\t' * self._tctr text = _format_date(value) labs = '{tabs}<date>{text}</date>\n'.format(tabs=tabs, text=text) file.write(labs)
[docs] def _append_integer(self, value, file): """Call this function to write integer contents. Args: value (int): content to be dumped file (io.TextIOWrapper): output file """ tabs = '\t' * self._tctr text = value labs = '{tabs}<integer>{text}</integer>\n'.format(tabs=tabs, text=text) file.write(labs)
[docs] def _append_real(self, value, file): """Call this function to write real contents. Args: value (float): content to be dumped file (io.TextIOWrapper): output file """ tabs = '\t' * self._tctr text = value labs = '{tabs}<real>{text}</real>\n'.format(tabs=tabs, text=text) file.write(labs)
[docs] def _append_bool(self, value, file): """Call this function to write bool contents. Args: value (bool): content to be dumped file (io.TextIOWrapper): output file """ tabs = '\t' * self._tctr text = '<true/>' if value else '<false/>' labs = '{tabs}{text}\n'.format(tabs=tabs, text=text) file.write(labs)