| <!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> |
| |
| |
| The Unicode Chapter |
| — |
| Mako 1.0.14 Documentation |
| |
| </title> |
| |
| |
| <!-- begin iterate through site-imported + sphinx environment css_files --> |
| <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> |
| <link rel="stylesheet" href="_static/changelog.css" type="text/css" /> |
| <link rel="stylesheet" href="_static/sphinx_paramlinks.css" type="text/css" /> |
| <link rel="stylesheet" href="_static/docs.css" type="text/css" /> |
| <!-- end iterate through site-imported + sphinx environment css_files --> |
| |
| |
| |
| |
| |
| <!-- begin layout.mako headers --> |
| |
| <link rel="index" title="Index" href="genindex.html" /> |
| <link rel="search" title="Search" href="search.html" /> |
| <link rel="top" title="Mako 1.0.14 Documentation" href="index.html" /> |
| <link rel="next" title="Caching" href="caching.html" /> |
| <link rel="prev" title="Filtering and Buffering" href="filtering.html" /> |
| <!-- end layout.mako headers --> |
| |
| |
| </head> |
| <body> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div id="docs-container"> |
| |
| |
| |
| <div id="docs-header"> |
| <h1>Mako 1.0.14 Documentation</h1> |
| |
| <div id="docs-search"> |
| Search: |
| <form class="search" action="search.html" method="get"> |
| <input type="text" name="q" size="18" /> <input type="submit" value="Search" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| |
| <div id="docs-version-header"> |
| Release: <span class="version-num">1.0.14</span> |
| |
| </div> |
| |
| </div> |
| |
| <div id="docs-top-navigation"> |
| <div id="docs-top-page-control" class="docs-navigation-links"> |
| <ul> |
| <li>Prev: |
| <a href="filtering.html" title="previous chapter">Filtering and Buffering</a> |
| </li> |
| <li>Next: |
| <a href="caching.html" title="next chapter">Caching</a> |
| </li> |
| |
| <li> |
| <a href="index.html">Table of Contents</a> | |
| <a href="genindex.html">Index</a> |
| </li> |
| </ul> |
| </div> |
| |
| <div id="docs-navigation-banner"> |
| <a href="index.html">Mako 1.0.14 Documentation</a> |
| » |
| The Unicode Chapter |
| |
| |
| <h2> |
| |
| The Unicode Chapter |
| |
| </h2> |
| </div> |
| |
| </div> |
| |
| <div id="docs-body-container"> |
| |
| |
| <div id="docs-sidebar"> |
| <div id="sidebar-banner"> |
| |
| </div> |
| |
| <h3><a href="index.html">Table of Contents</a></h3> |
| <ul> |
| <li><a class="reference internal" href="#">The Unicode Chapter</a><ul> |
| <li><a class="reference internal" href="#specifying-the-encoding-of-a-template-file">Specifying the Encoding of a Template File</a></li> |
| <li><a class="reference internal" href="#handling-expressions">Handling Expressions</a></li> |
| <li><a class="reference internal" href="#defining-output-encoding">Defining Output Encoding</a><ul> |
| <li><a class="reference internal" href="#buffer-selection">Buffer Selection</a></li> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#saying-to-heck-with-it-disabling-the-usage-of-unicode-entirely">Saying to Heck with It: Disabling the Usage of Unicode Entirely</a><ul> |
| <li><a class="reference internal" href="#rules-for-using-disable-unicode-true">Rules for using <code class="docutils literal notranslate"><span class="pre">disable_unicode=True</span></code></a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| |
| <h4>Previous Topic</h4> |
| <p> |
| <a href="filtering.html" title="previous chapter">Filtering and Buffering</a> |
| </p> |
| <h4>Next Topic</h4> |
| <p> |
| <a href="caching.html" title="next chapter">Caching</a> |
| </p> |
| |
| <h4>Quick Search</h4> |
| <p> |
| <form class="search" action="search.html" method="get"> |
| <input type="text" name="q" size="18" /> <input type="submit" value="Search" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </p> |
| |
| </div> |
| |
| <div id="docs-body" class="withsidebar" > |
| |
| <div class="section" id="the-unicode-chapter"> |
| <span id="unicode-toplevel"></span><h1>The Unicode Chapter<a class="headerlink" href="#the-unicode-chapter" title="Permalink to this headline">¶</a></h1> |
| <p>The Python language supports two ways of representing what we |
| know as “strings”, i.e. series of characters. In Python 2, the |
| two types are <code class="docutils literal notranslate"><span class="pre">string</span></code> and <code class="docutils literal notranslate"><span class="pre">unicode</span></code>, and in Python 3 they are |
| <code class="docutils literal notranslate"><span class="pre">bytes</span></code> and <code class="docutils literal notranslate"><span class="pre">string</span></code>. A key aspect of the Python 2 <code class="docutils literal notranslate"><span class="pre">string</span></code> and |
| Python 3 <code class="docutils literal notranslate"><span class="pre">bytes</span></code> types are that they contain no information |
| regarding what <strong>encoding</strong> the data is stored in. For this |
| reason they were commonly referred to as <strong>byte strings</strong> on |
| Python 2, and Python 3 makes this name more explicit. The |
| origins of this come from Python’s background of being developed |
| before the Unicode standard was even available, back when |
| strings were C-style strings and were just that, a series of |
| bytes. Strings that had only values below 128 just happened to |
| be <strong>ASCII</strong> strings and were printable on the console, whereas |
| strings with values above 128 would produce all kinds of |
| graphical characters and bells.</p> |
| <p>Contrast the “byte-string” type with the “unicode/string” type. |
| Objects of this latter type are created whenever you say something like |
| <code class="docutils literal notranslate"><span class="pre">u"hello</span> <span class="pre">world"</span></code> (or in Python 3, just <code class="docutils literal notranslate"><span class="pre">"hello</span> <span class="pre">world"</span></code>). In this |
| case, Python represents each character in the string internally |
| using multiple bytes per character (something similar to |
| UTF-16). What’s important is that when using the |
| <code class="docutils literal notranslate"><span class="pre">unicode</span></code>/<code class="docutils literal notranslate"><span class="pre">string</span></code> type to store strings, Python knows the |
| data’s encoding; it’s in its own internal format. Whereas when |
| using the <code class="docutils literal notranslate"><span class="pre">string</span></code>/<code class="docutils literal notranslate"><span class="pre">bytes</span></code> type, it does not.</p> |
| <p>When Python 2 attempts to treat a byte-string as a string, which |
| means it’s attempting to compare/parse its characters, to coerce |
| it into another encoding, or to decode it to a unicode object, |
| it has to guess what the encoding is. In this case, it will |
| pretty much always guess the encoding as <code class="docutils literal notranslate"><span class="pre">ascii</span></code>… and if the |
| byte-string contains bytes above value 128, you’ll get an error. |
| Python 3 eliminates much of this confusion by just raising an |
| error unconditionally if a byte-string is used in a |
| character-aware context.</p> |
| <p>There is one operation that Python <em>can</em> do with a non-ASCII |
| byte-string, and it’s a great source of confusion: it can dump the |
| byte-string straight out to a stream or a file, with nary a care |
| what the encoding is. To Python, this is pretty much like |
| dumping any other kind of binary data (like an image) to a |
| stream somewhere. In Python 2, it is common to see programs that |
| embed all kinds of international characters and encodings into |
| plain byte-strings (i.e. using <code class="docutils literal notranslate"><span class="pre">"hello</span> <span class="pre">world"</span></code> style literals) |
| can fly right through their run, sending reams of strings out to |
| wherever they are going, and the programmer, seeing the same |
| output as was expressed in the input, is now under the illusion |
| that his or her program is Unicode-compliant. In fact, their |
| program has no unicode awareness whatsoever, and similarly has |
| no ability to interact with libraries that <em>are</em> unicode aware. |
| Python 3 makes this much less likely by defaulting to unicode as |
| the storage format for strings.</p> |
| <p>The “pass through encoded data” scheme is what template |
| languages like Cheetah and earlier versions of Myghty do by |
| default. Mako as of version 0.2 also supports this mode of |
| operation when using Python 2, using the <code class="docutils literal notranslate"><span class="pre">disable_unicode=True</span></code> |
| flag. However, when using Mako in its default mode of |
| unicode-aware, it requires explicitness when dealing with |
| non-ASCII encodings. Additionally, if you ever need to handle |
| unicode strings and other kinds of encoding conversions more |
| intelligently, the usage of raw byte-strings quickly becomes a |
| nightmare, since you are sending the Python interpreter |
| collections of bytes for which it can make no intelligent |
| decisions with regards to encoding. In Python 3 Mako only allows |
| usage of native, unicode strings.</p> |
| <p>In normal Mako operation, all parsed template constructs and |
| output streams are handled internally as Python <code class="docutils literal notranslate"><span class="pre">unicode</span></code> |
| objects. It’s only at the point of <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal notranslate"><span class="pre">render()</span></code></a> that this unicode |
| stream may be rendered into whatever the desired output encoding |
| is. The implication here is that the template developer must |
| :ensure that <a class="reference internal" href="#set-template-file-encoding"><span class="std std-ref">the encoding of all non-ASCII templates is explicit</span></a> (still required in Python 3), |
| that <a class="reference internal" href="#handling-non-ascii-expressions"><span class="std std-ref">all non-ASCII-encoded expressions are in one way or another |
| converted to unicode</span></a> |
| (not much of a burden in Python 3), and that <a class="reference internal" href="#defining-output-encoding"><span class="std std-ref">the output stream of the |
| template is handled as a unicode stream being encoded to some |
| encoding</span></a> (still required in Python 3).</p> |
| <div class="section" id="specifying-the-encoding-of-a-template-file"> |
| <span id="set-template-file-encoding"></span><h2>Specifying the Encoding of a Template File<a class="headerlink" href="#specifying-the-encoding-of-a-template-file" title="Permalink to this headline">¶</a></h2> |
| <p>This is the most basic encoding-related setting, and it is |
| equivalent to Python’s “magic encoding comment”, as described in |
| <a class="reference external" href="http://www.python.org/dev/peps/pep-0263/">pep-0263</a>. Any |
| template that contains non-ASCII characters requires that this |
| comment be present so that Mako can decode to unicode (and also |
| make usage of Python’s AST parsing services). Mako’s lexer will |
| use this encoding in order to convert the template source into a |
| <code class="docutils literal notranslate"><span class="pre">unicode</span></code> object before continuing its parsing:</p> |
| <div class="highlight-mako notranslate"><div class="highlight"><pre><span></span><span class="cp">## -*- coding: utf-8 -*-</span><span class="x"></span> |
| |
| <span class="x">Alors vous imaginez ma surprise, au lever du jour, quand</span> |
| <span class="x">une drôle de petite voix m’a réveillé. Elle disait:</span> |
| <span class="x"> « S’il vous plaît… dessine-moi un mouton! »</span></pre></div> |
| </div> |
| <p>For the picky, the regular expression used is derived from that |
| of the above mentioned pep:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1">#.*coding[:=]\s*([-\w.]+).*\n</span></pre></div> |
| </div> |
| <p>The lexer will convert to unicode in all cases, so that if any |
| characters exist in the template that are outside of the |
| specified encoding (or the default of <code class="docutils literal notranslate"><span class="pre">ascii</span></code>), the error will |
| be immediate.</p> |
| <p>As an alternative, the template encoding can be specified |
| programmatically to either <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal notranslate"><span class="pre">TemplateLookup</span></code></a> via |
| the <code class="docutils literal notranslate"><span class="pre">input_encoding</span></code> parameter:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">t</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span><span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s1">'./'</span><span class="p">],</span> <span class="n">input_encoding</span><span class="o">=</span><span class="s1">'utf-8'</span><span class="p">)</span></pre></div> |
| </div> |
| <p>The above will assume all located templates specify <code class="docutils literal notranslate"><span class="pre">utf-8</span></code> |
| encoding, unless the template itself contains its own magic |
| encoding comment, which takes precedence.</p> |
| </div> |
| <div class="section" id="handling-expressions"> |
| <span id="handling-non-ascii-expressions"></span><h2>Handling Expressions<a class="headerlink" href="#handling-expressions" title="Permalink to this headline">¶</a></h2> |
| <p>The next area that encoding comes into play is in expression |
| constructs. By default, Mako’s treatment of an expression like |
| this:</p> |
| <div class="highlight-mako notranslate"><div class="highlight"><pre><span></span><span class="cp">${</span><span class="s2">"hello world"</span><span class="cp">}</span><span class="x"></span></pre></div> |
| </div> |
| <p>looks something like this:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="nb">unicode</span><span class="p">(</span><span class="s2">"hello world"</span><span class="p">))</span></pre></div> |
| </div> |
| <p>In Python 3, it’s just:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="s2">"hello world"</span><span class="p">))</span></pre></div> |
| </div> |
| <p>That is, <strong>the output of all expressions is run through the |
| ``unicode`` built-in</strong>. This is the default setting, and can be |
| modified to expect various encodings. The <code class="docutils literal notranslate"><span class="pre">unicode</span></code> step serves |
| both the purpose of rendering non-string expressions into |
| strings (such as integers or objects which contain <code class="docutils literal notranslate"><span class="pre">__str()__</span></code> |
| methods), and to ensure that the final output stream is |
| constructed as a unicode object. The main implication of this is |
| that <strong>any raw byte-strings that contain an encoding other than |
| ASCII must first be decoded to a Python unicode object</strong>. It |
| means you can’t say this in Python 2:</p> |
| <div class="highlight-mako notranslate"><div class="highlight"><pre><span></span><span class="cp">${</span><span class="s2">"voix m’a réveillé."</span><span class="cp">}</span> <span class="cp">## error in Python 2!</span><span class="x"></span></pre></div> |
| </div> |
| <p>You must instead say this:</p> |
| <div class="highlight-mako notranslate"><div class="highlight"><pre><span></span><span class="cp">${</span><span class="sa">u</span><span class="s2">"voix m’a réveillé."</span><span class="cp">}</span> <span class="cp">## OK !</span><span class="x"></span></pre></div> |
| </div> |
| <p>Similarly, if you are reading data from a file that is streaming |
| bytes, or returning data from some object that is returning a |
| Python byte-string containing a non-ASCII encoding, you have to |
| explicitly decode to unicode first, such as:</p> |
| <div class="highlight-mako notranslate"><div class="highlight"><pre><span></span><span class="cp">${</span><span class="n">call_my_object</span><span class="p">()</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">'utf-8'</span><span class="p">)</span><span class="cp">}</span><span class="x"></span></pre></div> |
| </div> |
| <p>Note that filehandles acquired by <code class="docutils literal notranslate"><span class="pre">open()</span></code> in Python 3 default |
| to returning “text”, that is the decoding is done for you. See |
| Python 3’s documentation for the <code class="docutils literal notranslate"><span class="pre">open()</span></code> built-in for details on |
| this.</p> |
| <p>If you want a certain encoding applied to <em>all</em> expressions, |
| override the <code class="docutils literal notranslate"><span class="pre">unicode</span></code> builtin with the <code class="docutils literal notranslate"><span class="pre">decode</span></code> built-in at the |
| <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal notranslate"><span class="pre">TemplateLookup</span></code></a> level:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="n">templatetext</span><span class="p">,</span> <span class="n">default_filters</span><span class="o">=</span><span class="p">[</span><span class="s1">'decode.utf8'</span><span class="p">])</span></pre></div> |
| </div> |
| <p>Note that the built-in <code class="docutils literal notranslate"><span class="pre">decode</span></code> object is slower than the |
| <code class="docutils literal notranslate"><span class="pre">unicode</span></code> function, since unlike <code class="docutils literal notranslate"><span class="pre">unicode</span></code> it’s not a Python |
| built-in, and it also checks the type of the incoming data to |
| determine if string conversion is needed first.</p> |
| <p>The <code class="docutils literal notranslate"><span class="pre">default_filters</span></code> argument can be used to entirely customize |
| the filtering process of expressions. This argument is described |
| in <a class="reference internal" href="filtering.html#filtering-default-filters"><span class="std std-ref">The default_filters Argument</span></a>.</p> |
| </div> |
| <div class="section" id="defining-output-encoding"> |
| <span id="id1"></span><h2>Defining Output Encoding<a class="headerlink" href="#defining-output-encoding" title="Permalink to this headline">¶</a></h2> |
| <p>Now that we have a template which produces a pure unicode output |
| stream, all the hard work is done. We can take the output and do |
| anything with it.</p> |
| <p>As stated in the <a class="reference internal" href="usage.html"><span class="doc">“Usage” chapter</span></a>, both <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> and |
| <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal notranslate"><span class="pre">TemplateLookup</span></code></a> accept <code class="docutils literal notranslate"><span class="pre">output_encoding</span></code> and <code class="docutils literal notranslate"><span class="pre">encoding_errors</span></code> |
| parameters which can be used to encode the output in any Python |
| supported codec:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span> |
| <span class="kn">from</span> <span class="nn">mako.lookup</span> <span class="kn">import</span> <span class="n">TemplateLookup</span> |
| |
| <span class="n">mylookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span><span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s1">'/docs'</span><span class="p">],</span> <span class="n">output_encoding</span><span class="o">=</span><span class="s1">'utf-8'</span><span class="p">,</span> <span class="n">encoding_errors</span><span class="o">=</span><span class="s1">'replace'</span><span class="p">)</span> |
| |
| <span class="n">mytemplate</span> <span class="o">=</span> <span class="n">mylookup</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s2">"foo.txt"</span><span class="p">)</span> |
| <span class="k">print</span><span class="p">(</span><span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">())</span></pre></div> |
| </div> |
| <p><a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal notranslate"><span class="pre">render()</span></code></a> will return a <code class="docutils literal notranslate"><span class="pre">bytes</span></code> object in Python 3 if an output |
| encoding is specified. By default it performs no encoding and |
| returns a native string.</p> |
| <p><a class="reference internal" href="usage.html#mako.template.Template.render_unicode" title="mako.template.Template.render_unicode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">render_unicode()</span></code></a> will return the template output as a Python |
| <code class="docutils literal notranslate"><span class="pre">unicode</span></code> object (or <code class="docutils literal notranslate"><span class="pre">string</span></code> in Python 3):</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">print</span><span class="p">(</span><span class="n">mytemplate</span><span class="o">.</span><span class="n">render_unicode</span><span class="p">())</span></pre></div> |
| </div> |
| <p>The above method disgards the output encoding keyword argument; |
| you can encode yourself by saying:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">print</span><span class="p">(</span><span class="n">mytemplate</span><span class="o">.</span><span class="n">render_unicode</span><span class="p">()</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s1">'utf-8'</span><span class="p">,</span> <span class="s1">'replace'</span><span class="p">))</span></pre></div> |
| </div> |
| <div class="section" id="buffer-selection"> |
| <h3>Buffer Selection<a class="headerlink" href="#buffer-selection" title="Permalink to this headline">¶</a></h3> |
| <p>Mako does play some games with the style of buffering used |
| internally, to maximize performance. Since the buffer is by far |
| the most heavily used object in a render operation, it’s |
| important!</p> |
| <p>When calling <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal notranslate"><span class="pre">render()</span></code></a> on a template that does not specify any |
| output encoding (i.e. it’s <code class="docutils literal notranslate"><span class="pre">ascii</span></code>), Python’s <code class="docutils literal notranslate"><span class="pre">cStringIO</span></code> module, |
| which cannot handle encoding of non-ASCII <code class="docutils literal notranslate"><span class="pre">unicode</span></code> objects |
| (even though it can send raw byte-strings through), is used for |
| buffering. Otherwise, a custom Mako class called |
| <code class="docutils literal notranslate"><span class="pre">FastEncodingBuffer</span></code> is used, which essentially is a super |
| dumbed-down version of <code class="docutils literal notranslate"><span class="pre">StringIO</span></code> that gathers all strings into |
| a list and uses <code class="docutils literal notranslate"><span class="pre">u''.join(elements)</span></code> to produce the final output |
| – it’s markedly faster than <code class="docutils literal notranslate"><span class="pre">StringIO</span></code>.</p> |
| </div> |
| </div> |
| <div class="section" id="saying-to-heck-with-it-disabling-the-usage-of-unicode-entirely"> |
| <span id="unicode-disabled"></span><h2>Saying to Heck with It: Disabling the Usage of Unicode Entirely<a class="headerlink" href="#saying-to-heck-with-it-disabling-the-usage-of-unicode-entirely" title="Permalink to this headline">¶</a></h2> |
| <p>Some segments of Mako’s userbase choose to make no usage of |
| Unicode whatsoever, and instead would prefer the “pass through” |
| approach; all string expressions in their templates return |
| encoded byte-strings, and they would like these strings to pass |
| right through. The only advantage to this approach is that |
| templates need not use <code class="docutils literal notranslate"><span class="pre">u""</span></code> for literal strings; there’s an |
| arguable speed improvement as well since raw byte-strings |
| generally perform slightly faster than unicode objects in |
| Python. For these users, assuming they’re sticking with Python |
| 2, they can hit the <code class="docutils literal notranslate"><span class="pre">disable_unicode=True</span></code> flag as so:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># -*- coding:utf-8 -*-</span> |
| <span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span> |
| |
| <span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">"drôle de petite voix m’a réveillé."</span><span class="p">,</span> <span class="n">disable_unicode</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">input_encoding</span><span class="o">=</span><span class="s1">'utf-8'</span><span class="p">)</span> |
| <span class="k">print</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">code</span><span class="p">)</span></pre></div> |
| </div> |
| <p>The <code class="docutils literal notranslate"><span class="pre">disable_unicode</span></code> mode is strictly a Python 2 thing. It is |
| not supported at all in Python 3.</p> |
| <p>The generated module source code will contain elements like |
| these:</p> |
| <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># -*- coding:utf-8 -*-</span> |
| <span class="c1"># ...more generated code ...</span> |
| |
| <span class="k">def</span> <span class="nf">render_body</span><span class="p">(</span><span class="n">context</span><span class="p">,</span><span class="o">**</span><span class="n">pageargs</span><span class="p">):</span> |
| <span class="n">context</span><span class="o">.</span><span class="n">caller_stack</span><span class="o">.</span><span class="n">push_frame</span><span class="p">()</span> |
| <span class="k">try</span><span class="p">:</span> |
| <span class="n">__M_locals</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">pageargs</span><span class="o">=</span><span class="n">pageargs</span><span class="p">)</span> |
| <span class="c1"># SOURCE LINE 1</span> |
| <span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'dr</span><span class="se">\xc3\xb4</span><span class="s1">le de petite voix m</span><span class="se">\xe2\x80\x99</span><span class="s1">a r</span><span class="se">\xc3\xa9</span><span class="s1">veill</span><span class="se">\xc3\xa9</span><span class="s1">.'</span><span class="p">)</span> |
| <span class="k">return</span> <span class="s1">''</span> |
| <span class="k">finally</span><span class="p">:</span> |
| <span class="n">context</span><span class="o">.</span><span class="n">caller_stack</span><span class="o">.</span><span class="n">pop_frame</span><span class="p">()</span></pre></div> |
| </div> |
| <p>Where above that the string literal used within <a class="reference internal" href="runtime.html#mako.runtime.Context.write" title="mako.runtime.Context.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Context.write()</span></code></a> |
| is a regular byte-string.</p> |
| <p>When <code class="docutils literal notranslate"><span class="pre">disable_unicode=True</span></code> is turned on, the <code class="docutils literal notranslate"><span class="pre">default_filters</span></code> |
| argument which normally defaults to <code class="docutils literal notranslate"><span class="pre">["unicode"]</span></code> now defaults |
| to <code class="docutils literal notranslate"><span class="pre">["str"]</span></code> instead. Setting <code class="docutils literal notranslate"><span class="pre">default_filters</span></code> to the empty list |
| <code class="docutils literal notranslate"><span class="pre">[]</span></code> can remove the overhead of the <code class="docutils literal notranslate"><span class="pre">str</span></code> call. Also, in this |
| mode you <strong>cannot</strong> safely call <a class="reference internal" href="usage.html#mako.template.Template.render_unicode" title="mako.template.Template.render_unicode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">render_unicode()</span></code></a> – you’ll get |
| unicode/decode errors.</p> |
| <p>The <code class="docutils literal notranslate"><span class="pre">h</span></code> filter (HTML escape) uses a less performant pure Python |
| escape function in non-unicode mode. This because |
| MarkupSafe only supports Python unicode objects for non-ASCII |
| strings.</p> |
| <div class="versionchanged"> |
| <p><span class="versionmodified changed">Changed in version 0.3.4: </span>In prior versions, it used <code class="docutils literal notranslate"><span class="pre">cgi.escape()</span></code>, which has been replaced |
| with a function that also escapes single quotes.</p> |
| </div> |
| <div class="section" id="rules-for-using-disable-unicode-true"> |
| <h3>Rules for using <code class="docutils literal notranslate"><span class="pre">disable_unicode=True</span></code><a class="headerlink" href="#rules-for-using-disable-unicode-true" title="Permalink to this headline">¶</a></h3> |
| <ul class="simple"> |
| <li><p>Don’t use this mode unless you really, really want to and you |
| absolutely understand what you’re doing.</p></li> |
| <li><p>Don’t use this option just because you don’t want to learn to |
| use Unicode properly; we aren’t supporting user issues in this |
| mode of operation. We will however offer generous help for the |
| vast majority of users who stick to the Unicode program.</p></li> |
| <li><p>Python 3 is unicode by default, and the flag is not available |
| when running on Python 3.</p></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| |
| </div> |
| |
| </div> |
| |
| <div id="docs-bottom-navigation" class="docs-navigation-links"> |
| Previous: |
| <a href="filtering.html" title="previous chapter">Filtering and Buffering</a> |
| Next: |
| <a href="caching.html" title="next chapter">Caching</a> |
| |
| <div id="docs-copyright"> |
| © Copyright the Mako authors and contributors. |
| Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.1.2 |
| with Mako templates. |
| </div> |
| </div> |
| |
| </div> |
| |
| |
| |
| |
| |
| |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT: './', |
| VERSION: '1.0.14', |
| COLLAPSE_MODINDEX: false, |
| FILE_SUFFIX: '.html' |
| }; |
| </script> |
| |
| <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> |
| |
| <!-- begin iterate through sphinx environment script_files --> |
| <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> |
| <script type="text/javascript" src="_static/language_data.js"></script> |
| <!-- end iterate through sphinx environment script_files --> |
| |
| <script type="text/javascript" src="_static/detectmobile.js"></script> |
| <script type="text/javascript" src="_static/init.js"></script> |
| |
| |
| </body> |
| </html> |
| |
| |
