<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>1.0.0 Porting Guide — kitchen 1.1.1 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.1.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within kitchen 1.1.1 documentation"
href="_static/opensearch.xml"/>
<link rel="top" title="kitchen 1.1.1 documentation" href="index.html" />
<link rel="next" title="Conventions for contributing to kitchen" href="hacking.html" />
<link rel="prev" title="Exceptions" href="api-exceptions.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="hacking.html" title="Conventions for contributing to kitchen"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="api-exceptions.html" title="Exceptions"
accesskey="P">previous</a> |</li>
<li><a href="index.html">kitchen 1.1.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="porting-guide">
<h1>1.0.0 Porting Guide<a class="headerlink" href="#porting-guide" title="Permalink to this headline">¶</a></h1>
<p>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.</p>
<div class="section" id="python-fedora">
<h2>python-fedora<a class="headerlink" href="#python-fedora" title="Permalink to this headline">¶</a></h2>
<table border="1" class="docutils">
<colgroup>
<col width="45%" />
<col width="55%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>python-fedora</td>
<td>kitchen replacement</td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">fedora.iterutils.isiterable()</span></tt></td>
<td><a class="reference internal" href="api-iterutils.html#kitchen.iterutils.isiterable" title="kitchen.iterutils.isiterable"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.iterutils.isiterable()</span></tt></a> <a class="footnote-reference" href="#f1" id="id1">[1]</a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">fedora.textutils.to_unicode()</span></tt></td>
<td><a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_unicode" title="kitchen.text.converters.to_unicode"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_unicode()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">fedora.textutils.to_bytes()</span></tt></td>
<td><a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_bytes" title="kitchen.text.converters.to_bytes"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_bytes()</span></tt></a></td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="f1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><p class="first"><a class="reference internal" href="api-iterutils.html#kitchen.iterutils.isiterable" title="kitchen.iterutils.isiterable"><tt class="xref py py-func docutils literal"><span class="pre">isiterable()</span></tt></a> has changed slightly in
kitchen. The <tt class="xref py py-attr docutils literal"><span class="pre">include_string</span></tt> attribute has switched its default value
from <a class="reference external" href="http://docs.python.org/library/constants.html#True" title="(in Python v2.7)"><tt class="xref py py-data docutils literal"><span class="pre">True</span></tt></a> to <a class="reference external" href="http://docs.python.org/library/constants.html#False" title="(in Python v2.7)"><tt class="xref py py-data docutils literal"><span class="pre">False</span></tt></a>. So you need to change code like:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="c"># Old code</span>
<span class="gp">>>> </span><span class="n">isiterable</span><span class="p">(</span><span class="s">'abcdef'</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="c"># New code</span>
<span class="gp">>>> </span><span class="n">isiterable</span><span class="p">(</span><span class="s">'abcdef'</span><span class="p">,</span> <span class="n">include_string</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
</td></tr>
</tbody>
</table>
</div>
<div class="section" id="yum">
<h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline">¶</a></h2>
<table border="1" class="docutils">
<colgroup>
<col width="35%" />
<col width="65%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>yum</td>
<td>kitchen replacement</td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.dummy_wrapper()</span></tt></td>
<td><tt class="xref py py-meth docutils literal"><span class="pre">kitchen.i18n.DummyTranslations.ugettext()</span></tt> <a class="footnote-reference" href="#y1" id="id2">[2]</a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.dummyP_wrapper()</span></tt></td>
<td><tt class="xref py py-meth docutils literal"><span class="pre">kitchen.i18n.DummyTanslations.ungettext()</span></tt> <a class="footnote-reference" href="#y1" id="id3">[2]</a></td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.utf8_width()</span></tt></td>
<td><a class="reference internal" href="api-text-display.html#kitchen.text.display.textual_width" title="kitchen.text.display.textual_width"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.display.textual_width()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.utf8_width_chop()</span></tt></td>
<td><a class="reference internal" href="api-text-display.html#kitchen.text.display.textual_width_chop" title="kitchen.text.display.textual_width_chop"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.display.textual_width_chop()</span></tt></a>
and <a class="reference internal" href="api-text-display.html#kitchen.text.display.textual_width" title="kitchen.text.display.textual_width"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.display.textual_width()</span></tt></a> <a class="footnote-reference" href="#y2" id="id4">[3]</a> <a class="footnote-reference" href="#y4" id="id5">[5]</a></td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.utf8_valid()</span></tt></td>
<td><a class="reference internal" href="api-text-misc.html#kitchen.text.misc.byte_string_valid_encoding" title="kitchen.text.misc.byte_string_valid_encoding"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.misc.byte_string_valid_encoding()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.utf8_text_wrap()</span></tt></td>
<td><a class="reference internal" href="api-text-display.html#kitchen.text.display.wrap" title="kitchen.text.display.wrap"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.display.wrap()</span></tt></a> <a class="footnote-reference" href="#y3" id="id6">[4]</a></td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.utf8_text_fill()</span></tt></td>
<td><a class="reference internal" href="api-text-display.html#kitchen.text.display.fill" title="kitchen.text.display.fill"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.display.fill()</span></tt></a> <a class="footnote-reference" href="#y3" id="id7">[4]</a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.to_unicode()</span></tt></td>
<td><a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_unicode" title="kitchen.text.converters.to_unicode"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_unicode()</span></tt></a> <a class="footnote-reference" href="#y5" id="id8">[6]</a></td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.to_unicode_maybe()</span></tt></td>
<td><a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_unicode" title="kitchen.text.converters.to_unicode"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_unicode()</span></tt></a> <a class="footnote-reference" href="#y5" id="id9">[6]</a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.to_utf8()</span></tt></td>
<td><a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_bytes" title="kitchen.text.converters.to_bytes"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_bytes()</span></tt></a> <a class="footnote-reference" href="#y5" id="id10">[6]</a></td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.to_str()</span></tt></td>
<td><a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_unicode" title="kitchen.text.converters.to_unicode"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_unicode()</span></tt></a>
or <a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_bytes" title="kitchen.text.converters.to_bytes"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_bytes()</span></tt></a> <a class="footnote-reference" href="#y6" id="id11">[7]</a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.str_eq()</span></tt></td>
<td><a class="reference internal" href="api-text-misc.html#kitchen.text.misc.str_eq" title="kitchen.text.misc.str_eq"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.misc.str_eq()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.misc.to_xml()</span></tt></td>
<td><a class="reference internal" href="api-text-converters.html#kitchen.text.converters.unicode_to_xml" title="kitchen.text.converters.unicode_to_xml"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.unicode_to_xml()</span></tt></a>
or <a class="reference internal" href="api-text-converters.html#kitchen.text.converters.byte_string_to_xml" title="kitchen.text.converters.byte_string_to_xml"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.byte_string_to_xml()</span></tt></a> <a class="footnote-reference" href="#y7" id="id12">[8]</a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n._()</span></tt></td>
<td>See: <a class="reference internal" href="#yum-i18n-init"><em>Initializing Yum i18n</em></a></td>
</tr>
<tr class="row-even"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.P_()</span></tt></td>
<td>See: <a class="reference internal" href="#yum-i18n-init"><em>Initializing Yum i18n</em></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.exception2msg()</span></tt></td>
<td><a class="reference internal" href="api-text-converters.html#kitchen.text.converters.exception_to_unicode" title="kitchen.text.converters.exception_to_unicode"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.exception_to_unicode()</span></tt></a>
or <tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converter.exception_to_bytes()</span></tt> <a class="footnote-reference" href="#y8" id="id13">[9]</a></td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="y1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> These yum methods provided fallback support for <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a>
functions in case either <tt class="docutils literal"><span class="pre">gaftonmode</span></tt> was set or <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> failed
to return an object. In kitchen, we can use the
<a class="reference internal" href="api-i18n.html#kitchen.i18n.DummyTranslations" title="kitchen.i18n.DummyTranslations"><tt class="xref py py-class docutils literal"><span class="pre">kitchen.i18n.DummyTranslations</span></tt></a> object to fulfill that role.
Please see <a class="reference internal" href="#yum-i18n-init"><em>Initializing Yum i18n</em></a> for more suggestions on how to do this.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="y2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[3]</a></td><td>The yum version of these functions returned a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>. The
kitchen version listed here returns a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string. If you
need a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> simply call
<a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_bytes" title="kitchen.text.converters.to_bytes"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_bytes()</span></tt></a> on the result.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="y3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[4]</td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id7">2</a>)</em> The yum version of these functions would return either a byte
<tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> or a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string depending on what the input
value was. The kitchen version always returns <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="y4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[5]</a></td><td><p class="first"><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.utf8_width_chop()</span></tt> 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:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="c"># Old way</span>
<span class="gp">>>> </span><span class="n">utf8_width_chop</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
<span class="go">(5, 'く ku')</span>
<span class="gp">>>> </span><span class="c"># New way</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">kitchen.text.display</span> <span class="kn">import</span> <span class="n">textual_width</span><span class="p">,</span> <span class="n">textual_width_chop</span>
<span class="gp">>>> </span><span class="p">(</span><span class="n">textual_width</span><span class="p">(</span><span class="n">msg</span><span class="p">),</span> <span class="n">textual_width_chop</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="mi">5</span><span class="p">))</span>
<span class="go">(5, u'く ku')</span>
</pre></div>
</div>
</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="y5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[6]</td><td><em>(<a class="fn-backref" href="#id8">1</a>, <a class="fn-backref" href="#id9">2</a>, <a class="fn-backref" href="#id10">3</a>)</em> <p>If the yum version of <tt class="xref py py-func docutils literal"><span class="pre">to_unicode()</span></tt> or
<tt class="xref py py-func docutils literal"><span class="pre">to_utf8()</span></tt> is given an object that is not a string, it
returns the object itself. <a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_unicode" title="kitchen.text.converters.to_unicode"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_unicode()</span></tt></a> and
<a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_bytes" title="kitchen.text.converters.to_bytes"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.to_bytes()</span></tt></a> default to returning the
<tt class="docutils literal"><span class="pre">simplerepr</span></tt> of the object instead. If you want the yum behaviour, set
the <tt class="xref py py-attr docutils literal"><span class="pre">nonstring</span></tt> parameter to <tt class="docutils literal"><span class="pre">passthru</span></tt>:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">kitchen.text.converters</span> <span class="kn">import</span> <span class="n">to_unicode</span>
<span class="gp">>>> </span><span class="n">to_unicode</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="go">u'5'</span>
<span class="gp">>>> </span><span class="n">to_unicode</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">nonstring</span><span class="o">=</span><span class="s">'passthru'</span><span class="p">)</span>
<span class="go">5</span>
</pre></div>
</div>
</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="y6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id11">[7]</a></td><td><tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.to_str()</span></tt> could return either a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>. or
a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string In kitchen you can get the same effect but you
get to choose whether you want a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> or a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>
string. Use <a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_bytes" title="kitchen.text.converters.to_bytes"><tt class="xref py py-func docutils literal"><span class="pre">to_bytes()</span></tt></a> for <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>
and <a class="reference internal" href="api-text-converters.html#kitchen.text.converters.to_unicode" title="kitchen.text.converters.to_unicode"><tt class="xref py py-func docutils literal"><span class="pre">to_unicode()</span></tt></a> for <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="y7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id12">[8]</a></td><td><tt class="xref py py-func docutils literal"><span class="pre">yum.misc.to_xml()</span></tt> was buggy as written. I think the intention
was for you to be able to pass a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> or <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>
string in and get out a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> that was valid to use in an xml
file. The two kitchen functions
<a class="reference internal" href="api-text-converters.html#kitchen.text.converters.byte_string_to_xml" title="kitchen.text.converters.byte_string_to_xml"><tt class="xref py py-func docutils literal"><span class="pre">byte_string_to_xml()</span></tt></a> and
<a class="reference internal" href="api-text-converters.html#kitchen.text.converters.unicode_to_xml" title="kitchen.text.converters.unicode_to_xml"><tt class="xref py py-func docutils literal"><span class="pre">unicode_to_xml()</span></tt></a> do that for each string
type.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="y8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id13">[9]</a></td><td><p class="first">When porting <tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.exception2msg()</span></tt> to use kitchen, you
should setup two wrapper functions to aid in your port. They’ll look like
this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">kitchen.text.converters</span> <span class="kn">import</span> <span class="n">EXCEPTION_CONVERTERS</span><span class="p">,</span> \
<span class="n">BYTE_EXCEPTION_CONVERTERS</span><span class="p">,</span> <span class="n">exception_to_unicode</span><span class="p">,</span> \
<span class="n">exception_to_bytes</span>
<span class="k">def</span> <span class="nf">exception2umsg</span><span class="p">(</span><span class="n">e</span><span class="p">):</span>
<span class="sd">'''Return a unicode representation of an exception'''</span>
<span class="n">c</span> <span class="o">=</span> <span class="p">[</span><span class="k">lambda</span> <span class="n">e</span><span class="p">:</span> <span class="n">e</span><span class="o">.</span><span class="n">value</span><span class="p">]</span>
<span class="n">c</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">EXCEPTION_CONVERTERS</span><span class="p">)</span>
<span class="k">return</span> <span class="n">exception_to_unicode</span><span class="p">(</span><span class="n">e</span><span class="p">,</span> <span class="n">converters</span><span class="o">=</span><span class="n">c</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">exception2bmsg</span><span class="p">(</span><span class="n">e</span><span class="p">):</span>
<span class="sd">'''Return a utf8 encoded str representation of an exception'''</span>
<span class="n">c</span> <span class="o">=</span> <span class="p">[</span><span class="k">lambda</span> <span class="n">e</span><span class="p">:</span> <span class="n">e</span><span class="o">.</span><span class="n">value</span><span class="p">]</span>
<span class="n">c</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">BYTE_EXCEPTION_CONVERTERS</span><span class="p">)</span>
<span class="k">return</span> <span class="n">exception_to_bytes</span><span class="p">(</span><span class="n">e</span><span class="p">,</span> <span class="n">converters</span><span class="o">=</span><span class="n">c</span><span class="p">)</span>
</pre></div>
</div>
<p class="last">The reason to define this wrapper is that many of the exceptions in yum
put the message in the <tt class="xref py py-attr docutils literal"><span class="pre">value</span></tt> attribute of the <tt class="xref py py-exc docutils literal"><span class="pre">Exception</span></tt>
instead of adding it to the <tt class="xref py py-attr docutils literal"><span class="pre">args</span></tt> attribute. So the default
<a class="reference internal" href="api-text-converters.html#kitchen.text.converters.EXCEPTION_CONVERTERS" title="kitchen.text.converters.EXCEPTION_CONVERTERS"><tt class="xref py py-data docutils literal"><span class="pre">EXCEPTION_CONVERTERS</span></tt></a> don’t know where to
find the message. The wrapper tells kitchen to check the <tt class="xref py py-attr docutils literal"><span class="pre">value</span></tt>
attribute for the message. The reason to define two wrappers may be less
obvious. <tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.exception2msg()</span></tt> can return a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>
string or a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> depending on a combination of what
attributes are present on the <tt class="xref py py-exc docutils literal"><span class="pre">Exception</span></tt> and what locale the
function is being run in. By contrast,
<a class="reference internal" href="api-text-converters.html#kitchen.text.converters.exception_to_unicode" title="kitchen.text.converters.exception_to_unicode"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.exception_to_unicode()</span></tt></a> only returns
<tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings and
<a class="reference internal" href="api-text-converters.html#kitchen.text.converters.exception_to_bytes" title="kitchen.text.converters.exception_to_bytes"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.text.converters.exception_to_bytes()</span></tt></a> only returns byte
<tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>. This is much safer as it keeps code that can only handle
<tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> or only handle byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> correctly from getting
the wrong type when an input changes but it means you need to examine the
calling code when porting from <tt class="xref py py-func docutils literal"><span class="pre">yum.i18n.exception2msg()</span></tt> and use the
appropriate wrapper.</p>
</td></tr>
</tbody>
</table>
<div class="section" id="initializing-yum-i18n">
<span id="yum-i18n-init"></span><h3>Initializing Yum i18n<a class="headerlink" href="#initializing-yum-i18n" title="Permalink to this headline">¶</a></h3>
<p>Previously, yum had several pieces of code to initialize i18n. From the
toplevel of <tt class="file docutils literal"><span class="pre">yum/i18n.py</span></tt>:</p>
<div class="highlight-python"><pre>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</pre>
</div>
<p>With kitchen, this can be changed to this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">kitchen.i18n</span> <span class="kn">import</span> <span class="n">easy_gettext_setup</span><span class="p">,</span> <span class="n">DummyTranslations</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">_</span><span class="p">,</span> <span class="n">P_</span> <span class="o">=</span> <span class="n">easy_gettext_setup</span><span class="p">(</span><span class="s">'yum'</span><span class="p">)</span>
<span class="k">except</span><span class="p">:</span>
<span class="n">translations</span> <span class="o">=</span> <span class="n">DummyTranslations</span><span class="p">()</span>
<span class="n">_</span> <span class="o">=</span> <span class="n">translations</span><span class="o">.</span><span class="n">ugettext</span>
<span class="n">P_</span> <span class="o">=</span> <span class="n">translations</span><span class="o">.</span><span class="n">ungettext</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>In <a class="reference internal" href="unicode-frustrations.html#overcoming-frustration"><em>Overcoming frustration: Correctly using unicode in python2</em></a>, it is mentioned that for some
things (like exception messages), using the byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> oriented
functions is more appropriate. If this is desired, the setup portion is
only a second call to <a class="reference internal" href="api-i18n.html#kitchen.i18n.easy_gettext_setup" title="kitchen.i18n.easy_gettext_setup"><tt class="xref py py-func docutils literal"><span class="pre">kitchen.i18n.easy_gettext_setup()</span></tt></a>:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="n">b_</span><span class="p">,</span> <span class="n">bP_</span> <span class="o">=</span> <span class="n">easy_gettext_setup</span><span class="p">(</span><span class="s">'yum'</span><span class="p">,</span> <span class="n">use_unicode</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
</pre></div>
</div>
</div>
<p>The second place where i18n is setup is in <tt class="xref py py-meth docutils literal"><span class="pre">yum.YumBase._getConfig()</span></tt> in
<tt class="file docutils literal"><span class="pre">yum/__init_.py</span></tt> if <tt class="docutils literal"><span class="pre">gaftonmode</span></tt> is in effect:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">startupconf</span><span class="o">.</span><span class="n">gaftonmode</span><span class="p">:</span>
<span class="k">global</span> <span class="n">_</span>
<span class="n">_</span> <span class="o">=</span> <span class="n">yum</span><span class="o">.</span><span class="n">i18n</span><span class="o">.</span><span class="n">dummy_wrapper</span>
</pre></div>
</div>
<p>This can be changed to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">startupconf</span><span class="o">.</span><span class="n">gaftonmode</span><span class="p">:</span>
<span class="k">global</span> <span class="n">_</span>
<span class="n">_</span> <span class="o">=</span> <span class="n">DummyTranslations</span><span class="p">()</span><span class="o">.</span><span class="n">ugettext</span><span class="p">()</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">1.0.0 Porting Guide</a><ul>
<li><a class="reference internal" href="#python-fedora">python-fedora</a></li>
<li><a class="reference internal" href="#yum">yum</a><ul>
<li><a class="reference internal" href="#initializing-yum-i18n">Initializing Yum i18n</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="api-exceptions.html"
title="previous chapter">Exceptions</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="hacking.html"
title="next chapter">Conventions for contributing to kitchen</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/porting-guide-0.3.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="hacking.html" title="Conventions for contributing to kitchen"
>next</a> |</li>
<li class="right" >
<a href="api-exceptions.html" title="Exceptions"
>previous</a> |</li>
<li><a href="index.html">kitchen 1.1.1 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2011 Red Hat, Inc. and others.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>