\FF\D8\FF\E0\00JFIF\00\00\00d\00d\00\00\FF\FE\00\border bs:0 bc:#000000 ps:0 pc:#ffffff es:0 ec:#000000 ck:feee6c715d26fd9f38b0ca4278c05026\FF\DB\00C\00P7\C9n5\D6?\BD\9Ds\EBp\9F[`8m\B7)o\B5\E8\E6I\99\FE3]]A2\BA\8Cw\D6E\93\\DEv\C8\009\F2\F1NI?uc\\F5\EA\96k\xN<~buv\EA\C8\D7 \8B\84\CEcxI\BBg\AE\9E=\D6+n\EC\80\C8A\8C\AE\EB\CF\D5\DA\E9"2\A4\B9j5\EB\F3W\B63\96\B30Yu\DA\FC8\ED\DF\E7Ms\FB\F1\8E\B3\FA\EA\E8\E6(\883zs\F2_\8DFk\8Bh \00\8C\DCw\D3R\B5+6X\BA\B2\C4j\AB0\B4\FCMw\C2I\8E\9B\E3\A9~9u\FA\D3l\80\C8%p\EE\FDn2 \00 $\FEj\C4e\A9\DB\~\95\A7\A5\80EK\BB\8DDsP\00@@AD'k\CF\E8\DB\D2(\80\9AK\D3\85\D6lb\F2\BA\8C*\80\00)\95 59\A3R:\F3\CE"\B6\80\88\00\00i1u4\E9\F2\A6\A2\FACM\93WMb*\E0*\00\00\00\00\00(\A8\80\00\00\80\00\00\00\00\00\00\00\00\00\FF\D9 C/// File Manager

File Manager

Path: /lib/python2.7/site-packages/kitchen/text/

Viewing File: utf8.py

# -*- coding: utf-8 -*-
#
# Copyright (c) 2011 Red Hat, Inc.
# Copyright (c) 2010 Ville Skyttä
# Copyright (c) 2009 Tim Lauridsen
# Copyright (c) 2007 Marcus Kuhn
#
# 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:
#   James Antill <james@fedoraproject.org>
#   Marcus Kuhn
#   Toshio Kuratomi <toshio@fedoraproject.org>
#   Tim Lauridsen
#   Ville Skyttä
#
# Portions of this are from yum/i18n.py
'''
-----
UTF-8
-----

Functions for operating on byte :class:`str` encoded as :term:`UTF-8`

.. note::

    In many cases, it is better to convert to :class:`unicode`, operate on the
    strings, then convert back to :term:`UTF-8`.  :class:`unicode` type can
    handle many of these functions itself.  For those that it doesn't
    (removing control characters from length calculations, for instance) the
    code to do so with a :class:`unicode` type is often simpler.

.. warning::

    All of the functions in this module are deprecated.  Most of them have
    been replaced with functions that operate on unicode values in
    :mod:`kitchen.text.display`.  :func:`kitchen.text.utf8.utf8_valid` has
    been replaced with a function in :mod:`kitchen.text.misc`.
'''
import warnings

from kitchen import b_
from kitchen.text.converters import to_unicode, to_bytes
from kitchen.text.misc import byte_string_valid_encoding
from kitchen.text.display import _textual_width_le, \
        byte_string_textual_width_fill, fill, textual_width, \
        textual_width_chop, wrap

#
# Deprecated functions
#

def utf8_valid(msg):
    '''**Deprecated** Detect if a string is valid :term:`utf-8`

    Use :func:`kitchen.text.misc.byte_string_valid_encoding` instead.
    '''
    warnings.warn(b_('kitchen.text.utf8.utf8_valid is deprecated.  Use'
            ' kitchen.text.misc.byte_string_valid_encoding(msg) instead'),
            DeprecationWarning, stacklevel=2)
    return byte_string_valid_encoding(msg)

