D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
share
/
doc
/
python-kitchen-1.1.1
/
html
/
Filename :
api-text-display.html
back
Copy
<!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>Format Text for Display — 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="up" title="Kitchen.text: unicode and utf8 and xml oh my!" href="api-text.html" /> <link rel="next" title="Miscellaneous functions for manipulating text" href="api-text-misc.html" /> <link rel="prev" title="Kitchen.text.converters" href="api-text-converters.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="api-text-misc.html" title="Miscellaneous functions for manipulating text" accesskey="N">next</a> |</li> <li class="right" > <a href="api-text-converters.html" title="Kitchen.text.converters" accesskey="P">previous</a> |</li> <li><a href="index.html">kitchen 1.1.1 documentation</a> »</li> <li><a href="api-overview.html" >Kitchen API</a> »</li> <li><a href="api-text.html" accesskey="U">Kitchen.text: unicode and utf8 and xml oh my!</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <span class="target" id="module-kitchen.text.display"></span><div class="section" id="format-text-for-display"> <h1>Format Text for Display<a class="headerlink" href="#format-text-for-display" title="Permalink to this headline">¶</a></h1> <p>Functions related to displaying unicode text. Unicode characters don’t all have the same width so we need helper functions for displaying them.</p> <p class="versionadded"> <span class="versionmodified">New in version 0.2: </span>kitchen.display API 1.0.0</p> </div> <dl class="function"> <dt id="kitchen.text.display.textual_width"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">textual_width</tt><big>(</big><em>msg</em>, <em>control_chars='guess'</em>, <em>encoding='utf-8'</em>, <em>errors='replace'</em><big>)</big><a class="headerlink" href="#kitchen.text.display.textual_width" title="Permalink to this definition">¶</a></dt> <dd><p>Get the <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> of a string</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>msg</strong> – <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string or byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to get the width of</li> <li><strong>control_chars</strong> – <p>specify how to deal with <a class="reference internal" href="glossary.html#term-control-characters"><em class="xref std std-term">control characters</em></a>. Possible values are:</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">guess:</th><td class="field-body">(default) will take a guess for <a class="reference internal" href="glossary.html#term-control-character"><em class="xref std std-term">control character</em></a> widths. Most codes will return zero width. <tt class="docutils literal"><span class="pre">backspace</span></tt>, <tt class="docutils literal"><span class="pre">delete</span></tt>, and <tt class="docutils literal"><span class="pre">clear</span> <span class="pre">delete</span></tt> return -1. <tt class="docutils literal"><span class="pre">escape</span></tt> currently returns -1 as well but this is not guaranteed as it’s not always correct</td> </tr> <tr class="field-even field"><th class="field-name">strict:</th><td class="field-body">will raise <a class="reference internal" href="api-exceptions.html#kitchen.text.exceptions.ControlCharError" title="kitchen.text.exceptions.ControlCharError"><tt class="xref py py-exc docutils literal"><span class="pre">kitchen.text.exceptions.ControlCharError</span></tt></a> if a <a class="reference internal" href="glossary.html#term-control-character"><em class="xref std std-term">control character</em></a> is encountered</td> </tr> </tbody> </table> </li> <li><strong>encoding</strong> – If we are given a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> this is used to decode it into <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string. Any characters that are not decodable in this encoding will get a value dependent on the <tt class="xref py py-attr docutils literal"><span class="pre">errors</span></tt> parameter.</li> <li><strong>errors</strong> – How to treat errors encoding the byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string. Legal values are the same as for <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>. The default value of <tt class="docutils literal"><span class="pre">replace</span></tt> will cause undecodable byte sequences to have a width of one. <tt class="docutils literal"><span class="pre">ignore</span></tt> will have a width of zero.</li> </ul> </td> </tr> <tr class="field-odd field"><th class="field-name" colspan="2">Raises ControlCharError:</th></tr> <tr class="field-odd field"><td> </td><td class="field-body"><p class="first">if <tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt> contains a <a class="reference internal" href="glossary.html#term-control-character"><em class="xref std std-term">control character</em></a> and <tt class="xref py py-attr docutils literal"><span class="pre">control_chars</span></tt> is <tt class="docutils literal"><span class="pre">strict</span></tt>.</p> </td> </tr> <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">Textual width</em></a> of the <tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt>. This is the amount of space that the string will consume on a monospace display. It’s measured in the number of cell positions or columns it will take up on a monospace display. This is <strong>not</strong> the number of glyphs that are in the string.</p> </td> </tr> </tbody> </table> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">This function can be wrong sometimes because Unicode does not specify a strict width value for all of the <a class="reference internal" href="glossary.html#term-code-points"><em class="xref std std-term">code points</em></a>. In particular, we’ve found that some Tamil characters take up to four character cells but we return a lesser amount.</p> </div> </dd></dl> <dl class="function"> <dt id="kitchen.text.display.textual_width_chop"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">textual_width_chop</tt><big>(</big><em>msg</em>, <em>chop</em>, <em>encoding='utf-8'</em>, <em>errors='replace'</em><big>)</big><a class="headerlink" href="#kitchen.text.display.textual_width_chop" title="Permalink to this definition">¶</a></dt> <dd><p>Given a string, return it chopped to a given <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a></p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>msg</strong> – <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string or byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to chop</li> <li><strong>chop</strong> – Chop <tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt> if it exceeds this <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a></li> <li><strong>encoding</strong> – If we are given a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>, this is used to decode it into a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string. Any characters that are not decodable in this encoding will be assigned a width of one.</li> <li><strong>errors</strong> – How to treat errors encoding the byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>. Legal values are the same as for <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></li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first"><tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string</p> </td> </tr> <tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string of the <tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt> chopped at the given <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a></p> </td> </tr> </tbody> </table> <p>This is what you want to use instead of <tt class="docutils literal"><span class="pre">%.*s</span></tt>, as it does the “right” thing with regard to <a class="reference internal" href="glossary.html#term-utf-8"><em class="xref std std-term">UTF-8</em></a> sequences, <a class="reference internal" href="glossary.html#term-control-characters"><em class="xref std std-term">control characters</em></a>, and characters that take more than one cell position. Eg:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="c"># Wrong: only displays 8 characters because it is operating on bytes</span> <span class="gp">>>> </span><span class="k">print</span> <span class="s">"</span><span class="si">%.*s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="s">'café ñunru!'</span><span class="p">)</span> <span class="go">café ñun</span> <span class="gp">>>> </span><span class="c"># Properly operates on graphemes</span> <span class="gp">>>> </span><span class="s">'</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">textual_width_chop</span><span class="p">(</span><span class="s">'café ñunru!'</span><span class="p">,</span> <span class="mi">10</span><span class="p">))</span> <span class="go">café ñunru</span> <span class="gp">>>> </span><span class="c"># takes too many columns because the kanji need two cell positions</span> <span class="gp">>>> </span><span class="k">print</span> <span class="s">'1234567890</span><span class="se">\n</span><span class="si">%.*s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="s">u'一二三四五六七八九十'</span><span class="p">)</span> <span class="go">1234567890</span> <span class="go">一二三四五六七八九十</span> <span class="gp">>>> </span><span class="c"># Properly chops at 10 columns</span> <span class="gp">>>> </span><span class="k">print</span> <span class="s">'1234567890</span><span class="se">\n</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">textual_width_chop</span><span class="p">(</span><span class="s">u'一二三四五六七八九十'</span><span class="p">,</span> <span class="mi">10</span><span class="p">))</span> <span class="go">1234567890</span> <span class="go">一二三四五</span> </pre></div> </div> </dd></dl> <dl class="function"> <dt id="kitchen.text.display.textual_width_fill"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">textual_width_fill</tt><big>(</big><em>msg</em>, <em>fill</em>, <em>chop=None</em>, <em>left=True</em>, <em>prefix=''</em>, <em>suffix=''</em><big>)</big><a class="headerlink" href="#kitchen.text.display.textual_width_fill" title="Permalink to this definition">¶</a></dt> <dd><p>Expand a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string to a specified <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> or chop to same</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>msg</strong> – <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string to format</li> <li><strong>fill</strong> – pad string until the <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> of the string is this length</li> <li><strong>chop</strong> – before doing anything else, chop the string to this length. Default: Don’t chop the string at all</li> <li><strong>left</strong> – If <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> (default) left justify the string and put the padding on the right. If <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>, pad on the left side.</li> <li><strong>prefix</strong> – Attach this string before the field we’re filling</li> <li><strong>suffix</strong> – Append this string to the end of the field we’re filling</li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first"><tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string</p> </td> </tr> <tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt> formatted to fill the specified width. If no <tt class="xref py py-attr docutils literal"><span class="pre">chop</span></tt> is specified, the string could exceed the fill length when completed. If <tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt> or <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> are printable characters, the string could be longer than the fill width.</p> </td> </tr> </tbody> </table> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last"><tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt> and <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> should be used for “invisible” characters like highlighting, color changing escape codes, etc. The fill characters are appended outside of any <tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt> or <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> elements. This allows you to only highlight <tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt> inside of the field you’re filling.</p> </div> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last"><tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt>, <tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt>, and <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> should all be representable as unicode characters. In particular, any escape sequences in <tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt> and <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> need to be convertible to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>. If you need to use byte sequences here rather than unicode characters, use <a class="reference internal" href="#kitchen.text.display.byte_string_textual_width_fill" title="kitchen.text.display.byte_string_textual_width_fill"><tt class="xref py py-func docutils literal"><span class="pre">byte_string_textual_width_fill()</span></tt></a> instead.</p> </div> <p>This function expands a string to fill a field of a particular <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a>. Use it instead of <tt class="docutils literal"><span class="pre">%*.*s</span></tt>, as it does the “right” thing with regard to <a class="reference internal" href="glossary.html#term-utf-8"><em class="xref std std-term">UTF-8</em></a> sequences, <a class="reference internal" href="glossary.html#term-control-characters"><em class="xref std std-term">control characters</em></a>, and characters that take more than one cell position in a display. Example usage:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">msg</span> <span class="o">=</span> <span class="s">u'一二三四五六七八九十'</span> <span class="gp">>>> </span><span class="c"># Wrong: This uses 10 characters instead of 10 cells:</span> <span class="gp">>>> </span><span class="s">u":</span><span class="si">%-*.*s</span><span class="s">:"</span> <span class="o">%</span> <span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="n">msg</span><span class="p">[:</span><span class="mi">9</span><span class="p">])</span> <span class="go">:一二三四五六七八九 :</span> <span class="gp">>>> </span><span class="c"># This uses 10 cells like we really want:</span> <span class="gp">>>> </span><span class="s">u":</span><span class="si">%s</span><span class="s">:"</span> <span class="o">%</span> <span class="p">(</span><span class="n">textual_width_fill</span><span class="p">(</span><span class="n">msg</span><span class="p">[:</span><span class="mi">9</span><span class="p">],</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">))</span> <span class="go">:一二三四五:</span> <span class="gp">>>> </span><span class="c"># Wrong: Right aligned in the field, but too many cells</span> <span class="gp">>>> </span><span class="s">u"</span><span class="si">%20.10s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">msg</span><span class="p">)</span> <span class="go"> 一二三四五六七八九十</span> <span class="gp">>>> </span><span class="c"># Correct: Right aligned with proper number of cells</span> <span class="gp">>>> </span><span class="s">u"</span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">textual_width_fill</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="n">left</span><span class="o">=</span><span class="bp">False</span><span class="p">))</span> <span class="go"> 一二三四五</span> <span class="gp">>>> </span><span class="c"># Wrong: Adding some escape characters to highlight the line but too many cells</span> <span class="gp">>>> </span><span class="s">u"</span><span class="si">%s%20.10s%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">msg</span><span class="p">,</span> <span class="n">suffix</span><span class="p">)</span> <span class="go">u'[7m 一二三四五六七八九十[0m'</span> <span class="gp">>>> </span><span class="c"># Correct highlight of the line</span> <span class="gp">>>> </span><span class="s">u"</span><span class="si">%s%s%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">display</span><span class="o">.</span><span class="n">textual_width_fill</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="n">left</span><span class="o">=</span><span class="bp">False</span><span class="p">),</span> <span class="n">suffix</span><span class="p">)</span> <span class="go">u'[7m 一二三四五[0m'</span> <span class="gp">>>> </span><span class="c"># Correct way to not highlight the fill</span> <span class="gp">>>> </span><span class="s">u"</span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">display</span><span class="o">.</span><span class="n">textual_width_fill</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="n">left</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="n">prefix</span><span class="p">,</span> <span class="n">suffix</span><span class="o">=</span><span class="n">suffix</span><span class="p">))</span> <span class="go">u' [7m一二三四五[0m'</span> </pre></div> </div> </dd></dl> <dl class="function"> <dt id="kitchen.text.display.wrap"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">wrap</tt><big>(</big><em>text</em>, <em>width=70</em>, <em>initial_indent=u''</em>, <em>subsequent_indent=u''</em>, <em>encoding='utf-8'</em>, <em>errors='replace'</em><big>)</big><a class="headerlink" href="#kitchen.text.display.wrap" title="Permalink to this definition">¶</a></dt> <dd><p>Works like we want <a class="reference external" href="http://docs.python.org/library/textwrap.html#textwrap.wrap" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">textwrap.wrap()</span></tt></a> to work,</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>text</strong> – <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string or byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to wrap</li> <li><strong>width</strong> – <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> at which to wrap. Default: 70</li> <li><strong>initial_indent</strong> – string to use to indent the first line. Default: do not indent.</li> <li><strong>subsequent_indent</strong> – string to use to wrap subsequent lines. Default: do not indent</li> <li><strong>encoding</strong> – Encoding to use if <tt class="xref py py-attr docutils literal"><span class="pre">text</span></tt> is a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt></li> <li><strong>errors</strong> – error handler to use if <tt class="xref py py-attr docutils literal"><span class="pre">text</span></tt> is a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> and contains some undecodable characters.</li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first"><tt class="xref py py-class docutils literal"><span class="pre">list</span></tt> of <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings</p> </td> </tr> <tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">list of lines that have been text wrapped and indented.</p> </td> </tr> </tbody> </table> <p><a class="reference external" href="http://docs.python.org/library/textwrap.html#textwrap.wrap" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">textwrap.wrap()</span></tt></a> from the <a class="reference external" href="http://docs.python.org/library">python standard library</a> has two drawbacks that this attempts to fix:</p> <ol class="arabic simple"> <li>It does not handle <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a>. It only operates on bytes or characters which are both inadequate (due to multi-byte and double width characters).</li> <li>It malforms lists and blocks.</li> </ol> </dd></dl> <dl class="function"> <dt id="kitchen.text.display.fill"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">fill</tt><big>(</big><em>text</em>, <em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#kitchen.text.display.fill" title="Permalink to this definition">¶</a></dt> <dd><p>Works like we want <a class="reference external" href="http://docs.python.org/library/textwrap.html#textwrap.fill" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">textwrap.fill()</span></tt></a> to work</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>text</strong> – <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string or byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to process</td> </tr> <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string with each line separated by a newline</td> </tr> </tbody> </table> <div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt><a class="reference internal" href="#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></dt> <dd>for other parameters that you can give this command.</dd> </dl> </div> <p>This function is a light wrapper around <a class="reference internal" href="#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>. Where that function returns a <tt class="xref py py-class docutils literal"><span class="pre">list</span></tt> of lines, this function returns one string with each line separated by a newline.</p> </dd></dl> <dl class="function"> <dt id="kitchen.text.display.byte_string_textual_width_fill"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">byte_string_textual_width_fill</tt><big>(</big><em>msg</em>, <em>fill</em>, <em>chop=None</em>, <em>left=True</em>, <em>prefix=''</em>, <em>suffix=''</em>, <em>encoding='utf-8'</em>, <em>errors='replace'</em><big>)</big><a class="headerlink" href="#kitchen.text.display.byte_string_textual_width_fill" title="Permalink to this definition">¶</a></dt> <dd><p>Expand a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to a specified <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> or chop to same</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>msg</strong> – byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> encoded in <a class="reference internal" href="glossary.html#term-utf-8"><em class="xref std std-term">UTF-8</em></a> that we want formatted</li> <li><strong>fill</strong> – pad <tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt> until the <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> is this long</li> <li><strong>chop</strong> – before doing anything else, chop the string to this length. Default: Don’t chop the string at all</li> <li><strong>left</strong> – If <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> (default) left justify the string and put the padding on the right. If <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>, pad on the left side.</li> <li><strong>prefix</strong> – Attach this byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> before the field we’re filling</li> <li><strong>suffix</strong> – Append this byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to the end of the field we’re filling</li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt></p> </td> </tr> <tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt> formatted to fill the specified <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a>. If no <tt class="xref py py-attr docutils literal"><span class="pre">chop</span></tt> is specified, the string could exceed the fill length when completed. If <tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt> or <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> are printable characters, the string could be longer than fill width.</p> </td> </tr> </tbody> </table> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last"><tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt> and <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> should be used for “invisible” characters like highlighting, color changing escape codes, etc. The fill characters are appended outside of any <tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt> or <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> elements. This allows you to only highlight <tt class="xref py py-attr docutils literal"><span class="pre">msg</span></tt> inside of the field you’re filling.</p> </div> <div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt><a class="reference internal" href="#kitchen.text.display.textual_width_fill" title="kitchen.text.display.textual_width_fill"><tt class="xref py py-func docutils literal"><span class="pre">textual_width_fill()</span></tt></a></dt> <dd><p class="first">For example usage. This function has only two differences.</p> <ol class="last arabic simple"> <li>it takes byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> for <tt class="xref py py-attr docutils literal"><span class="pre">prefix</span></tt> and <tt class="xref py py-attr docutils literal"><span class="pre">suffix</span></tt> so you can pass in arbitrary sequences of bytes, not just unicode characters.</li> <li>it returns a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> instead of a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string.</li> </ol> </dd> </dl> </div> </dd></dl> <div class="section" id="internal-data"> <h1>Internal Data<a class="headerlink" href="#internal-data" title="Permalink to this headline">¶</a></h1> <p>There are a few internal functions and variables in this module. Code outside of kitchen shouldn’t use them but people coding on kitchen itself may find them useful.</p> <dl class="data"> <dt id="kitchen.text.display._COMBINING"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">_COMBINING</tt><em class="property"> = ((768, 879), (1155, 1161), (1425, 1469), (1471, 1471), (1473, 1474), (1476, 1477), (1479, 1479), (1536, 1539), (1552, 1562), (1611, 1630), (1648, 1648), (1750, 1764), (1767, 1768), (1770, 1773), (1807, 1807), (1809, 1809), (1840, 1866), (1958, 1968), (2027, 2035), (2070, 2073), (2075, 2083), (2085, 2087), (2089, 2093), (2305, 2306), (2364, 2364), (2369, 2376), (2381, 2381), (2385, 2388), (2402, 2403), (2433, 2433), (2492, 2492), (2497, 2500), (2509, 2509), (2530, 2531), (2561, 2562), (2620, 2620), (2625, 2626), (2631, 2632), (2635, 2637), (2672, 2673), (2689, 2690), (2748, 2748), (2753, 2757), (2759, 2760), (2765, 2765), (2786, 2787), (2817, 2817), (2876, 2876), (2879, 2879), (2881, 2883), (2893, 2893), (2902, 2902), (2946, 2946), (3008, 3008), (3021, 3021), (3134, 3136), (3142, 3144), (3146, 3149), (3157, 3158), (3260, 3260), (3263, 3263), (3270, 3270), (3276, 3277), (3298, 3299), (3393, 3395), (3405, 3405), (3530, 3530), (3538, 3540), (3542, 3542), (3633, 3633), (3636, 3642), (3655, 3662), (3761, 3761), (3764, 3769), (3771, 3772), (3784, 3789), (3864, 3865), (3893, 3893), (3895, 3895), (3897, 3897), (3953, 3966), (3968, 3972), (3974, 3975), (3984, 3991), (3993, 4028), (4038, 4038), (4141, 4144), (4146, 4146), (4150, 4151), (4153, 4154), (4184, 4185), (4237, 4237), (4448, 4607), (4959, 4959), (5906, 5908), (5938, 5940), (5970, 5971), (6002, 6003), (6068, 6069), (6071, 6077), (6086, 6086), (6089, 6099), (6109, 6109), (6155, 6157), (6313, 6313), (6432, 6434), (6439, 6440), (6450, 6450), (6457, 6459), (6679, 6680), (6752, 6752), (6773, 6780), (6783, 6783), (6912, 6915), (6964, 6964), (6966, 6970), (6972, 6972), (6978, 6978), (6980, 6980), (7019, 7027), (7082, 7082), (7223, 7223), (7376, 7378), (7380, 7392), (7394, 7400), (7405, 7405), (7616, 7654), (7677, 7679), (8203, 8207), (8234, 8238), (8288, 8291), (8298, 8303), (8400, 8432), (11503, 11505), (11744, 11775), (12330, 12335), (12441, 12442), (42607, 42607), (42620, 42621), (42736, 42737), (43014, 43014), (43019, 43019), (43045, 43046), (43204, 43204), (43232, 43249), (43307, 43309), (43347, 43347), (43443, 43443), (43456, 43456), (43696, 43696), (43698, 43700), (43703, 43704), (43710, 43711), (43713, 43713), (44013, 44013), (64286, 64286), (65024, 65039), (65056, 65062), (65279, 65279), (65529, 65531), (66045, 66045), (68097, 68099), (68101, 68102), (68108, 68111), (68152, 68154), (68159, 68159), (69817, 69818), (119141, 119145), (119149, 119170), (119173, 119179), (119210, 119213), (119362, 119364), (917505, 917505), (917536, 917631), (917760, 917999))</em><a class="headerlink" href="#kitchen.text.display._COMBINING" title="Permalink to this definition">¶</a></dt> <dd><p>Internal table, provided by this module to list <a class="reference internal" href="glossary.html#term-code-points"><em class="xref std std-term">code points</em></a> which combine with other characters and therefore should have no <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a>. This is a sorted <tt class="xref py py-class docutils literal"><span class="pre">tuple</span></tt> of non-overlapping intervals. Each interval is a <tt class="xref py py-class docutils literal"><span class="pre">tuple</span></tt> listing a starting <a class="reference internal" href="glossary.html#term-code-point"><em class="xref std std-term">code point</em></a> and ending <a class="reference internal" href="glossary.html#term-code-point"><em class="xref std std-term">code point</em></a>. Every <a class="reference internal" href="glossary.html#term-code-point"><em class="xref std std-term">code point</em></a> between the two end points is a combining character.</p> <div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt><a class="reference internal" href="#kitchen.text.display._generate_combining_table" title="kitchen.text.display._generate_combining_table"><tt class="xref py py-func docutils literal"><span class="pre">_generate_combining_table()</span></tt></a></dt> <dd>for how this table is generated</dd> </dl> </div> <p>This table was last regenerated on python-2.7.0 with <a class="reference external" href="http://docs.python.org/library/unicodedata.html#unicodedata.unidata_version" title="(in Python v2.7)"><tt class="xref py py-data docutils literal"><span class="pre">unicodedata.unidata_version</span></tt></a> 5.1.0</p> </dd></dl> <dl class="function"> <dt id="kitchen.text.display._generate_combining_table"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">_generate_combining_table</tt><big>(</big><big>)</big><a class="headerlink" href="#kitchen.text.display._generate_combining_table" title="Permalink to this definition">¶</a></dt> <dd><p>Combine Markus Kuhn’s data with <a class="reference external" href="http://docs.python.org/library/unicodedata.html#unicodedata" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">unicodedata</span></tt></a> to make combining char list</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><tt class="xref py py-class docutils literal"><span class="pre">tuple</span></tt> of tuples</td> </tr> <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><tt class="xref py py-class docutils literal"><span class="pre">tuple</span></tt> of intervals of <a class="reference internal" href="glossary.html#term-code-points"><em class="xref std std-term">code points</em></a> that are combining character. Each interval is a 2-<tt class="xref py py-class docutils literal"><span class="pre">tuple</span></tt> of the starting <a class="reference internal" href="glossary.html#term-code-point"><em class="xref std std-term">code point</em></a> and the ending <a class="reference internal" href="glossary.html#term-code-point"><em class="xref std std-term">code point</em></a> for the combining characters.</td> </tr> </tbody> </table> <p>In normal use, this function serves to tell how we’re generating the combining char list. For speed reasons, we use this to generate a static list and just use that later.</p> <p>Markus Kuhn’s list of combining characters is more complete than what’s in the python <a class="reference external" href="http://docs.python.org/library/unicodedata.html#unicodedata" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">unicodedata</span></tt></a> library but the python <a class="reference external" href="http://docs.python.org/library/unicodedata.html#unicodedata" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">unicodedata</span></tt></a> is synced against later versions of the unicode database</p> <p>This is used to generate the <a class="reference internal" href="#kitchen.text.display._COMBINING" title="kitchen.text.display._COMBINING"><tt class="xref py py-data docutils literal"><span class="pre">_COMBINING</span></tt></a> table.</p> </dd></dl> <dl class="function"> <dt id="kitchen.text.display._print_combining_table"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">_print_combining_table</tt><big>(</big><big>)</big><a class="headerlink" href="#kitchen.text.display._print_combining_table" title="Permalink to this definition">¶</a></dt> <dd><p>Print out a new <a class="reference internal" href="#kitchen.text.display._COMBINING" title="kitchen.text.display._COMBINING"><tt class="xref py py-data docutils literal"><span class="pre">_COMBINING</span></tt></a> table</p> <p>This will print a new <a class="reference internal" href="#kitchen.text.display._COMBINING" title="kitchen.text.display._COMBINING"><tt class="xref py py-data docutils literal"><span class="pre">_COMBINING</span></tt></a> table in the format used in <tt class="file docutils literal"><span class="pre">kitchen/text/display.py</span></tt>. It’s useful for updating the <a class="reference internal" href="#kitchen.text.display._COMBINING" title="kitchen.text.display._COMBINING"><tt class="xref py py-data docutils literal"><span class="pre">_COMBINING</span></tt></a> table with updated data from a new python as the format won’t change from what’s already in the file.</p> </dd></dl> <dl class="function"> <dt id="kitchen.text.display._interval_bisearch"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">_interval_bisearch</tt><big>(</big><em>value</em>, <em>table</em><big>)</big><a class="headerlink" href="#kitchen.text.display._interval_bisearch" title="Permalink to this definition">¶</a></dt> <dd><p>Binary search in an interval table.</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>value</strong> – numeric value to search for</li> <li><strong>table</strong> – Ordered list of intervals. This is a list of two-tuples. The elements of the two-tuple define an interval’s start and end points.</li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">If <tt class="xref py py-attr docutils literal"><span class="pre">value</span></tt> is found within an interval in the <tt class="xref py py-attr docutils literal"><span class="pre">table</span></tt> return <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>. Otherwise, <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></p> </td> </tr> </tbody> </table> <p>This function checks whether a numeric value is present within a table of intervals. It checks using a binary search algorithm, dividing the list of values in half and checking against the values until it determines whether the value is in the table.</p> </dd></dl> <dl class="function"> <dt id="kitchen.text.display._ucp_width"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">_ucp_width</tt><big>(</big><em>ucs</em>, <em>control_chars='guess'</em><big>)</big><a class="headerlink" href="#kitchen.text.display._ucp_width" title="Permalink to this definition">¶</a></dt> <dd><p>Get the <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> of a ucs character</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>ucs</strong> – integer representing a single unicode <a class="reference internal" href="glossary.html#term-code-point"><em class="xref std std-term">code point</em></a></li> <li><strong>control_chars</strong> – <p>specify how to deal with <a class="reference internal" href="glossary.html#term-control-characters"><em class="xref std std-term">control characters</em></a>. Possible values are:</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">guess:</th><td class="field-body">(default) will take a guess for <a class="reference internal" href="glossary.html#term-control-character"><em class="xref std std-term">control character</em></a> widths. Most codes will return zero width. <tt class="docutils literal"><span class="pre">backspace</span></tt>, <tt class="docutils literal"><span class="pre">delete</span></tt>, and <tt class="docutils literal"><span class="pre">clear</span> <span class="pre">delete</span></tt> return -1. <tt class="docutils literal"><span class="pre">escape</span></tt> currently returns -1 as well but this is not guaranteed as it’s not always correct</td> </tr> <tr class="field-even field"><th class="field-name">strict:</th><td class="field-body">will raise <a class="reference internal" href="api-exceptions.html#kitchen.text.exceptions.ControlCharError" title="kitchen.text.exceptions.ControlCharError"><tt class="xref py py-exc docutils literal"><span class="pre">ControlCharError</span></tt></a> if a <a class="reference internal" href="glossary.html#term-control-character"><em class="xref std std-term">control character</em></a> is encountered</td> </tr> </tbody> </table> </li> </ul> </td> </tr> <tr class="field-odd field"><th class="field-name" colspan="2">Raises ControlCharError:</th></tr> <tr class="field-odd field"><td> </td><td class="field-body"><p class="first">if the <a class="reference internal" href="glossary.html#term-code-point"><em class="xref std std-term">code point</em></a> is a unicode <a class="reference internal" href="glossary.html#term-control-character"><em class="xref std std-term">control character</em></a> and <tt class="xref py py-attr docutils literal"><span class="pre">control_chars</span></tt> is set to ‘strict’</p> </td> </tr> <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> of the character.</p> </td> </tr> </tbody> </table> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">It’s important to remember this is <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> and not the number of characters or bytes.</p> </div> </dd></dl> <dl class="function"> <dt id="kitchen.text.display._textual_width_le"> <tt class="descclassname">kitchen.text.display.</tt><tt class="descname">_textual_width_le</tt><big>(</big><em>width</em>, <em>*args</em><big>)</big><a class="headerlink" href="#kitchen.text.display._textual_width_le" title="Permalink to this definition">¶</a></dt> <dd><p>Optimize the common case when deciding which <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> is larger</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>width</strong> – <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> to compare against.</li> <li><strong>*args</strong> – <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings to check the total <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> of</li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><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> if the total length of <tt class="xref py py-attr docutils literal"><span class="pre">args</span></tt> are less than or equal to <tt class="xref py py-attr docutils literal"><span class="pre">width</span></tt>. Otherwise <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>.</p> </td> </tr> </tbody> </table> <p>We often want to know “does X fit in Y”. It takes a while to use <a class="reference internal" href="#kitchen.text.display.textual_width" title="kitchen.text.display.textual_width"><tt class="xref py py-func docutils literal"><span class="pre">textual_width()</span></tt></a> to calculate this. However, we know that the number of canonically composed <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> characters is always going to have 1 or 2 for the <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> per character. With this we can take the following shortcuts:</p> <ol class="arabic simple"> <li>If the number of canonically composed characters is more than width, the true <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> cannot be less than width.</li> <li>If the number of canonically composed characters * 2 is less than the width then the <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> must be ok.</li> </ol> <p><a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> of a canonically composed <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string will always be greater than or equal to the the number of <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> characters. So we can first check if the number of composed <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> characters is less than the asked for width. If it is we can return <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> immediately. If not, then we must do a full <a class="reference internal" href="glossary.html#term-textual-width"><em class="xref std std-term">textual width</em></a> lookup.</p> </dd></dl> </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="#">Format Text for Display</a></li> <li><a class="reference internal" href="#internal-data">Internal Data</a></li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="api-text-converters.html" title="previous chapter">Kitchen.text.converters</a></p> <h4>Next topic</h4> <p class="topless"><a href="api-text-misc.html" title="next chapter">Miscellaneous functions for manipulating text</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/api-text-display.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="api-text-misc.html" title="Miscellaneous functions for manipulating text" >next</a> |</li> <li class="right" > <a href="api-text-converters.html" title="Kitchen.text.converters" >previous</a> |</li> <li><a href="index.html">kitchen 1.1.1 documentation</a> »</li> <li><a href="api-overview.html" >Kitchen API</a> »</li> <li><a href="api-text.html" >Kitchen.text: unicode and utf8 and xml oh my!</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>