diff options
Diffstat (limited to 'docs/html/cheps/2_import.html')
| -rw-r--r-- | docs/html/cheps/2_import.html | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/docs/html/cheps/2_import.html b/docs/html/cheps/2_import.html new file mode 100644 index 0000000..3f238ad --- /dev/null +++ b/docs/html/cheps/2_import.html @@ -0,0 +1,248 @@ + +<!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="X-UA-Compatible" content="IE=Edge" /> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <title>(#2) Conditionalized #import behavior — Cheetah3 - The Python-Powered Template Engine</title> + <link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" /> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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> + <script type="text/javascript" src="../_static/language_data.js"></script> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="(#3) Exposing of super() and self via Template searchList" href="3_super.html" /> + <link rel="prev" title="(#1) CHEP Purpose and Guidelines" href="1_chep.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <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="3_super.html" title="(#3) Exposing of super() and self via Template searchList" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="1_chep.html" title="(#1) CHEP Purpose and Guidelines" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Cheetah3 - The Python-Powered Template Engine</a> »</li> + <li class="nav-item nav-item-1"><a href="../chep.html" accesskey="U">Cheetah Enhancement Proposals</a> »</li> + </ul> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">(#2) Conditionalized #import behavior</a><ul> +<li><a class="reference internal" href="#abstract">Abstract</a></li> +<li><a class="reference internal" href="#motivation">Motivation</a></li> +<li><a class="reference internal" href="#specification">Specification</a></li> +<li><a class="reference internal" href="#rationale">Rationale</a></li> +<li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> +<li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> +<li><a class="reference internal" href="#copyright">Copyright</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="1_chep.html" + title="previous chapter">(#1) CHEP Purpose and Guidelines</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="3_super.html" + title="next chapter">(#3) Exposing of super() and self via Template searchList</a></p> + <div role="note" aria-label="source link"> + <h3>This Page</h3> + <ul class="this-page-menu"> + <li><a href="../_sources/cheps/2_import.rst.txt" + rel="nofollow">Show Source</a></li> + </ul> + </div> +<div id="searchbox" style="display: none" role="search"> + <h3>Quick search</h3> + <div class="searchformwrapper"> + <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> + </div> +</div> +<script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <div class="section" id="conditionalized-import-behavior"> +<h1>(#2) Conditionalized #import behavior<a class="headerlink" href="#conditionalized-import-behavior" title="Permalink to this headline">¶</a></h1> +<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">CHEP:</th><td class="field-body">2</td> +</tr> +<tr class="field-even field"><th class="field-name">Title:</th><td class="field-body">Conditionalized #import behavior</td> +</tr> +<tr class="field-odd field"><th class="field-name">Version:</th><td class="field-body">1</td> +</tr> +<tr class="field-even field"><th class="field-name">Author:</th><td class="field-body">R Tyler Ballance <tyler at slide.com></td> +</tr> +<tr class="field-odd field"><th class="field-name">Status:</th><td class="field-body">Draft</td> +</tr> +<tr class="field-even field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td> +</tr> +<tr class="field-odd field"><th class="field-name">Content-Type:</th><td class="field-body">text/x-rst</td> +</tr> +<tr class="field-even field"><th class="field-name">Created:</th><td class="field-body">07-Jun-2009</td> +</tr> +</tbody> +</table> +<hr class="docutils" /> +<div class="section" id="abstract"> +<h2>Abstract<a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2> +<p>This CHEP proposes an update to the way the #import and #from +directives are handled such that locally scoped imports and +module-level imports are handled appropriately.</p> +</div> +<div class="section" id="motivation"> +<h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2> +<p>Currently Cheetah (v2.2.1) provides two different, but mutually exclusive, +means of importing Python modules with the #from/#import directives. The +“traditional” handling for #from/#import (hereafter referred to as “module imports”) +is that the generated import statements shall all be relocated to +the top of the generated module’s source code, i.e.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>#import cjson + +Hello $cjson.encode([1, 2, 3]) +</pre></div> +</div> +<p>Will result in generated module code along the lines of:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">cjson</span> + +<span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">Template</span><span class="p">):</span> + <span class="k">def</span> <span class="nf">writeBody</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> + <span class="n">write</span><span class="p">(</span><span class="s1">'Hello '</span><span class="p">)</span> + <span class="n">write</span><span class="p">(</span><span class="n">cjson</span><span class="o">.</span><span class="n">encode</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]))</span> +</pre></div> +</div> +<p>Also currently in Cheetah is the ability to switch off this +behavior and enable location specific #from/#import handling +(hereafter referred to as “function imports”) in the generated +code, with this block of Cheetah for example:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#def aFunction(arg)</span> + <span class="c1">#try</span> + <span class="c1">#from hashlib import md5</span> + <span class="c1">#except ImportError</span> + <span class="c1">#from md5 import md5</span> + <span class="c1">#end try</span> + <span class="c1">#return $md5.new(arg).hexdigest()</span> +<span class="c1">#end def</span> +</pre></div> +</div> +<p>Will result in code generated with everything in +place such that the Python looks something like:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">Template</span><span class="p">):</span> + <span class="k">def</span> <span class="nf">aFunction</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span> + <span class="k">try</span><span class="p">:</span> + <span class="kn">from</span> <span class="nn">hashlib</span> <span class="k">import</span> <span class="n">md5</span> + <span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span> + <span class="kn">from</span> <span class="nn">md5</span> <span class="k">import</span> <span class="n">md5</span> + <span class="k">return</span> <span class="n">md5</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">()</span> +</pre></div> +</div> +<p>These two approaches to handling the #from/#import directives +are both beneficial for different situations but currently they +are handled in mutually exclusive code paths and in mutually +exclusive fashions.</p> +</div> +<div class="section" id="specification"> +<h2>Specification<a class="headerlink" href="#specification" title="Permalink to this headline">¶</a></h2> +<p>The change in #from/#import behavior and how these directives +are handled is all based on context of their use, making the +#from/#import handling “intelligent”. For module imports, the +“traditional” handling of the #from/#import directives will +still apply. Whereas function imports will result in inline +generated import code.</p> +<p>The basic premise of the change proposed by this document is +that all #from/#import directives contained within a #def/#end def +closure will result in import statements contained within that +function block whereas everywhere else the statements will be relocated +to the top of the generated module code (i.e. the module import)</p> +</div> +<div class="section" id="rationale"> +<h2>Rationale<a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2> +<p>The concept of the “function import” was introduced in Cheetah v2.1.0 +and quickly retrofitted to “live” behind a compiler setting due to the +regressions with older templates or templates that were designed to utilize +module imports (through heavy #block/#end block use, etc). Through discussion +with Tavis Rudd, this middle ground between the two styles of importing was +concluded to be the most reasonable solution to providing “pythonic” import +functionality (i.e. “function import” also known as “inline imports”) while +still providing the ability to have #from/#import directives declared at the +module scope within the template (within the Cheetah templates, markup and most +directives declared within the module scope are placed inside the default method).</p> +</div> +<div class="section" id="backwards-compatibility"> +<h2>Backwards Compatibility<a class="headerlink" href="#backwards-compatibility" title="Permalink to this headline">¶</a></h2> +<p>Changes proposed in this document should be <em>mostly</em> backwards +compatible with current versions of Cheetah, Any unforeseen issues +could arise from the use of #from/#import inside of a function +expecting those symbols to be available outside of the function +that they’re declared in.</p> +</div> +<div class="section" id="reference-implementation"> +<h2>Reference Implementation<a class="headerlink" href="#reference-implementation" title="Permalink to this headline">¶</a></h2> +<p><em>still in development</em></p> +</div> +<div class="section" id="copyright"> +<h2>Copyright<a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h2> +<p>This document has been placed in the public domain.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <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="3_super.html" title="(#3) Exposing of super() and self via Template searchList" + >next</a> |</li> + <li class="right" > + <a href="1_chep.html" title="(#1) CHEP Purpose and Guidelines" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Cheetah3 - The Python-Powered Template Engine</a> »</li> + <li class="nav-item nav-item-1"><a href="../chep.html" >Cheetah Enhancement Proposals</a> »</li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2017-2018, Oleg Broytman; 2009-2012, R. Tyler Croy; 2001-2008, The Cheetah Development Team.. + Last updated on Mar 19, 2019. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5. + </div> + </body> +</html>
\ No newline at end of file |