EVOLUTION-MANAGER

Edit File: porting-guide-0.3.txt

=================== 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 ----------------------------------- ------------------- :func:`fedora.iterutils.isiterable` :func:`kitchen.iterutils.isiterable` [#f1]_ :func:`fedora.textutils.to_unicode` :func:`kitchen.text.converters.to_unicode` :func:`fedora.textutils.to_bytes` :func:`kitchen.text.converters.to_bytes` =================================== =================== .. [#f1] :func:`~kitchen.iterutils.isiterable` has changed slightly in kitchen. The :attr:`include_string` attribute has switched its default value from :data:`True` to :data:`False`. So you need to change code like:: >>> # Old code >>> isiterable('abcdef') True >>> # New code >>> isiterable('abcdef', include_string=True) True --- yum --- ================================= =================== yum kitchen replacement --------------------------------- ------------------- :func:`yum.i18n.dummy_wrapper` :meth:`kitchen.i18n.DummyTranslations.ugettext` [#y1]_ :func:`yum.i18n.dummyP_wrapper` :meth:`kitchen.i18n.DummyTanslations.ungettext` [#y1]_ :func:`yum.i18n.utf8_width` :func:`kitchen.text.display.textual_width` :func:`yum.i18n.utf8_width_chop` :func:`kitchen.text.display.textual_width_chop` and :func:`kitchen.text.display.textual_width` [#y2]_ [#y4]_ :func:`yum.i18n.utf8_valid` :func:`kitchen.text.misc.byte_string_valid_encoding` :func:`yum.i18n.utf8_text_wrap` :func:`kitchen.text.display.wrap` [#y3]_ :func:`yum.i18n.utf8_text_fill` :func:`kitchen.text.display.fill` [#y3]_ :func:`yum.i18n.to_unicode` :func:`kitchen.text.converters.to_unicode` [#y5]_ :func:`yum.i18n.to_unicode_maybe` :func:`kitchen.text.converters.to_unicode` [#y5]_ :func:`yum.i18n.to_utf8` :func:`kitchen.text.converters.to_bytes` [#y5]_ :func:`yum.i18n.to_str` :func:`kitchen.text.converters.to_unicode` or :func:`kitchen.text.converters.to_bytes` [#y6]_ :func:`yum.i18n.str_eq` :func:`kitchen.text.misc.str_eq` :func:`yum.misc.to_xml` :func:`kitchen.text.converters.unicode_to_xml` or :func:`kitchen.text.converters.byte_string_to_xml` [#y7]_ :func:`yum.i18n._` See: :ref:`yum-i18n-init` :func:`yum.i18n.P_` See: :ref:`yum-i18n-init` :func:`yum.i18n.exception2msg` :func:`kitchen.text.converters.exception_to_unicode` or :func:`kitchen.text.converter.exception_to_bytes` [#y8]_ ================================= =================== .. [#y1] These yum methods provided fallback support for :mod:`gettext` functions in case either ``gaftonmode`` was set or :mod:`gettext` failed to return an object. In kitchen, we can use the :class:`kitchen.i18n.DummyTranslations` object to fulfill that role. Please see :ref:`yum-i18n-init` for more suggestions on how to do this. .. [#y2] The yum version of these functions returned a byte :class:`str`. The kitchen version listed here returns a :class:`unicode` string. If you need a byte :class:`str` simply call :func:`kitchen.text.converters.to_bytes` on the result. .. [#y3] The yum version of these functions would return either a byte :class:`str` or a :class:`unicode` string depending on what the input value was. The kitchen version always returns :class:`unicode` strings. .. [#y4] :func:`yum.i18n.utf8_width_chop` performed two functions. It returned the piece of the message that fit in a specified width and the width of that message. In kitchen, you need to call two functions, one for each action:: >>> # 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') .. [#y5] If the yum version of :func:`~yum.i18n.to_unicode` or :func:`~yum.i18n.to_utf8` is given an object that is not a string, it returns the object itself. :func:`kitchen.text.converters.to_unicode` and :func:`kitchen.text.converters.to_bytes` default to returning the ``simplerepr`` of the object instead. If you want the yum behaviour, set the :attr:`nonstring` parameter to ``passthru``:: >>> from kitchen.text.converters import to_unicode >>> to_unicode(5) u'5' >>> to_unicode(5, nonstring='passthru') 5 .. [#y6] :func:`yum.i18n.to_str` could return either a byte :class:`str`. or a :class:`unicode` string In kitchen you can get the same effect but you get to choose whether you want a byte :class:`str` or a :class:`unicode` string. Use :func:`~kitchen.text.converters.to_bytes` for :class:`str` and :func:`~kitchen.text.converters.to_unicode` for :class:`unicode`. .. [#y7] :func:`yum.misc.to_xml` was buggy as written. I think the intention was for you to be able to pass a byte :class:`str` or :class:`unicode` string in and get out a byte :class:`str` that was valid to use in an xml file. The two kitchen functions :func:`~kitchen.text.converters.byte_string_to_xml` and :func:`~kitchen.text.converters.unicode_to_xml` do that for each string type. .. [#y8] When porting :func:`yum.i18n.exception2msg` to use kitchen, you should setup two wrapper functions to aid in your port. They'll look like this: .. code-block:: python 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 :attr:`value` attribute of the :exc:`Exception` instead of adding it to the :attr:`args` attribute. So the default :data:`~kitchen.text.converters.EXCEPTION_CONVERTERS` don't know where to find the message. The wrapper tells kitchen to check the :attr:`value` attribute for the message. The reason to define two wrappers may be less obvious. :func:`yum.i18n.exception2msg` can return a :class:`unicode` string or a byte :class:`str` depending on a combination of what attributes are present on the :exc:`Exception` and what locale the function is being run in. By contrast, :func:`kitchen.text.converters.exception_to_unicode` only returns :class:`unicode` strings and :func:`kitchen.text.converters.exception_to_bytes` only returns byte :class:`str`. This is much safer as it keeps code that can only handle :class:`unicode` or only handle byte :class:`str` correctly from getting the wrong type when an input changes but it means you need to examine the calling code when porting from :func:`yum.i18n.exception2msg` and use the appropriate wrapper. .. _yum-i18n-init: Initializing Yum i18n ===================== Previously, yum had several pieces of code to initialize i18n. From the toplevel of :file:`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 :ref:`overcoming-frustration`, it is mentioned that for some things (like exception messages), using the byte :class:`str` oriented functions is more appropriate. If this is desired, the setup portion is only a second call to :func:`kitchen.i18n.easy_gettext_setup`:: b_, bP_ = easy_gettext_setup('yum', use_unicode=False) The second place where i18n is setup is in :meth:`yum.YumBase._getConfig` in :file:`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()