:mod:`dip.io.codecs`
====================
.. module:: dip.io.codecs

The :mod:`dip.io.codecs` module implements support for specific data
encoders and decoders used with :term:`streaming storage`.


:class:`XmlDecoder`
-------------------
.. class:: XmlDecoder

    Base class: :class:`~dip.model.Model`

    The XmlDecoder class implements an object decoder that decodes a
    :class:`~dip.model.Model` instance from XML.

    .. method:: XmlDecoder.decode(obj, source, location)

        An object is decoded from an XML byte stream.
        
        :param obj:
            is the object to populate from the decoded byte stream.
        :param source:
            is an iterator that will return the byte stream to be decoded.
        :param location:
            is the storage location where the encoded object is being read
            from.  It is mainly used for error reporting.
        :return:
            the decoded object.

    .. method:: XmlDecoder.decode_attribute(obj, reader, source, location)

        Decode the current element as an attribute.
        
        :param obj:
            is the object to populate from the decoded byte stream.
        :param reader:
            is the :class:`~PyQt4.QtCore.QXmlStreamReader` instance.
        :param source:
            is an iterator that will return the byte stream to be decoded.
        :param location:
            is the storage location where the encoded object is being read
            from.  It is mainly used for error reporting.

    .. method:: XmlDecoder.decode_document_element(obj, reader, location)

        Decode the document element (i.e. the outermost element).
        
        :param obj:
            is the object to populate from the decoded byte stream.
        :param reader:
            is the :class:`~PyQt4.QtCore.QXmlStreamReader` instance.
        :param location:
            is the storage location where the encoded object is being read
            from.  It is mainly used for error reporting.

    .. method:: XmlDecoder.decode_model(obj, reader, source, location)

        Decode the next element as a model.
        
        :param obj:
            is the model to populate from the decoded byte stream.
        :param reader:
            is the :class:`~PyQt4.QtCore.QXmlStreamReader` instance.
        :param source:
            is an iterator that will return the byte stream to be decoded.
        :param location:
            is the storage location where the encoded object is being read
            from.  It is mainly used for error reporting.


:class:`XmlEncoder`
-------------------
.. class:: XmlEncoder

    Base class: :class:`~dip.model.Model`

    The XmlEncoder class implements an object encoder that encodes a
    :class:`~dip.model.Model` instance as XML.
    
    Note that, by default, pickle is used to encode any attributes that don't
    have a value corresponding to a fundamental Python type (i.e.
    :class:`~dip.model.Int`, :class:`~dip.model.List` etc.).  It is
    recommended (but not required) that the object is defined fully in terms
    of these fundamental types or that the encoder is sub-classed to handle
    attributes with non-fundamental types explicitly.

    .. attribute:: declaration = Str('<?xml version="1.0" encoding="UTF-8"?>')

        The XML declaration.

    .. attribute:: document_start = Str()

        The text to open the outermost element.

    .. attribute:: document_end = Str('</DipModel>')

        The text to close the outermost element.

    .. attribute:: encoding = Str('utf8')

        The encoding to use.

    .. attribute:: exclude = List(Str())

        The list of names of attributes to exclude.

    .. attribute:: include = List(Str())

        The list of names of attributes to include.  If this is empty then all
        attributes are included unless they have been explicitly excluded.

    .. attribute:: indentation_spaces = Int(2)

        The number of spaces used for a single level of indentation.

    .. method:: XmlEncoder.encode(obj, location)

        An object is encoded as an XML byte stream.
        
        :param obj:
            is the object to encode.
        :param location:
            is the storage location where the encoded object will be written
            to.  It is mainly used for error reporting.
        :return:
            the next section of the encoded XML byte stream.

    .. method:: XmlEncoder.encode_attribute(obj, name, value, attribute_type, location, indent_level)

        A single attribute is encoded as an XML byte stream.
        
        :param obj:
            is the object containing the attribute to encode.
        :param name:
            is the name of the attribute.  It may be '' if the value is a
            member of a collection attribute.
        :param value:
            is the value of the attribute.
        :param attribute_type:
            is the type of the attribute.
        :param location:
            is the storage location where the encoded attribute will be
            written to.  It is mainly used for error reporting.
        :param indent_level:
            is the current indentation level as a number.
        :return:
            the next section of the encoded XML byte stream.

    .. method:: XmlEncoder.encode_model(obj, location, indent_level)

        A model is encoded as an XML byte stream.
        
        :param obj:
            is the model to encode.
        :param location:
            is the storage location where the encoded model will be written
            to.  It is mainly used for error reporting.
        :param indent_level:
            is the current indentation level as a number.

    .. staticmethod:: XmlEncoder.escape(value)

        Replace any characters with their corresponding entities.
        
        :param value:
            is the string to escape.
        :return:
            the escaped string.

    .. method:: XmlEncoder.indentation(indent_level)

        Return a string that will indent a line to a particular level.
        
        :param indent_level:
            is the indentation level as a number.
        :return:
            the string.
