# coding:utf-8

"""
Public interface for flanker address (email or url) parsing and validation
capabilities.

Public Functions in flanker.addresslib.address module:

    * parse(address, addr_spec_only=False)

      Parse a single address or URL. Can parse just the address spec or the
      full mailbox.

    * parse_list(address_list, strict=False, as_tuple=False)

      Parse a list of addresses, operates in strict or relaxed modes. Strict
      mode will fail at the first instance of invalid grammar, relaxed modes
      tries to recover and continue.

    * validate_address(addr_spec)

      Validates (parse, plus dns, mx check, and custom grammar) a single
      address spec. In the case of a valid address returns an EmailAddress
      object, otherwise returns None.

    * validate_list(addr_list, as_tuple=False)

      Validates an address list, and returns a tuple of parsed and unparsed
      portions.

When valid addresses are returned, they are returned as an instance of either
EmailAddress or UrlAddress in flanker.addresslib.address.

See the parser.py module for implementation details of the parser.
"""
from logging import getLogger

import idna
import six
from idna import IDNAError
from ply.lex import LexError
from ply.yacc import YaccError
from six.moves.urllib_parse import urlparse
from time import time
from tld import get_tld

from flanker import _email
from flanker.addresslib._parser.lexer import lexer
from flanker.addresslib._parser.parser import (Mailbox, Url, mailbox_parser,
                                               mailbox_or_url_parser,
                                               mailbox_or_url_list_parser,
                                               addr_spec_parser, url_parser)
from flanker.addresslib.quote import smart_unquote, smart_quote
from flanker.addresslib.validate import (mail_exchanger_lookup,
                                         plugin_for_esp)
from flanker.mime.message.headers.encodedword import mime_to_unicode
from flanker.utils import is_pure_ascii, metrics_wrapper

_log = getLogger(__name__)

MAX_ADDRESS_LENGTH = 1024
MAX_ADDRESS_NUMBER = 1024
MAX_ADDRESS_LIST_LENGTH = MAX_ADDRESS_LENGTH * MAX_ADDRESS_NUMBER


@metrics_wrapper()
def parse(address, addr_spec_only=False, strict=False, metrics=False):
    """
    Given a string, returns a scalar object representing a single full
    mailbox (display name and addr-spec), addr-spec, or a url.

    If parsing the entire string fails and strict is not set to True, fall back
    to trying to parse the last word only and assume everything else is the
    display name.

    Returns an Address object and optionally metrics on processing
    time if requested.

    Examples:
        >>> address.parse('John Smith <john@smith.com')
        John Smith <john@smith.com>

        >>> print address.parse('John <john@smith.com>', addr_spec_only=True)
        None

        >>> print address.parse('john@smith.com', addr_spec_only=True)
        'john@smith.com'

        >>> address.parse('http://host.com/post?q')
        http://host.com/post?q

        >>> print address.parse('foo')
        None
    """
    mtimes = {'parsing': 0}
    if addr_spec_only:
        parser = addr_spec_parser
    else:
        parser = mailbox_or_url_parser

    address = _to_parser_input(address)

    # sanity checks
    if not address:
        return None, mtimes
    if len(address) > MAX_ADDRESS_LENGTH:
        _log.warning('address exceeds maximum length of %s', MAX_ADDRESS_LENGTH)
        return None, mtimes

    bstart = time()
    try:
        parse_rs = parser.parse(address.strip(), lexer=lexer.clone())
        addr_obj = _lift_parse_result(parse_rs)
    except (LexError, YaccError, SyntaxError):
        addr_obj = None

    if addr_obj is None and not strict:
        addr_parts = address.split(' ')
        addr_spec = addr_parts[-1]
        if len(addr_spec) < len(address):
            try:
                parse_rs = parser.parse(addr_spec, lexer=lexer.clone())
                addr_obj = _lift_parse_result(parse_rs)
                if addr_obj:
                    display_name = ' '.join(addr_parts[:-1])
                    if isinstance(display_name, six.binary_type):
                        display_name = display_name.decode('utf-8')
                    addr_obj._display_name = display_name

            except (LexError, YaccError, SyntaxError):
                addr_obj = None

    mtimes['parsing'] = time() - bstart
    return addr_obj, mtimes


