0
  :   	ˆl–ßi~”Ja,jzãb¸&ÔÅ£Ä„h.	Ÿa–Ü4ý('TËmJq@?q \h*bÑ¿Ã ?÷     	# -*- coding: utf-8 -*-
#
# Copyright (c) 2011 Red Hat, Inc.
#
# kitchen is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# kitchen is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with kitchen; if not, see <http://www.gnu.org/licenses/>
#
# Authors:
#   Toshio Kuratomi <toshio@fedoraproject.org>
#   Seth Vidal
#
# Portions of code taken from yum/i18n.py and
# python-fedora: fedora/textutils.py

'''
Functions to handle conversion of byte :class:`str` and :class:`unicode`
strings.

.. versionchanged:: kitchen 0.2a2 ; API kitchen.text 2.0.0
    Added :func:`~kitchen.text.converters.getwriter`

.. versionchanged:: kitchen 0.2.2  ; API kitchen.text 2.1.0
    Added :func:`~kitchen.text.converters.exception_to_unicode`,
    :func:`~kitchen.text.converters.exception_to_bytes`,
    :data:`~kitchen.text.converters.EXCEPTION_CONVERTERS`,
    and :data:`~kitchen.text.converters.BYTE_EXCEPTION_CONVERTERS`

.. versionchanged:: kitchen 1.0.1 ; API kitchen.text 2.1.1
    Deprecated :data:`~kitchen.text.converters.BYTE_EXCEPTION_CONVERTERS` as
    we've simplified :func:`~kitchen.text.converters.exception_to_unicode` and
    :func:`~kitchen.text.converters.exception_to_bytes` to make it unnecessary

'''
try:
    from base64 import b64encode, b64decode
except ImportError:
    from kitchen.pycompat24.base64 import b64encode, b64decode

import codecs
import warnings
import xml.sax.saxutils

# We need to access b_() for localizing our strings but we'll end up with
# a circular import if we import it directly.
import kitchen as k
from kitchen.pycompat24 import sets
sets.add_builtin_set()

from kitchen.text.exceptions import ControlCharError, XmlEncodeError
from kitchen.text.misc import guess_encoding, html_entities_unescape, \
        process_control_chars

#: Aliases for the utf-8 codec
_UTF8_ALIASES = frozenset(('utf-8', 'UTF-8', 'utf8', 'UTF8', 'utf_8', 'UTF_8',
    'utf', 'UTF', 'u8', 'U8'))
#: Aliases for the latin-1 codec
_LATIN1_ALIASES = frozenset(('latin-1', 'LATIN-1', 'latin1', 'LATIN1',
    'latin', 'LATIN', 'l1', 'L1', 'cp819', 'CP819', '8859', 'iso8859-1',
    'ISO8859-1', 'iso-8859-1', 'ISO-8859-1'))

# EXCEPTION_CONVERTERS is defined below due to using to_unicode

def to_unicode(obj, encoding='utf-8', errors='replace', nonstring=None,
        non_string=None):
    '''Convert an object into a :class:`unicode` string

    :arg obj: Object to convert to a :class:`unicode` string.  This should
        normally be a byte :class:`str`
    :kwarg encoding: What encoding to try converting the byte :class:`str` as.
        Defaults to :term:`utf-8`
    :kwarg errors: If errors are found while decoding, perform this action.
        Defaults to ``replace`` which replaces the invalid bytes with
        a character that means the bytes were unable to be decoded.  Other
        values are the same as the error handling schemes in the `codec base
        classes
        <http://docs.python.org/library/codecs.html#codec-base-classes>`_.
        For instance ``strict`` which raises an exception and ``ignore`` which
        simply omits the non-decodable characters.
    :kwarg nonstring: How to treat nonstring values.  Possible values are:

        :simplerepr: Attempt to call the object's "simple representation"
            method and return that value.  Python-2.3+ has two methods that
            try to return a simple representation: :meth:`object.__unicode__`
            and :meth:`object.__str__`.  We first try to get a usable value
            from :meth:`object.__unicode__`.  If that fails we try the sam