def utf8_width(msg):
    '''**Deprecated** Get the :term:`textual width` of a :term:`utf-8` string

    Use :func:`kitchen.text.display.textual_width` instead.
    '''
    warnings.warn(b_('kitchen.text.utf8.utf8_width is deprecated.  Use'
        ' kitchen.text.display.textual_width(msg) instead'),
        DeprecationWarning, stacklevel=2)
    return textual_width(msg)


def utf8_width_chop(msg, chop=None):
    '''**Deprecated** Return a string chopped to a given :term:`textual width`

    Use :func:`~kitchen.text.display.textual_width_chop` and
    :func:`~kitchen.text.display.textual_width` instead::

        >>> msg = 'く ku ら ra と to み mi'
        >>> # Old way:
        >>> utf8_width_chop(msg, 5)
        (5, 'く ku')
        >>> # New way
        >>> from kitchen.text.converters import to_bytes
        >>> from kitchen.text.display import textual_width, textual_width_chop
        >>> (textual_width(msg), to_bytes(textual_width_chop(msg, 5)))
        (5, 'く ku')
    '''
    warnings.warn(b_('kitchen.text.utf8.utf8_width_chop is deprecated.  Use'
        ' kitchen.text.display.textual_width_chop instead'), DeprecationWarning,
        stacklevel=2)

    if chop == None:
        return textual_width(msg), msg

    as_bytes = not isinstance(msg, unicode)
 
    chopped_msg = textual_width_chop(msg, chop)
    if as_bytes:
        chopped_msg = to_bytes(chopped_msg)
    return textual_width(chopped_msg), chopped_msg

def utf8_width_fill(msg, fill, chop=None, left=True, prefix='', suffix=''):
    '''**Deprecated** Pad a :term:`utf-8` string to fill a specified width

    Use :func:`~kitchen.text.display.byte_string_textual_width_fill` instead
    '''
    warnings.warn(b_('kitchen.text.utf8.utf8_width_fill is deprecated.  Use'
        ' kitchen.text.display.byte_string_textual_width_fill instead'),
        DeprecationWarning, stacklevel=2)

    return byte_string_textual_width_fill(msg, fill, chop=chop, left=left,
            prefix=prefix, suffix=suffix)

def utf8_text_wrap(text, width=70, initial_indent='', subsequent_indent=''):
    '''**Deprecated** Similar to :func:`textwrap.wrap` but understands
    :term:`utf-8` data and doesn't screw up lists/blocks/etc

    Use :func:`kitchen.text.display.wrap` instead
    '''
    warnings.warn(b_('kitchen.text.utf8.utf8_text_wrap is deprecated.  Use'
        ' kitchen.text.display.wrap instead'),
        DeprecationWarning, stacklevel=2)

    as_bytes = not isinstance(text, unicode)

    text = to_unicode(text)
    lines = wrap(text, width=width, initial_indent=initial_indent,
            subsequent_indent=subsequent_indent)
    if as_bytes:
        lines = [to_bytes(m) for m in lines]

    return lines

def utf8_text_fill(text, *args, **kwargs):
    '''**Deprecated** Similar to :func:`textwrap.fill` but understands
    :term:`utf-8` strings and doesn't screw up lists/blocks/etc.

    Use :func:`kitchen.text.display.fill` instead.
    '''
    warnings.warn(b_('kitchen.text.utf8.utf8_text_fill is deprecated.  Use'
        ' kitchen.text.display.fill instead'),
        DeprecationWarning, stacklevel=2)
    # This assumes that all args. are utf8.
    return fill(text, *args, **kwargs)

def _utf8_width_le(width, *args):
    '''**Deprecated** Convert the arguments to unicode and use
    :func:`kitchen.text.display._textual_width_le` instead.
    '''
    warnings.warn(b_('kitchen.text.utf8._utf8_width_le is deprecated.  Use'
        ' kitchen.text.display._textual_width_le instead'),
        DeprecationWarning, stacklevel=2)
    # This assumes that all args. are utf8.
    return _textual_width_le(width, to_unicode(''.join(args)))

__all__ = ('utf8_text_fill', 'utf8_text_wrap', 'utf8_valid', 'utf8_width',
        'utf8_width_chop', 'utf8_width_fill')