@metrics_wrapper()
def parse_discrete_list(address_list, as_tuple=False, metrics=False):
    """
    Given an string, returns an AddressList object (an iterable list
    representing parsed email addresses and urls).

    Returns an AddressList object and optionally metrics on processing
    time if requested.

    Examples:
        >>> address.parse_list('A <a@b>')
        [A <a@b>]

        >>> address.parse_list('A <a@b>, C <d@e>')
        [A <a@b>, C <d@e>]

        >>> address.parse_list('A <a@b>, C, D <d@e>')
        None

        >>> address.parse_list('A <a@b>, D <d@e>, http://localhost')
        [A <a@b>, D <d@e>, http://localhost]
    """
    mtimes = {'parsing': 0}

    # Normalize the input to binary for Python 2, and text for Python 3.
    address_list_s = _to_parser_input(address_list)

    # sanity checks
    if not address_list_s:
        return _parse_list_result(as_tuple, AddressList(), [], mtimes)

    if len(address_list_s) > MAX_ADDRESS_LIST_LENGTH:
        _log.warning('address list exceeds maximum length of %s', MAX_ADDRESS_LIST_LENGTH)
        return _parse_list_result(as_tuple, AddressList(), [address_list], mtimes)

    bstart = time()
    try:
        parse_list_rs = mailbox_or_url_list_parser.parse(address_list_s.strip(),
                                                         lexer.clone())
        addr_list_obj, bad_addr_list = _lift_parse_list_result(parse_list_rs)
        if len(addr_list_obj) == 0:
            bad_addr_list.append(address_list_s)

        mtimes['parsing'] = time() - bstart
    except (LexError, YaccError, SyntaxError):
        return _parse_list_result(as_tuple, AddressList(), [address_list], mtimes)

    return _parse_list_result(as_tuple, addr_list_obj, bad_addr_list, mtimes)


@metrics_wrapper()
def parse_list(address_list, strict=False, as_tuple=False, metrics=False):
    """
    Given an string or list of email addresses and/or urls seperated by a
    delimiter (comma (,) or semi-colon (;)), returns an AddressList object
    (an iterable list representing parsed email addresses and urls).

    Given a list of email addresses, the strict parameter is passed to the
    parse call for each element. Given a string the strict parameter is
    ignored.

    The parser can return a list of parsed addresses or a tuple containing
    the parsed and unparsed portions. The parser also returns the parsing
    time metrics if requested.

    Examples:
        >>> address.parse_list('A <a@b>')
        [A <a@b>]

        >>> address.parse_list('A <a@b>, C <d@e>')
        [A <a@b>, C <d@e>]

        >>> address.parse_list('A <a@b>, C, D <d@e>')
        []

        >>> address.parse_list(['A <a@b>', 'C', 'D <d@e>'], as_tuple=True)
        ([A <a@b>, D <d@e>], ['C'])

        >>> address.parse_list('A <a@b>, D <d@e>, http://localhost')
        [A <a@b>, D <d@e>, http://localhost]
    """
    mtimes = {'parsing': 0}

    if not address_list:
        return _parse_list_result(as_tuple, AddressList(), [], mtimes)

    if isinstance(address_list, list):
        if len(address_list) > MAX_ADDRESS_NUMBER:
            _log.warning('address list exceeds maximum items of %s', MAX_ADDRESS_NUMBER)
            return _parse_list_result(as_tuple, AddressList(), [], mtimes)

        parsed, unparsed = AddressList(), []
        for address in address_list:
            if isinstance(address, six.string_types):
                addr_obj, metrics = parse(address, strict=strict, metrics=True)
                mtimes['parsing'] += metrics['parsing']
                if addr_obj:
                    parsed.append(addr_obj)
                else:
                    unparsed.append(address)
            elif isinstance(address, EmailAddress):
                parsed.append(address)
            elif isinstance(address, UrlAddress):
                parsed.append(address)
            else:
                unparsed.append(address)

        return _parse_list_result(as_tuple, parsed, unparsed, mtimes)

    if isinstance(address_list, six.string_types):
        if len(address_list) > MAX_ADDRESS_LIST_LENGTH:
            _log.warning('address list exceeds maximum length of %s', MAX_ADDRESS_LIST_LENGTH)
            return _parse_list_result(as_tuple, AddressList(), [address_list], mtimes)

        if not strict:
            _log.debug('relaxed parsing is not available for discrete lists, ignoring')

        return parse_discrete_list(address_list, as_tuple=as_tuple, metrics=True)

    return _parse_list_result(as_tuple, AddressList(), [address_list], mtimes)


