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

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


:class:`IUnicodeDecoder`
------------------------
.. class:: IUnicodeDecoder

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

    The IUnicodeDecoder interface defines the interface to be implemented
    by models being decoded by the :class:`~dip.io.codecs.UnicodeCodec` codec.

    .. method:: IUnicodeDecoder.set_unicode(model, data)

        Set the model data from an Python v3 str object or a Python v2
        unicode object.
        
        :param model:
            is the model.
        :param data:
            the encoded model data.
        :return:
            the decoded model.  This may be the original model populated from
            the storage location, or it may be a different model (of an
            appropriate type) created from the storage location.


:class:`IUnicodeEncoder`
------------------------
.. class:: IUnicodeEncoder

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

    The IUnicodeEncoder interface defines the interface to be implemented
    by models being encoded by the :class:`~dip.io.codecs.UnicodeCodec` codec.

    .. method:: IUnicodeEncoder.get_unicode(model)

        Return the model data encoded as a Python v3 str object or a Python
        v2 unicode object.
        
        :param model:
            is the model.
        :return:
            the encoded model data.


:class:`UnicodeCodec`
---------------------
.. class:: UnicodeCodec

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

    The UnicodeCodec class implements a codec that decodes and encodes
    models as Unicode.  The codec does not set the
    :attr:`~dip.io.ICodec.format` attribute.  This should be defined in a
    sub-class or passed as an argument when the codec is created.

    .. attribute:: decoder_interface = IUnicodeDecoder

        The decoder interface.

    .. attribute:: encoder_interface = IUnicodeEncoder

        The encoder interface.

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

        The Unicode encoding that is being used.

    .. method:: UnicodeCodec.decode(model, source, location)

        A model is decoded from a byte stream.
        
        :param model:
            is the model.
        :param source:
            is an iterator that will return the byte stream to be decoded.
        :param location:
            is the storage location where the encoded model is being read from.
            It is mainly used for error reporting.
        :return:
            the decoded model.  This may be the original model populated from
            the storage location, or it may be a different model (of an
            appropriate type) created from the storage location.

    .. method:: UnicodeCodec.encode(model, location)

        A model is encoded as a byte stream.
        
        :param model:
            is the model.
        :param location:
            is the storage location where the encoded model will be written to.
            It is mainly used for error reporting.
        :return:
            a generator that will return sections of the encoded byte stream.