1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<!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>(#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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '3.1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="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>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</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"><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"><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"><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"><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, Oleg Broytman; 2009-2012, R. Tyler Croy; 2001-2008, The Cheetah Development Team..
Last updated on Mar 03, 2018.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.5.
</div>
</body>
</html>
|