@metrics_wrapper()
def validate_address(addr_spec, metrics=False, skip_remote_checks=False):
    """
    Given an addr-spec, runs the pre-parser, the parser, DNS MX checks,
    MX existence checks, and if available, ESP specific grammar for the
    local part.

    In the case of a valid address returns an EmailAddress object, otherwise
    returns None. If requested, will also return the parsing time metrics.

    Examples:
        >>> address.validate_address('john@non-existent-domain.com')
        None

        >>> address.validate_address('user@gmail.com')
        None

        >>> address.validate_address('user.1234@gmail.com')
        user.1234@gmail.com
    """
    mtimes = {'parsing': 0,
              'tld_lookup': 0,
              'mx_lookup': 0,
              'dns_lookup': 0,
              'mx_conn':0 ,
              'custom_grammar':0}

    # sanity check
    if addr_spec is None:
        return None, mtimes
    if '@' not in addr_spec:
        return None, mtimes

    # run parser against address
    bstart = time()
    paddr = parse(addr_spec, addr_spec_only=True, strict=True)
    mtimes['parsing'] = time() - bstart
    if paddr is None:
        _log.debug('failed parse check for %s', addr_spec)
        return None, mtimes

    # lookup the TLD
    bstart = time()
    tld = get_tld(paddr.hostname, fail_silently=True, fix_protocol=True)
    mtimes['tld_lookup'] = time() - bstart
    if tld is None:
        _log.debug('failed tld check for %s', addr_spec)
        return None, mtimes

    if skip_remote_checks:
        return paddr, mtimes

    # lookup if this domain has a mail exchanger
    exchanger, mx_metrics = mail_exchanger_lookup(paddr.hostname, metrics=True)
    mtimes['mx_lookup'] = mx_metrics['mx_lookup']
    mtimes['dns_lookup'] = mx_metrics['dns_lookup']
    mtimes['mx_conn'] = mx_metrics['mx_conn']
    if exchanger is None:
        _log.debug('failed mx check for %s', addr_spec)
        return None, mtimes

    # lookup custom local-part grammar if it exists
    bstart = time()
    plugin = plugin_for_esp(exchanger)
    mtimes['custom_grammar'] = time() - bstart
    if plugin and plugin.validate(paddr) is False:
        _log.debug('failed custom grammer check for %s/%s', addr_spec, plugin.__name__)
        return None, mtimes

    return paddr, mtimes


@metrics_wrapper()
def validate_list(addr_list, as_tuple=False, metrics=False, skip_remote_checks=False):
    """
    Validates an address list, and returns a tuple of parsed and unparsed
    portions.

    Returns results as a list or tuple consisting of the parsed addresses
    and unparsable protions. If requested, will also return parisng time
    metrics.

    Examples:
        >>> address.validate_address_list('a@mailgun.com, c@mailgun.com')
        [a@mailgun.com, c@mailgun.com]

        >>> address.validate_address_list('a@mailgun.com, b@example.com')
        [a@mailgun.com]

        >>> address.validate_address_list('a@b, c@d, e@example.com', as_tuple=True)
        ([a@mailgun.com, c@mailgun.com], ['e@example.com'])
    """
    mtimes = {'parsing': 0,
              'tld_lookup': 0,
              'mx_lookup': 0,
              'dns_lookup': 0,
              'mx_conn':0 ,
              'custom_grammar':0}

    # sanity check
    if not addr_list:
        return AddressList(), mtimes

    # run parser against address list
    bstart = time()
    parsed_addresses, unparseable = parse_list(addr_list, strict=True, as_tuple=True)
    mtimes['parsing'] = time() - bstart

    plist = AddressList()
    ulist = unparseable

    # validate each address
    for paddr in parsed_addresses:
        vaddr, metrics = validate_address(paddr.address, metrics=True, skip_remote_checks=skip_remote_checks)
        for k in mtimes.keys():
            mtimes[k] += metrics[k]
        if vaddr is None:
            ulist.append(paddr.full_spec())
        else:
            plist.append(paddr)

    if as_tuple:
        return plist, ulist, mtimes
    return plist, mtimes


def is_email(string):
    if parse(string, True):
        return True
    return False


class Address(object):
    """
    Base class that represents an address (email or URL). Use it to create
    concrete instances of different addresses:
    """

    @property
    def supports_routing(self):
        """
        Indicates that by default this address cannot be routed.
        """
        return False

    class Type(object):
        """
        Enumerates the types of addresses we support:
            >>> parse('foo@example.com').addr_type
            'email'

            >>> parse('http://example.com').addr_type
            'url'
        """
        Email = 'email'
        Url   = 'url'


