| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474 |
- <html xmlns="http://www.w3.org/1999/xhtml">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
- <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
- <head>
- <title>
-
- The Unicode Chapter
- —
- Mako 0.7.2 Documentation
- </title>
- <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
- <link rel="stylesheet" href="_static/docs.css" type="text/css" />
- <script type="text/javascript">
- var DOCUMENTATION_OPTIONS = {
- URL_ROOT: '#',
- VERSION: '0.7.2',
- COLLAPSE_MODINDEX: false,
- FILE_SUFFIX: '.html'
- };
- </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="index" title="Index" href="genindex.html" />
- <link rel="search" title="Search" href="search.html" />
- <link rel="top" title="Mako 0.7.2 Documentation" href="index.html" />
- <link rel="next" title="Caching" href="caching.html" />
- <link rel="prev" title="Filtering and Buffering" href="filtering.html" />
- <link rel="stylesheet" href="_static/site.css"></link>
- </head>
- <body>
- <div id="wrap">
- <div class="rightbar">
- <div class="slogan">
- Hyperfast and lightweight templating for the Python platform.
- </div>
- </div>
- <a href="http://www.makotemplates.org/"><img src="_static/makoLogo.png" /></a>
- <hr/>
-
- <div id="docs-container">
- <div id="docs-header">
- <h1>Mako 0.7.2 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">0.7.2</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>
- | <a href="_sources/unicode.txt">view source
- </li>
- </ul>
- </div>
- <div id="docs-navigation-banner">
- <a href="index.html">Mako 0.7.2 Documentation</a>
- »
- The Unicode Chapter
-
- <h2>
-
- The Unicode Chapter
-
- </h2>
- </div>
- </div>
- <div id="docs-body-container">
- <div id="docs-sidebar">
- <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 <tt class="docutils literal"><span class="pre">disable_unicode=True</span></tt></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 <tt class="docutils literal"><span class="pre">string</span></tt> and <tt class="docutils literal"><span class="pre">unicode</span></tt>, and in Python 3 they are
- <tt class="docutils literal"><span class="pre">bytes</span></tt> and <tt class="docutils literal"><span class="pre">string</span></tt>. A key aspect of the Python 2 <tt class="docutils literal"><span class="pre">string</span></tt> and
- Python 3 <tt class="docutils literal"><span class="pre">bytes</span></tt> 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
- <tt class="docutils literal"><span class="pre">u"hello</span> <span class="pre">world"</span></tt> (or in Python 3, just <tt class="docutils literal"><span class="pre">"hello</span> <span class="pre">world"</span></tt>). 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
- <tt class="docutils literal"><span class="pre">unicode</span></tt>/<tt class="docutils literal"><span class="pre">string</span></tt> type to store strings, Python knows the
- data’s encoding; it’s in its own internal format. Whereas when
- using the <tt class="docutils literal"><span class="pre">string</span></tt>/<tt class="docutils literal"><span class="pre">bytes</span></tt> 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 <tt class="docutils literal"><span class="pre">ascii</span></tt>... 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 <tt class="docutils literal"><span class="pre">"hello</span> <span class="pre">world"</span></tt> 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 <tt class="docutils literal"><span class="pre">disable_unicode=True</span></tt>
- 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 <tt class="docutils literal"><span class="pre">unicode</span></tt>
- objects. It’s only at the point of <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></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"><em>the encoding of all non-ASCII templates is explicit</em></a> (still required in Python 3),
- that <a class="reference internal" href="#handling-non-ascii-expressions"><em>all non-ASCII-encoded expressions are in one way or another
- converted to unicode</em></a>
- (not much of a burden in Python 3), and that <a class="reference internal" href="#defining-output-encoding"><em>the output stream of the
- template is handled as a unicode stream being encoded to some
- encoding</em></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
- <tt class="docutils literal"><span class="pre">unicode</span></tt> object before continuing its parsing:</p>
- <div class="highlight-mako"><div class="highlight"><pre><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"><div class="highlight"><pre><span class="c">#.*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 <tt class="docutils literal"><span class="pre">ascii</span></tt>), 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"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> via
- the <tt class="docutils literal"><span class="pre">input_encoding</span></tt> parameter:</p>
- <div class="highlight-python"><div class="highlight"><pre><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="s">'./'</span><span class="p">],</span> <span class="n">input_encoding</span><span class="o">=</span><span class="s">'utf-8'</span><span class="p">)</span>
- </pre></div>
- </div>
- <p>The above will assume all located templates specify <tt class="docutils literal"><span class="pre">utf-8</span></tt>
- 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"><div class="highlight"><pre><span class="cp">${</span><span class="s">"hello world"</span><span class="cp">}</span><span class="x"></span>
- </pre></div>
- </div>
- <p>looks something like this:</p>
- <div class="highlight-python"><div class="highlight"><pre><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="s">"hello world"</span><span class="p">))</span>
- </pre></div>
- </div>
- <p>In Python 3, it’s just:</p>
- <div class="highlight-python"><div class="highlight"><pre><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="s">"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 <tt class="docutils literal"><span class="pre">unicode</span></tt> step serves
- both the purpose of rendering non-string expressions into
- strings (such as integers or objects which contain <tt class="docutils literal"><span class="pre">__str()__</span></tt>
- 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"><div class="highlight"><pre><span class="cp">${</span><span class="s">"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"><div class="highlight"><pre><span class="cp">${</span><span class="s">u"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"><div class="highlight"><pre><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="s">'utf-8'</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
- </pre></div>
- </div>
- <p>Note that filehandles acquired by <tt class="docutils literal"><span class="pre">open()</span></tt> in Python 3 default
- to returning “text”, that is the decoding is done for you. See
- Python 3’s documentation for the <tt class="docutils literal"><span class="pre">open()</span></tt> built-in for details on
- this.</p>
- <p>If you want a certain encoding applied to <em>all</em> expressions,
- override the <tt class="docutils literal"><span class="pre">unicode</span></tt> builtin with the <tt class="docutils literal"><span class="pre">decode</span></tt> built-in at the
- <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> level:</p>
- <div class="highlight-python"><div class="highlight"><pre><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="s">'decode.utf8'</span><span class="p">])</span>
- </pre></div>
- </div>
- <p>Note that the built-in <tt class="docutils literal"><span class="pre">decode</span></tt> object is slower than the
- <tt class="docutils literal"><span class="pre">unicode</span></tt> function, since unlike <tt class="docutils literal"><span class="pre">unicode</span></tt> 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 <tt class="docutils literal"><span class="pre">default_filters</span></tt> 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"><em>The default_filters Argument</em></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"><em>“Usage” chapter</em></a>, both <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> and
- <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> accept <tt class="docutils literal"><span class="pre">output_encoding</span></tt> and <tt class="docutils literal"><span class="pre">encoding_errors</span></tt>
- parameters which can be used to encode the output in any Python
- supported codec:</p>
- <div class="highlight-python"><div class="highlight"><pre><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="s">'/docs'</span><span class="p">],</span> <span class="n">output_encoding</span><span class="o">=</span><span class="s">'utf-8'</span><span class="p">,</span> <span class="n">encoding_errors</span><span class="o">=</span><span class="s">'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="s">"foo.txt"</span><span class="p">)</span>
- <span class="k">print</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"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a> will return a <tt class="docutils literal"><span class="pre">bytes</span></tt> 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"><tt class="xref py py-meth docutils literal"><span class="pre">render_unicode()</span></tt></a> will return the template output as a Python
- <tt class="docutils literal"><span class="pre">unicode</span></tt> object (or <tt class="docutils literal"><span class="pre">string</span></tt> in Python 3):</p>
- <div class="highlight-python"><div class="highlight"><pre><span class="k">print</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"><div class="highlight"><pre><span class="k">print</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="s">'utf-8'</span><span class="p">,</span> <span class="s">'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"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a> on a template that does not specify any
- output encoding (i.e. it’s <tt class="docutils literal"><span class="pre">ascii</span></tt>), Python’s <tt class="docutils literal"><span class="pre">cStringIO</span></tt> module,
- which cannot handle encoding of non-ASCII <tt class="docutils literal"><span class="pre">unicode</span></tt> objects
- (even though it can send raw byte-strings through), is used for
- buffering. Otherwise, a custom Mako class called
- <tt class="docutils literal"><span class="pre">FastEncodingBuffer</span></tt> is used, which essentially is a super
- dumbed-down version of <tt class="docutils literal"><span class="pre">StringIO</span></tt> that gathers all strings into
- a list and uses <tt class="docutils literal"><span class="pre">u''.join(elements)</span></tt> to produce the final output
- – it’s markedly faster than <tt class="docutils literal"><span class="pre">StringIO</span></tt>.</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 <tt class="docutils literal"><span class="pre">u""</span></tt> 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 <tt class="docutils literal"><span class="pre">disable_unicode=True</span></tt> flag as so:</p>
- <div class="highlight-python"><div class="highlight"><pre><span class="c"># -*- encoding: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="s">"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="s">'utf-8'</span><span class="p">)</span>
- <span class="k">print</span> <span class="n">t</span><span class="o">.</span><span class="n">code</span>
- </pre></div>
- </div>
- <p>The <tt class="docutils literal"><span class="pre">disable_unicode</span></tt> 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"><div class="highlight"><pre><span class="c"># -*- encoding:utf-8 -*-</span>
- <span class="c"># ...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="c"># SOURCE LINE 1</span>
- <span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">'dr</span><span class="se">\xc3\xb4</span><span class="s">le de petite voix m</span><span class="se">\xe2\x80\x99</span><span class="s">a r</span><span class="se">\xc3\xa9</span><span class="s">veill</span><span class="se">\xc3\xa9</span><span class="s">.'</span><span class="p">)</span>
- <span class="k">return</span> <span class="s">''</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"><tt class="xref py py-meth docutils literal"><span class="pre">Context.write()</span></tt></a>
- is a regular byte-string.</p>
- <p>When <tt class="docutils literal"><span class="pre">disable_unicode=True</span></tt> is turned on, the <tt class="docutils literal"><span class="pre">default_filters</span></tt>
- argument which normally defaults to <tt class="docutils literal"><span class="pre">["unicode"]</span></tt> now defaults
- to <tt class="docutils literal"><span class="pre">["str"]</span></tt> instead. Setting <tt class="docutils literal"><span class="pre">default_filters</span></tt> to the empty list
- <tt class="docutils literal"><span class="pre">[]</span></tt> can remove the overhead of the <tt class="docutils literal"><span class="pre">str</span></tt> 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"><tt class="xref py py-meth docutils literal"><span class="pre">render_unicode()</span></tt></a> – you’ll get
- unicode/decode errors.</p>
- <p>The <tt class="docutils literal"><span class="pre">h</span></tt> 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>
- <p class="versionchanged">
- <span class="versionmodified">Changed in version 0.3.4: </span>In prior versions, it used <tt class="docutils literal"><span class="pre">cgi.escape()</span></tt>, which has been replaced
- with a function that also escapes single quotes.</p>
- <div class="section" id="rules-for-using-disable-unicode-true">
- <h3>Rules for using <tt class="docutils literal"><span class="pre">disable_unicode=True</span></tt><a class="headerlink" href="#rules-for-using-disable-unicode-true" title="Permalink to this headline">¶</a></h3>
- <ul class="simple">
- <li>Don’t use this mode unless you really, really want to and you
- absolutely understand what you’re doing.</li>
- <li>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.</li>
- <li>Python 3 is unicode by default, and the flag is not available
- when running on Python 3.</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> 1.1.3
- with Mako templates.
- </div>
- </div>
- </div>
- <div class="clearfix">
- <hr/>
- <div class="copyright">Website content copyright © by Michael Bayer.
- All rights reserved. Mako and its documentation are licensed
- under the MIT license. mike(&)zzzcomputing.com</div>
- </div>
- </div>
- </body>
- </html>
|