1.0.0 Porting Guide¶
The 0.1 through 1.0.0 releases focused on bringing in functions from yum and python-fedora. This porting guide tells how to port from those APIs to their kitchen replacements.
python-fedora¶
python-fedora | kitchen replacement |
fedora.iterutils.isiterable() |
kitchen.iterutils.isiterable() [1] |
fedora.textutils.to_unicode() |
kitchen.text.converters.to_unicode() |
fedora.textutils.to_bytes() |
kitchen.text.converters.to_bytes() |
[1] |
>>> # Old code
>>> isiterable('abcdef')
True
>>> # New code
>>> isiterable('abcdef', include_string=True)
True
|
yum¶
[2] | (1, 2) These yum methods provided fallback support for gettext
functions in case either gaftonmode was set or gettext failed
to return an object. In kitchen, we can use the
kitchen.i18n.DummyTranslations object to fulfill that role.
Please see Initializing Yum i18n for more suggestions on how to do this. |
[3] | The yum version of these functions returned a byte str . The
kitchen version listed here returns a unicode string. If you
need a byte str simply call
kitchen.text.converters.to_bytes() on the result. |
[4] | (1, 2) The yum version of these functions would return either a byte
str or a unicode string depending on what the input
value was. The kitchen version always returns unicode strings. |
[5] |
>>> # Old way
>>> utf8_width_chop(msg, 5)
(5, 'く ku')
>>> # New way
>>> from kitchen.text.display import textual_width, textual_width_chop
>>> (textual_width(msg), textual_width_chop(msg, 5))
(5, u'く ku')
|
[6] | (1, 2, 3) If the yum version of >>> from kitchen.text.converters import to_unicode
>>> to_unicode(5)
u'5'
>>> to_unicode(5, nonstring='passthru')
5
|
[7] | yum.i18n.to_str() could return either a byte str . or
a unicode string In kitchen you can get the same effect but you
get to choose whether you want a byte str or a unicode
string. Use to_bytes() for str
and to_unicode() for unicode . |
[8] | yum.misc.to_xml() was buggy as written. I think the intention
was for you to be able to pass a byte str or unicode
string in and get out a byte str that was valid to use in an xml
file. The two kitchen functions
byte_string_to_xml() and
unicode_to_xml() do that for each string
type. |
[9] | When porting from kitchen.text.converters import EXCEPTION_CONVERTERS, \
BYTE_EXCEPTION_CONVERTERS, exception_to_unicode, \
exception_to_bytes
def exception2umsg(e):
'''Return a unicode representation of an exception'''
c = [lambda e: e.value]
c.extend(EXCEPTION_CONVERTERS)
return exception_to_unicode(e, converters=c)
def exception2bmsg(e):
'''Return a utf8 encoded str representation of an exception'''
c = [lambda e: e.value]
c.extend(BYTE_EXCEPTION_CONVERTERS)
return exception_to_bytes(e, converters=c)
The reason to define this wrapper is that many of the exceptions in yum
put the message in the |
Initializing Yum i18n¶
Previously, yum had several pieces of code to initialize i18n. From the
toplevel of yum/i18n.py
:
try:.
'''
Setup the yum translation domain and make _() and P_() translation wrappers
available.
using ugettext to make sure translated strings are in Unicode.
'''
import gettext
t = gettext.translation('yum', fallback=True)
_ = t.ugettext
P_ = t.ungettext
except:
'''
Something went wrong so we make a dummy _() wrapper there is just
returning the same text
'''
_ = dummy_wrapper
P_ = dummyP_wrapper
With kitchen, this can be changed to this:
from kitchen.i18n import easy_gettext_setup, DummyTranslations
try:
_, P_ = easy_gettext_setup('yum')
except:
translations = DummyTranslations()
_ = translations.ugettext
P_ = translations.ungettext
Note
In Overcoming frustration: Correctly using unicode in python2, it is mentioned that for some
things (like exception messages), using the byte str
oriented
functions is more appropriate. If this is desired, the setup portion is
only a second call to kitchen.i18n.easy_gettext_setup()
:
b_, bP_ = easy_gettext_setup('yum', use_unicode=False)
The second place where i18n is setup is in yum.YumBase._getConfig()
in
yum/__init_.py
if gaftonmode
is in effect:
if startupconf.gaftonmode:
global _
_ = yum.i18n.dummy_wrapper
This can be changed to:
if startupconf.gaftonmode:
global _
_ = DummyTranslations().ugettext()