class EmailAddress(Address):
    """
    Represents a fully parsed email address with built-in support for MIME
    encoding. Note, do not use EmailAddress class directly, use the parse()
    or parse_list() functions to return a scalar or iterable list respectively.

    Examples:
       >>> addr = parse("Bob Silva", "bob@host.com")
       >>> addr.address
       'bob@host.com'
       >>> addr.hostname
       'host.com'
       >>> addr.mailbox
       'bob'

    Display name is always returned in Unicode, i.e. ready to be displayed on
    web forms:

       >>> addr.display_name
       u'Bob Silva'

    And full email spec is always returned as a sting encoded for MIME:
       >>> addr.full_spec()
       'Bob Silva <bob@host.com>'
    """

    _addr_type = Address.Type.Email

    def __init__(self, raw_display_name=None, raw_addr_spec=None,
                 _display_name=None, _mailbox=None, _hostname=None):
        raw_display_name = _to_parser_input(raw_display_name)
        raw_addr_spec = _to_parser_input(raw_addr_spec)

        if raw_display_name and raw_addr_spec:
            mailbox = addr_spec_parser.parse(raw_addr_spec, lexer.clone())
            self._display_name = _to_text(raw_display_name)
            self._mailbox = _to_text(mailbox.local_part)
            self._hostname = _to_text(mailbox.domain)

        elif raw_display_name:
            mailbox = mailbox_parser.parse(raw_display_name, lexer.clone())
            self._display_name = _to_text(mailbox.display_name)
            self._mailbox = _to_text(mailbox.local_part)
            self._hostname = _to_text(mailbox.domain)

        elif raw_addr_spec:
            mailbox = addr_spec_parser.parse(raw_addr_spec, lexer.clone())
            self._display_name = u''
            self._mailbox = _to_text(mailbox.local_part)
            self._hostname = _to_text(mailbox.domain)

        elif _mailbox and _hostname:
            self._display_name = _display_name or u''
            self._mailbox = _mailbox
            self._hostname = _hostname

        else:
            raise SyntaxError('failed to create EmailAddress: bad parameters')

        # Convert display name to decoded unicode string.
        if (self._display_name.startswith('=?') and
                self._display_name.endswith('?=')):
            self._display_name = mime_to_unicode(self._display_name)
        if (self._display_name.startswith('"') and
                self._display_name.endswith('"') and
                len(self._display_name) > 2):
            self._display_name = smart_unquote(self._display_name)

        # Convert hostname to lowercase unicode string.
        self._hostname = self._hostname.lower()
        if self._hostname.startswith('xn--') or '.xn--' in self._hostname:
            self._hostname = idna.decode(self._hostname)
        if not is_pure_ascii(self._hostname):
            idna.encode(self._hostname)

        assert isinstance(self._display_name, six.text_type)
        assert isinstance(self._mailbox, six.text_type)
        assert isinstance(self._hostname, six.text_type)

    @property
    def addr_type(self):
        return self._addr_type

    @property
    def display_name(self):
        return self._display_name

    @property
    def ace_display_name(self):
        quoted_display_name = smart_quote(self._display_name)
        encoded_display_name = _email.encode_header(None, quoted_display_name,
                                                    'ascii', MAX_ADDRESS_LENGTH)
        return _to_str(encoded_display_name)

    @property
    def mailbox(self):
        return self._mailbox

    @property
    def hostname(self):
        return self._hostname

    @property
    def ace_hostname(self):
        return _to_str(idna.encode(self._hostname))

    @property
    def address(self):
        return u'{}@{}'.format(self._mailbox, self._hostname)

    @property
    def ace_address(self):
        if not is_pure_ascii(self._mailbox):
            raise ValueError('Address {} has no ASCII-compatable encoding'
                             .format(self.address))
        return _to_str('{}@{}'.format(self._mailbox, self.ace_hostname))

    @property
    def supports_routing(self):
        """
        Email addresses can be routed.
        """
        return True

    def __repr__(self):
        return _to_str(self.to_unicode())

    def __str__(self):
        return _to_str(self.address)

    def __unicode__(self):
        return self.to_unicode()

    def to_unicode(self):
        if self._display_name:
            return u'{} <{}@{}>'.format(smart_quote(self._display_name),
                                        self._mailbox, self._hostname)
        return u'{}@{}'.format(self._mailbox, self._hostname)

    def full_spec(self):
        """
        Returns an ASCII-compatable encoding of an email address or raises a
        ValueError. Display name and domain parts will be converted to
        ASCII-compatable encoding. The transformed address will be ASCII-only
        and RFC-2822 compliant.

           >>> EmailAddress("Ev K", "ev@example.com").full_spec()
           'Ev K <ev@example.com>'
           >>> EmailAddress("Жека", "ev@example.com").full_spec()
           '=?utf-8?b?0JbQtdC60LA=?= <ev@example.com>'
        """
        ace_address = self.ace_address
        if not self.display_name:
            return self.ace_address

        return '{} <{}>'.format(self.ace_display_name, ace_address)

    def contains_non_ascii(self):
        """
        Does the address contain any non-ASCII characters?
        """
        return not is_pure_ascii(self.address)

    def requires_non_ascii(self):
        """
        Can the address be converted to an ASCII compatible encoding?
        """
        if not is_pure_ascii(self.mailbox):
            return True
        if not is_pure_ascii(self.hostname):
            try:
                idna.encode(self.hostname)
            except idna.IDNAError:
                return True
        return False

    def contains_domain_literal(self):
        """
        Is the address a domain literal?
        """
        return self.hostname.startswith('[') and self.hostname.endswith(']')

    def __cmp__(self, other):
        return True

    def __eq__(self, other):
        """
        Allows comparison of two addresses.
        """
        if isinstance(other, six.string_types):
            other = parse(other)
        if other:
            return self.address.lower() == other.address.lower()
        return False

    def __ne__(self, other):
        """
        Negative comparison support
        """
        return not (self == other)

    def __hash__(self):
        """
        Hashing allows using Address objects as keys in collections and compare
        them in sets

            >>> a = Address.from_string("a@host")
            >>> b = Address.from_string("A <A@host>")
            >>> hash(a) == hash(b)
            True
            >>> s = set()
            >>> s.add(a)
            >>> s.add(b)
            >>> len(s)
            1
        """
        return hash(self.address.lower())


class UrlAddress(Address):
    """
    Represents a parsed URL:
        >>> url = parse("http://user@host.com:8080?q=a")
        >>> url.hostname
        'host.com'
        >>> url.port
        8080
        >>> url.scheme
        'http'
        >>> str(url)
        'http://user@host.com:8080?q=a'

    Note: do not create UrlAddress class directly by passing raw "internet
    data", use the parse() and parse_list() functions instead.
    """

    _address = None
    _addr_type = Address.Type.Url

    def __init__(self, raw=None, _address=None):

        if raw:
            raw = _to_parser_input(raw)
            url = url_parser.parse(raw, lexer.clone())
            self._address = urlparse(url.address)
        elif _address:
            self._address = urlparse(_address)
        else:
            raise SyntaxError('failed to create UrlAddress: bad parameters')

    @property
    def address(self):
        return self._address.geturl()

    @property
    def addr_type(self):
        return self._addr_type

    @property
    def hostname(self):
        hostname = self._address.hostname
        if hostname:
            return hostname.lower()
        else:
            return None

    @property
    def port(self):
        return self._address.port

    @property
    def scheme(self):
        return self._address.scheme

    @property
    def path(self):
        return self._address.path

    def __repr__(self):
        return _to_str(self.address)

    def __str__(self):
        return _to_str(self.address)

    def __unicode__(self):
        return self.address

    def to_unicode(self):
        return self.address

    def full_spec(self):
        return self.address

    def __eq__(self, other):
        if isinstance(other, six.string_types):
            other = parse(other)
        if other:
            return self.address == other.address
        return False

    def __hash__(self):
        return hash(self.address)


class AddressList(object):
    """
    Keeps the list of addresses. Each address is an EmailAddress or
    URLAddress objectAddress-derived object.

    To create a list, use the parse_list method, do not create an
    AddressList directly.

    To see if the address is in the list:
        >>> "missing@host.com" in al
        False
        >>> "bob@host.COM" in al
        True
    """

    def __init__(self, container=None):
        self._container = []
        if not container:
            return

        for i, addr in enumerate(container):
            if not isinstance(addr, Address):
                raise TypeError('Unexpected type %s in position %d'
                                % (type(addr), i))
            self._container.append(addr)

    def append(self, addr):
        if not isinstance(addr, Address):
            raise TypeError('Unexpected type %s' % type(addr))
        self._container.append(addr)

    def remove(self, addr):
        self._container.remove(addr)

    def __iter__(self):
        return iter(self._container)

    def __getitem__(self, key):
        return self._container[key]

    def __len__(self):
        return len(self._container)

    def __eq__(self, other):
        """
        When comparing ourselves to other lists we must ignore order.
        """
        if isinstance(other, (list, six.binary_type, six.text_type)):
            other = parse_list(other)
        if not isinstance(other, AddressList):
            raise TypeError('Cannot compare with %s' % type(other))
        return set(self._container) == set(other._container)

    def __repr__(self):
        return _to_str(''.join(['[', self.to_unicode(), ']']))

    def __str__(self):
        return _to_str(', '.join(addr.address for addr in self._container))

    def __unicode__(self):
        return self.to_unicode()

    def __add__(self, other):
        """
        Adding two AddressLists together yields another AddressList.
        """
        if isinstance(other, list):
            other = parse_list(other)

        if not isinstance(other, AddressList):
            raise TypeError('Cannot add %s' % type(other))

        container = self._container + other._container
        addr_lst = AddressList()
        addr_lst._container = container
        return addr_lst

    def full_spec(self, delimiter=', '):
        """
        Returns a full string which looks pretty much what the original was
        like
            >>> adl = AddressList("Foo <foo@host.com>, Bar <bar@host.com>")
            >>> adl.full_spec(delimiter='; ')
            'Foo <foo@host.com; Bar <bar@host.com>'
        """
        return delimiter.join(addr.full_spec() for addr in self._container)

    def to_unicode(self, delimiter=u', '):
        return delimiter.join(addr.to_unicode() for addr in self._container)

    def to_ascii_list(self):
        return [addr.full_spec() for addr in self._container]

    @property
    def addresses(self):
        """
        Returns a list of just addresses, i.e. no names:
            >>> adl = AddressList("Foo <foo@host.com>, Bar <bar@host.com>")
            >>> adl.addresses
            ['foo@host.com', 'bar@host.com']
        """
        return [addr.address for addr in self._container]

    @property
    def hostnames(self):
        """
        Returns a set of hostnames used in addresses in this list.
        """
        return set([addr.hostname for addr in self._container])

    @property
    def addr_types(self):
        """
        Returns a set of address types used in addresses in this list.
        """
        return set([addr.addr_type for addr in self._container])


def _lift_parse_result(parse_rs):
    if isinstance(parse_rs, Mailbox):
        try:
            return EmailAddress(
                _display_name=smart_unquote(_to_text(parse_rs.display_name)),
                _mailbox=_to_text(parse_rs.local_part),
                _hostname=_to_text(parse_rs.domain))
        except (UnicodeError, IDNAError):
            return None

    if isinstance(parse_rs, Url):
        return UrlAddress(_address=_to_text(parse_rs.address))

    return None


def _lift_parse_list_result(parse_list_rs):
    addr_list_obj = AddressList()
    bad_list = []
    for parse_rs in parse_list_rs:
        addr_obj = _lift_parse_result(parse_rs)
        if not addr_obj:
            if isinstance(parse_rs, Mailbox):
                bad_list.append(u'%s@%s' % (_to_text(parse_rs.local_part),
                                            _to_text(parse_rs.domain)))
            continue

        addr_list_obj.append(addr_obj)

    return addr_list_obj, bad_list


def _parse_list_result(as_tuple, parsed, unparsed, mtimes):
    if as_tuple:
        return parsed, unparsed, mtimes

    return parsed, mtimes


def _to_parser_input(parser_in):
    """
    Normalize the input to binary in Python 2, and text in Python 3.
    """
    if parser_in is None:
        return None

    if six.PY2:
        if isinstance(parser_in, six.text_type):
            parser_in = parser_in.encode('utf-8')
        assert isinstance(parser_in, six.binary_type), (
            'Expected %s, got %s' % (six.binary_type, type(parser_in)))
        return parser_in

    if isinstance(parser_in, six.binary_type):
        parser_in = parser_in.decode('utf-8')
    assert isinstance(parser_in, six.text_type), (
        'Expected %s, got %s' % (six.text_type, type(parser_in)))
    return parser_in


def _to_text(val):
    """
    Converts val to unicode in Python 2, and str in Python 3.
    """
    if val is None:
        return None

    if isinstance(val, six.binary_type):
        return val.decode('utf-8')

    if isinstance(val, six.text_type):
        return val

    raise TypeError('String type expected, got %s' % type(val))


def _to_str(val):
    """
    Converts val to str. Note that in different Python version the returned
    value has different semantic, and that is intentional.
    """
    if val is None:
        return None

    if isinstance(val, str):
        return val

    if six.PY2:
        return val.encode('utf-8')

    return val.decode('utf-8')