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
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
|
<!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>Cheetah.Template module — 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" />
</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="nav-item nav-item-0"><a href="../index.html">Cheetah3 - The Python-Powered Template Engine</a> »</li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/api/Cheetah.Template.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="module-Cheetah.Template">
<span id="cheetah-template-module"></span><h1>Cheetah.Template module<a class="headerlink" href="#module-Cheetah.Template" title="Permalink to this headline">¶</a></h1>
<p>Provides the core API for Cheetah</p>
<p>See the docstring in the Template class and the Users’ Guide
for more information.</p>
<dl class="class">
<dt id="Cheetah.Template.CompileCacheItem">
<em class="property">class </em><code class="descclassname">Cheetah.Template.</code><code class="descname">CompileCacheItem</code><a class="headerlink" href="#Cheetah.Template.CompileCacheItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">object</span></code></p>
</dd></dl>
<dl class="exception">
<dt id="Cheetah.Template.Error">
<em class="property">exception </em><code class="descclassname">Cheetah.Template.</code><code class="descname">Error</code><a class="headerlink" href="#Cheetah.Template.Error" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">exceptions.Exception</span></code></p>
</dd></dl>
<dl class="exception">
<dt id="Cheetah.Template.PreprocessError">
<em class="property">exception </em><code class="descclassname">Cheetah.Template.</code><code class="descname">PreprocessError</code><a class="headerlink" href="#Cheetah.Template.PreprocessError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#Cheetah.Template.Error" title="Cheetah.Template.Error"><code class="xref py py-class docutils literal"><span class="pre">Cheetah.Template.Error</span></code></a></p>
</dd></dl>
<dl class="attribute">
<dt id="Cheetah.Template.T">
<code class="descclassname">Cheetah.Template.</code><code class="descname">T</code><a class="headerlink" href="#Cheetah.Template.T" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <a class="reference internal" href="#Cheetah.Template.Template" title="Cheetah.Template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a></p>
</dd></dl>
<dl class="class">
<dt id="Cheetah.Template.Template">
<em class="property">class </em><code class="descclassname">Cheetah.Template.</code><code class="descname">Template</code><span class="sig-paren">(</span><em>source=None</em>, <em>namespaces=None</em>, <em>searchList=None</em>, <em>file=None</em>, <em>filter='RawOrEncodedUnicode'</em>, <em>filtersLib=<module 'Cheetah.Filters' from '/home/phd/current/projects/cheetah3/cheetah3/Cheetah/Filters.py'></em>, <em>errorCatcher=None</em>, <em>compilerSettings=Unspecified</em>, <em>_globalSetVars=None</em>, <em>_preBuiltSearchList=None</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="Cheetah.Servlet.html#Cheetah.Servlet.Servlet" title="Cheetah.Servlet.Servlet"><code class="xref py py-class docutils literal"><span class="pre">Cheetah.Servlet.Servlet</span></code></a></p>
<p>This class provides a) methods used by templates at runtime and b)
methods for compiling Cheetah source code into template classes.</p>
<p>This documentation assumes you already know Python and the basics of object
oriented programming. If you don’t know Python, see the sections of the
Cheetah Users’ Guide for non-programmers. It also assumes you have read
about Cheetah’s syntax in the Users’ Guide.</p>
<p>The following explains how to use Cheetah from within Python programs or
via the interpreter. If you statically compile your templates on the
command line using the ‘cheetah’ script, this is not relevant to you.
Statically compiled Cheetah template modules/classes (e.g. myTemplate.py:
MyTemplateClasss) are just like any other Python module or class. Also
note, most Python web frameworks (Webware, Aquarium, mod_python,
Turbogears, CherryPy, Quixote, etc.) provide plugins that handle Cheetah
compilation for you.</p>
<p>There are several possible usage patterns:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="mi">1</span><span class="p">)</span> <span class="n">tclass</span> <span class="o">=</span> <span class="n">Template</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
<span class="n">t1</span> <span class="o">=</span> <span class="n">tclass</span><span class="p">()</span> <span class="c1"># or tclass(namespaces=[namespace,...])</span>
<span class="n">t2</span> <span class="o">=</span> <span class="n">tclass</span><span class="p">()</span> <span class="c1"># or tclass(namespaces=[namespace2,...])</span>
<span class="n">outputStr</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">t1</span><span class="p">)</span> <span class="c1"># or outputStr = t1.aMethodYouDefined()</span>
<span class="n">Template</span><span class="o">.</span><span class="n">compile</span> <span class="n">provides</span> <span class="n">a</span> <span class="n">rich</span> <span class="ow">and</span> <span class="n">very</span> <span class="n">flexible</span> <span class="n">API</span> <span class="n">via</span> <span class="n">its</span>
<span class="n">optional</span> <span class="n">arguments</span> <span class="n">so</span> <span class="n">there</span> <span class="n">are</span> <span class="n">many</span> <span class="n">possible</span> <span class="n">variations</span> <span class="n">of</span> <span class="n">this</span>
<span class="n">pattern</span><span class="o">.</span> <span class="n">One</span> <span class="n">example</span> <span class="ow">is</span><span class="p">:</span>
<span class="n">tclass</span> <span class="o">=</span> <span class="n">Template</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s1">'hello $name from $caller'</span><span class="p">,</span>
<span class="n">baseclass</span><span class="o">=</span><span class="nb">dict</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">tclass</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'world'</span><span class="p">,</span> <span class="n">caller</span><span class="o">=</span><span class="s1">'me'</span><span class="p">))</span>
<span class="n">See</span> <span class="n">the</span> <span class="n">Template</span><span class="o">.</span><span class="n">compile</span><span class="p">()</span> <span class="n">docstring</span> <span class="k">for</span> <span class="n">more</span> <span class="n">details</span><span class="o">.</span>
<span class="mi">2</span><span class="p">)</span> <span class="n">tmplInstance</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
<span class="c1"># or Template(src, namespaces=[namespace,...])</span>
<span class="n">outputStr</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">tmplInstance</span><span class="p">)</span>
<span class="c1"># or outputStr = tmplInstance.aMethodYouDefined(...args...)</span>
</pre></div>
</div>
<p>Notes on the usage patterns:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">usage</span> <span class="n">pattern</span> <span class="mi">1</span><span class="p">)</span>
<span class="n">This</span> <span class="ow">is</span> <span class="n">the</span> <span class="n">most</span> <span class="n">flexible</span><span class="p">,</span> <span class="n">but</span> <span class="n">it</span> <span class="ow">is</span> <span class="n">slightly</span> <span class="n">more</span> <span class="n">verbose</span> <span class="n">unless</span> <span class="n">you</span>
<span class="n">write</span> <span class="n">a</span> <span class="n">wrapper</span> <span class="n">function</span> <span class="n">to</span> <span class="n">hide</span> <span class="n">the</span> <span class="n">plumbing</span><span class="o">.</span> <span class="n">Under</span> <span class="n">the</span> <span class="n">hood</span><span class="p">,</span> <span class="nb">all</span>
<span class="n">other</span> <span class="n">usage</span> <span class="n">patterns</span> <span class="n">are</span> <span class="n">based</span> <span class="n">on</span> <span class="n">this</span> <span class="n">approach</span><span class="o">.</span> <span class="n">Templates</span> <span class="n">compiled</span>
<span class="n">this</span> <span class="n">way</span> <span class="n">can</span> <span class="c1">#extend (subclass) any Python baseclass: old-style or</span>
<span class="n">new</span><span class="o">-</span><span class="n">style</span> <span class="p">(</span><span class="n">based</span> <span class="n">on</span> <span class="nb">object</span> <span class="ow">or</span> <span class="n">a</span> <span class="n">builtin</span> <span class="nb">type</span><span class="p">)</span><span class="o">.</span>
<span class="n">usage</span> <span class="n">pattern</span> <span class="mi">2</span><span class="p">)</span>
<span class="n">This</span> <span class="n">was</span> <span class="n">Cheetah</span><span class="s1">'s original usage pattern. It returns an instance,</span>
<span class="n">but</span> <span class="n">you</span> <span class="n">can</span> <span class="n">still</span> <span class="n">access</span> <span class="n">the</span> <span class="n">generated</span> <span class="k">class</span> <span class="nc">via</span>
<span class="n">tmplInstance</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span> <span class="n">If</span> <span class="n">you</span> <span class="n">want</span> <span class="n">to</span> <span class="n">use</span> <span class="n">several</span> <span class="n">different</span>
<span class="n">namespace</span> <span class="s1">'searchLists'</span> <span class="k">with</span> <span class="n">a</span> <span class="n">single</span> <span class="n">template</span> <span class="n">source</span> <span class="n">definition</span><span class="p">,</span>
<span class="n">you</span><span class="s1">'re better off with Template.compile (1).</span>
<span class="n">Limitations</span> <span class="p">(</span><span class="n">use</span> <span class="n">pattern</span> <span class="mi">1</span> <span class="n">instead</span><span class="p">)::</span>
<span class="o">-</span> <span class="n">Templates</span> <span class="n">compiled</span> <span class="n">this</span> <span class="n">way</span> <span class="n">can</span> <span class="n">only</span> <span class="c1">#extend subclasses of the</span>
<span class="n">new</span><span class="o">-</span><span class="n">style</span> <span class="s1">'object'</span> <span class="n">baseclass</span><span class="o">.</span> <span class="n">Cheetah</span><span class="o">.</span><span class="n">Template</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">subclass</span> <span class="n">of</span>
<span class="s1">'object'</span><span class="o">.</span> <span class="n">You</span> <span class="n">also</span> <span class="n">can</span> <span class="ow">not</span> <span class="c1">#extend dict, list, or other builtin</span>
<span class="n">types</span><span class="o">.</span>
<span class="o">-</span> <span class="n">If</span> <span class="n">your</span> <span class="n">template</span> <span class="n">baseclass</span><span class="s1">' __init__ constructor expects args</span>
<span class="n">there</span> <span class="ow">is</span> <span class="n">currently</span> <span class="n">no</span> <span class="n">way</span> <span class="n">to</span> <span class="k">pass</span> <span class="n">them</span> <span class="ow">in</span><span class="o">.</span>
</pre></div>
</div>
<p>If you need to subclass a dynamically compiled Cheetah class, do something
like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">Cheetah.Template</span> <span class="k">import</span> <span class="n">Template</span>
<span class="n">T1</span> <span class="o">=</span> <span class="n">Template</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s1">'$meth1 #def meth1: this is meth1 in T1'</span><span class="p">)</span>
<span class="n">T2</span> <span class="o">=</span> <span class="n">Template</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span>
<span class="s1">'#implements meth1</span><span class="se">\n</span><span class="s1">this is meth1 redefined in T2'</span><span class="p">,</span> <span class="n">baseclass</span><span class="o">=</span><span class="n">T1</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">T1</span><span class="p">,</span> <span class="n">T1</span><span class="p">())</span>
<span class="nb">print</span><span class="p">(</span><span class="n">T2</span><span class="p">,</span> <span class="n">T2</span><span class="p">())</span>
</pre></div>
</div>
<p>Note about class and instance attribute names:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Attributes</span> <span class="n">used</span> <span class="n">by</span> <span class="n">Cheetah</span> <span class="n">have</span> <span class="n">a</span> <span class="n">special</span> <span class="n">prefix</span> <span class="n">to</span> <span class="n">avoid</span> <span class="n">confusion</span> <span class="k">with</span>
<span class="n">the</span> <span class="n">attributes</span> <span class="n">of</span> <span class="n">the</span> <span class="n">templates</span> <span class="n">themselves</span> <span class="ow">or</span> <span class="n">those</span> <span class="n">of</span> <span class="n">template</span>
<span class="n">baseclasses</span><span class="o">.</span>
<span class="n">Class</span> <span class="n">attributes</span> <span class="n">which</span> <span class="n">are</span> <span class="n">used</span> <span class="ow">in</span> <span class="k">class</span> <span class="nc">methods</span> <span class="n">look</span> <span class="n">like</span> <span class="n">this</span><span class="p">::</span>
<span class="n">klass</span><span class="o">.</span><span class="n">_CHEETAH_useCompilationCache</span> <span class="p">(</span><span class="n">_CHEETAH_xxx</span><span class="p">)</span>
<span class="n">Instance</span> <span class="n">attributes</span> <span class="n">look</span> <span class="n">like</span> <span class="n">this</span><span class="p">::</span>
<span class="n">klass</span><span class="o">.</span><span class="n">_CHEETAH__globalSetVars</span> <span class="p">(</span><span class="n">_CHEETAH__xxx</span> <span class="k">with</span> <span class="mi">2</span> <span class="n">underscores</span><span class="p">)</span>
</pre></div>
</div>
<dl class="exception">
<dt id="Cheetah.Template.Template.NonNumericInputError">
<em class="property">exception </em><code class="descname">NonNumericInputError</code><a class="headerlink" href="#Cheetah.Template.Template.NonNumericInputError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">exceptions.ValueError</span></code></p>
</dd></dl>
<dl class="attribute">
<dt id="Cheetah.Template.Template.Reserved_SearchList">
<code class="descname">Reserved_SearchList</code><em class="property"> = set(['respond', '_CHEETAH_preprocessors', '__module__', '__format__', '_CHEETAH_defaultMainMethodNameForTemplates', '_CHEETAH_keepRefToGeneratedCode', 'serverSidePath', 'searchList', '__str__', '__getattribute__', '_getTemplateAPIClassForIncludeDirectiveCompilation', 'transaction', '_CHEETAH_defaultModuleNameForTemplates', '_CHEETAH_cacheCompilationResults', 'application', 'sleep', 'getCacheRegions', 'shutdown', 'hasVar', '__dict__', '__sizeof__', '__weakref__', '_createCacheRegion', '_CHEETAH_generatedModuleCode', 'runAsMainProgram', 'getCacheRegion', '__setattr__', '__reduce_ex__', '__new__', '__delattr__', '_normalizePreprocessorSettings', '_CHEETAH_compilerInstance', 'errorCatcher', '_CHEETAH_requiredCheetahClassMethods', '__class__', '_CHEETAH_useCompilationCache', '_updateSettingsWithPreprocessTokens', '_CHEETAH_cacheStoreIdPrefix', 'session', '_CHEETAH_defaultMainMethodName', '_normalizePreprocessorArg', 'getVar', '_compile', '_CHEETAH_cacheDirForModuleFiles', '__doc__', '_handleCheetahInclude', '_CHEETAH_compileLock', '_CHEETAH_defaultClassNameForTemplates', '_CHEETAH_requiredCheetahMethods', '_CHEETAH_compilerSettings', 'generatedClassCode', 'i18n', '_addCheetahPlumbingCodeToClass', '_CHEETAH_defaultBaseclassForTemplates', '_CHEETAH_defaultPreprocessorClass', '__hash__', 'webInput', '__subclasshook__', '_CHEETAH_requiredCheetahClassAttributes', '_CHEETAH_compileCache', '_CHEETAH_cacheStoreClass', '__reduce__', 'subclass', '_CHEETAH_cacheRegionClass', '_CHEETAH_cacheStore', '_initCheetahInstance', 'generatedModuleCode', '_CHEETAH_cacheModuleFilesForTracebacks', '_getCacheStore', '_getCacheStoreIdPrefix', 'refreshCache', '_getCompilerClass', 'request', 'getFileContents', 'compile', '_CHEETAH_compilerClass', '_preprocessSource', '_CHEETAH_defaultModuleGlobalsForTemplates', '__repr__', '__init__', 'NonNumericInputError', '_getCompilerSettings', 'varExists'])</em><a class="headerlink" href="#Cheetah.Template.Template.Reserved_SearchList" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="classmethod">
<dt id="Cheetah.Template.Template.compile">
<em class="property">classmethod </em><code class="descname">compile</code><span class="sig-paren">(</span><em>klass</em>, <em>source=None</em>, <em>file=None</em>, <em>returnAClass=True</em>, <em>compilerSettings=Unspecified</em>, <em>compilerClass=Unspecified</em>, <em>moduleName=None</em>, <em>className=Unspecified</em>, <em>mainMethodName=Unspecified</em>, <em>baseclass=Unspecified</em>, <em>moduleGlobals=Unspecified</em>, <em>cacheCompilationResults=Unspecified</em>, <em>useCache=Unspecified</em>, <em>preprocessors=Unspecified</em>, <em>cacheModuleFilesForTracebacks=Unspecified</em>, <em>cacheDirForModuleFiles=Unspecified</em>, <em>commandlineopts=None</em>, <em>keepRefToGeneratedCode=Unspecified</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.compile" title="Permalink to this definition">¶</a></dt>
<dd><p>The core API for compiling Cheetah source code into template classes.</p>
<p>This class method compiles Cheetah source code and returns a python
class. You then create template instances using that class. All
Cheetah’s other compilation API’s use this method under the hood.</p>
<p>Internally, this method a) parses the Cheetah source code and generates
Python code defining a module with a single class in it, b) dynamically
creates a module object with a unique name, c) execs the generated code
in that module’s namespace then inserts the module into sys.modules,
and d) returns a reference to the generated class. If you want to get
the generated python source code instead, pass the argument
returnAClass=False.</p>
<p>It caches generated code and classes. See the descriptions of the
arguments’cacheCompilationResults’ and ‘useCache’ for details. This
doesn’t mean that templates will automatically recompile themselves
when the source file changes. Rather, if you call Template.compile(src)
or Template.compile(file=path) repeatedly it will attempt to return a
cached class definition instead of recompiling.</p>
<p>Hooks are provided template source preprocessing. See the notes on the
‘preprocessors’ arg.</p>
<p>If you are an advanced user and need to customize the way Cheetah
parses source code or outputs Python code, you should check out
the compilerSettings argument.</p>
<p>Arguments:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>You must provide either a 'source' or 'file' arg, but not both::
- source (string or None)
- file (string path, file-like object, or None)
The rest of the arguments are strictly optional. All but the first
have defaults in attributes of the Template class which can be
overridden in subclasses of this class. Working with most of these
is an advanced topic.
::
- returnAClass=True
If false, return the generated module code rather than a class.
- compilerSettings (a dict)
Default: Template._CHEETAH_compilerSettings=None
a dictionary of settings to override those defined in
DEFAULT_COMPILER_SETTINGS. These can also be overridden in your
template source code with the #compiler or #compiler-settings
directives.
- compilerClass (a class)
Default: Template._CHEETAH_compilerClass=Cheetah.Compiler.Compiler
a subclass of Cheetah.Compiler.Compiler. Mucking with this is a
very advanced topic.
- moduleName (a string)
Default:
Template._CHEETAH_defaultModuleNameForTemplates
='DynamicallyCompiledCheetahTemplate'
What to name the generated Python module. If the provided value
is None and a file arg was given, the moduleName is created from
the file path. In all cases if the moduleName provided is
already in sys.modules it is passed through a filter that
generates a unique variant of the name.
- className (a string)
Default: Template._CHEETAH_defaultClassNameForTemplates=None
What to name the generated Python class. If the provided value
is None, the moduleName is use as the class name.
- mainMethodName (a string)
Default:
Template._CHEETAH_defaultMainMethodNameForTemplates
=None (and thus DEFAULT_COMPILER_SETTINGS['mainMethodName'])
What to name the main output generating method in the compiled
template class.
- baseclass (a string or a class)
Default: Template._CHEETAH_defaultBaseclassForTemplates=None
Specifies the baseclass for the template without manually
including an #extends directive in the source. The #extends
directive trumps this arg.
If the provided value is a string you must make sure that a class
reference by that name is available to your template, either by
using an #import directive or by providing it in the arg
'moduleGlobals'.
If the provided value is a class, Cheetah will handle all the
details for you.
- moduleGlobals (a dict)
Default: Template._CHEETAH_defaultModuleGlobalsForTemplates=None
A dict of vars that will be added to the global namespace of the
module the generated code is executed in, prior to the execution
of that code. This should be Python values, not code strings!
- cacheCompilationResults (True/False)
Default: Template._CHEETAH_cacheCompilationResults=True
Tells Cheetah to cache the generated code and classes so that
they can be reused if Template.compile() is called multiple times
with the same source and options.
- useCache (True/False)
Default: Template._CHEETAH_useCompilationCache=True
Should the compilation cache be used? If True and a previous
compilation created a cached template class with the same source
code, compiler settings and other options, the cached template
class will be returned.
- cacheModuleFilesForTracebacks (True/False)
Default: Template._CHEETAH_cacheModuleFilesForTracebacks=False
In earlier versions of Cheetah tracebacks from exceptions that
were raised inside dynamically compiled Cheetah templates were
opaque because Python didn't have access to a python source file
to use in the traceback:
File "xxxx.py", line 192, in getTextiledContent
content = str(template(searchList=searchList))
File "cheetah_yyyy.py", line 202, in __str__
File "cheetah_yyyy.py", line 187, in respond
File "cheetah_yyyy.py", line 139, in writeBody
ZeroDivisionError: integer division or modulo by zero
It is now possible to keep those files in a cache dir and allow
Python to include the actual source lines in tracebacks and makes
them much easier to understand:
File "xxxx.py", line 192, in getTextiledContent
content = str(template(searchList=searchList))
File "/tmp/CheetahCacheDir/cheetah_yyyy.py", line 202, in __str__
def __str__(self): return self.respond()
File "/tmp/CheetahCacheDir/cheetah_yyyy.py", line 187, in respond
self.writeBody(trans=trans)
File "/tmp/CheetahCacheDir/cheetah_yyyy.py", line 139, in writeBody
__v = 0/0 # $(0/0)
ZeroDivisionError: integer division or modulo by zero
- cacheDirForModuleFiles (a string representing a dir path)
Default: Template._CHEETAH_cacheDirForModuleFiles=None
See notes on cacheModuleFilesForTracebacks.
- preprocessors
Default: Template._CHEETAH_preprocessors=None
** THIS IS A VERY ADVANCED TOPIC **
These are used to transform the source code prior to compilation.
They provide a way to use Cheetah as a code generator for Cheetah
code. In other words, you use one Cheetah template to output the
source code for another Cheetah template.
The major expected use cases are:
a) 'compile-time caching' aka 'partial template binding',
wherein an intermediate Cheetah template is used to output
the source for the final Cheetah template. The intermediate
template is a mix of a modified Cheetah syntax (the
'preprocess syntax') and standard Cheetah syntax. The
preprocessor syntax is executed at compile time and outputs
Cheetah code which is then compiled in turn. This approach
allows one to completely soft-code all the elements in the
template which are subject to change yet have it compile to
extremely efficient Python code with everything but the
elements that must be variable at runtime (per browser
request, etc.) compiled as static strings. Examples of this
usage pattern will be added to the Cheetah Users' Guide.
The'preprocess syntax' is just Cheetah's standard one with
alternatives for the $ and # tokens:
e.g. '@' and '%' for code like this
@aPreprocessVar $aRuntimeVar
%if aCompileTimeCondition then yyy else zzz
%% preprocessor comment
#if aRunTimeCondition then aaa else bbb
## normal comment
$aRuntimeVar
b) adding #import and #extends directives dynamically based on
the source
If preprocessors are provided, Cheetah pipes the source code
through each one in the order provided. Each preprocessor should
accept the args (source, file) and should return a tuple (source,
file).
The argument value should be a list, but a single non-list value
is acceptable and will automatically be converted into a list.
Each item in the list will be passed through
Template._normalizePreprocessor(). The items should either match
one of the following forms:
- an object with a .preprocess(source, file) method
- a callable with the following signature:
source, file = f(source, file)
or one of the forms below:
- a single string denoting the 2 'tokens' for the preprocess
syntax. The tokens should be in the order (placeholderToken,
directiveToken) and should separated with a space:
e.g. '@ %'
klass = Template.compile(src, preprocessors='@ %')
# or
klass = Template.compile(src, preprocessors=['@ %'])
- a dict with the following keys or an object with the
following attributes (all are optional, but nothing will
happen if you don't provide at least one):
- tokens: same as the single string described above. You can
also provide a tuple of 2 strings.
- searchList: the searchList used
for preprocess $placeholders
- compilerSettings: used in the compilation
of the intermediate template
- templateAPIClass: an optional subclass of `Template`
- outputTransformer: a simple hook for passing in a callable
which can do further transformations of the preprocessor
output, or do something else like debug logging. The
default is str().
+ any keyword arguments to Template.compile which you want
to provide for the compilation
of the intermediate template.
klass = Template.compile(
src,
preprocessors=[dict(tokens='@ %', searchList=[...])])
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.errorCatcher">
<code class="descname">errorCatcher</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.errorCatcher" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a reference to the current errorCatcher</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.generatedClassCode">
<code class="descname">generatedClassCode</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.generatedClassCode" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the class code the compiler generated, or None if no
compilation took place.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.generatedModuleCode">
<code class="descname">generatedModuleCode</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.generatedModuleCode" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the module code the compiler generated, or None if no
compilation took place.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.getCacheRegion">
<code class="descname">getCacheRegion</code><span class="sig-paren">(</span><em>regionID</em>, <em>cacheInfo=None</em>, <em>create=True</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.getCacheRegion" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.getCacheRegions">
<code class="descname">getCacheRegions</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.getCacheRegions" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a dictionary of the ‘cache regions’ initialized in a
template.</p>
<p>Each #cache directive block or $*cachedPlaceholder is a separate ‘cache
region’.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.getFileContents">
<code class="descname">getFileContents</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.getFileContents" title="Permalink to this definition">¶</a></dt>
<dd><p>A hook for getting the contents of a file. The default
implementation just uses the Python open() function
to load local files. This method could be reimplemented
to allow reading of remote files via various protocols,
as PHP allows with its ‘URL fopen wrapper’.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.getVar">
<code class="descname">getVar</code><span class="sig-paren">(</span><em>varName</em>, <em>default=Unspecified</em>, <em>autoCall=True</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.getVar" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a variable from the searchList. If the variable can’t be found
in the searchList, it returns the default value if one was given, or
raises NameMapper.NotFound.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.hasVar">
<code class="descname">hasVar</code><span class="sig-paren">(</span><em>varName</em>, <em>autoCall=True</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.hasVar" title="Permalink to this definition">¶</a></dt>
<dd><p>Test if a variable name exists in the searchList.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.i18n">
<code class="descname">i18n</code><span class="sig-paren">(</span><em>message</em>, <em>plural=None</em>, <em>n=None</em>, <em>id=None</em>, <em>domain=None</em>, <em>source=None</em>, <em>target=None</em>, <em>comment=None</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.i18n" title="Permalink to this definition">¶</a></dt>
<dd><p>This is just a stub at this time.</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">plural</span> <span class="o">=</span> <span class="n">the</span> <span class="n">plural</span> <span class="n">form</span> <span class="n">of</span> <span class="n">the</span> <span class="n">message</span>
<span class="n">n</span> <span class="o">=</span> <span class="n">a</span> <span class="n">sized</span> <span class="n">argument</span> <span class="n">to</span> <span class="n">distinguish</span>
<span class="n">between</span> <span class="n">single</span> <span class="ow">and</span> <span class="n">plural</span> <span class="n">forms</span>
<span class="nb">id</span> <span class="o">=</span> <span class="n">msgid</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">translation</span> <span class="n">catalog</span>
<span class="n">domain</span> <span class="o">=</span> <span class="n">translation</span> <span class="n">domain</span>
<span class="n">source</span> <span class="o">=</span> <span class="n">source</span> <span class="n">lang</span>
<span class="n">target</span> <span class="o">=</span> <span class="n">a</span> <span class="n">specific</span> <span class="n">target</span> <span class="n">lang</span>
<span class="n">comment</span> <span class="o">=</span> <span class="n">a</span> <span class="n">comment</span> <span class="n">to</span> <span class="n">the</span> <span class="n">translation</span> <span class="n">team</span>
</pre></div>
</div>
</div></blockquote>
<p>See the following for some ideas
<a class="reference external" href="http://www.zope.org/DevHome/Wikis/DevSite/Projects/ComponentArchitecture/ZPTInternationalizationSupport">http://www.zope.org/DevHome/Wikis/DevSite/Projects/ComponentArchitecture/ZPTInternationalizationSupport</a></p>
<p>Other notes:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="n">There</span> <span class="ow">is</span> <span class="n">no</span> <span class="n">need</span> <span class="n">to</span> <span class="n">replicate</span> <span class="n">the</span> <span class="n">i18n</span><span class="p">:</span><span class="n">name</span> <span class="n">attribute</span>
<span class="kn">from</span> <span class="nn">plone</span> <span class="o">/</span> <span class="n">PTL</span><span class="p">,</span> <span class="k">as</span> <span class="n">cheetah</span> <span class="n">placeholders</span> <span class="n">serve</span> <span class="n">the</span> <span class="n">same</span> <span class="n">purpose</span><span class="o">.</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.refreshCache">
<code class="descname">refreshCache</code><span class="sig-paren">(</span><em>cacheRegionId=None</em>, <em>cacheItemId=None</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.refreshCache" title="Permalink to this definition">¶</a></dt>
<dd><p>Refresh a cache region or a specific cache item within a region.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.runAsMainProgram">
<code class="descname">runAsMainProgram</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.runAsMainProgram" title="Permalink to this definition">¶</a></dt>
<dd><p>Allows the Template to function as a standalone command-line program
for static page generation.</p>
<p>Type ‘python yourtemplate.py –help to see what it’s capabable of.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.searchList">
<code class="descname">searchList</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.searchList" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a reference to the searchlist</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.shutdown">
<code class="descname">shutdown</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.shutdown" title="Permalink to this definition">¶</a></dt>
<dd><p>Break reference cycles before discarding a servlet.</p>
</dd></dl>
<dl class="classmethod">
<dt id="Cheetah.Template.Template.subclass">
<em class="property">classmethod </em><code class="descname">subclass</code><span class="sig-paren">(</span><em>klass</em>, <em>*args</em>, <em>**kws</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.subclass" title="Permalink to this definition">¶</a></dt>
<dd><p>Takes the same args as the .compile() classmethod and returns a
template that is a subclass of the template this method is called from.</p>
<dl class="docutils">
<dt>T1 = Template.compile(</dt>
<dd>‘foo - $meth1 - barn#def meth1: this is T1.meth1’)</dd>
</dl>
<p>T2 = T1.subclass(‘#implements meth1n this is T2.meth1’)</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.varExists">
<code class="descname">varExists</code><span class="sig-paren">(</span><em>varName</em>, <em>autoCall=True</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.varExists" title="Permalink to this definition">¶</a></dt>
<dd><p>Test if a variable name exists in the searchList.</p>
</dd></dl>
<dl class="method">
<dt id="Cheetah.Template.Template.webInput">
<code class="descname">webInput</code><span class="sig-paren">(</span><em>names</em>, <em>namesMulti=()</em>, <em>default=''</em>, <em>src='f'</em>, <em>defaultInt=0</em>, <em>defaultFloat=0.0</em>, <em>badInt=0</em>, <em>badFloat=0.0</em>, <em>debug=False</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.Template.webInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Method for importing web transaction variables in bulk.</p>
<p>This works for GET/POST fields both in Webware servlets and in CGI
scripts, and for cookies and session variables in Webware servlets.
If you try to read a cookie or session variable in a CGI script,
you’ll get a RuntimeError. ‘In a CGI script’ here means
‘not running as a Webware servlet’. If the CGI environment
is not properly set up, Cheetah will act like there’s no input.</p>
<p>The public method provided is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">webInput</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">names</span><span class="p">,</span> <span class="n">namesMulti</span><span class="o">=</span><span class="p">(),</span> <span class="n">default</span><span class="o">=</span><span class="s1">''</span><span class="p">,</span> <span class="n">src</span><span class="o">=</span><span class="s1">'f'</span><span class="p">,</span>
<span class="n">defaultInt</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">defaultFloat</span><span class="o">=</span><span class="mf">0.00</span><span class="p">,</span>
<span class="n">badInt</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">badFloat</span><span class="o">=</span><span class="mf">0.00</span><span class="p">,</span> <span class="n">debug</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
</pre></div>
</div>
<p>This method places the specified GET/POST fields, cookies or session
variables into a dictionary, which is both returned and put at the
beginning of the searchList. It handles:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*</span> <span class="n">single</span> <span class="n">vs</span> <span class="n">multiple</span> <span class="n">values</span>
<span class="o">*</span> <span class="n">conversion</span> <span class="n">to</span> <span class="n">integer</span> <span class="ow">or</span> <span class="nb">float</span> <span class="k">for</span> <span class="n">specified</span> <span class="n">names</span>
<span class="o">*</span> <span class="n">default</span> <span class="n">values</span><span class="o">/</span><span class="n">exceptions</span> <span class="k">for</span> <span class="n">missing</span> <span class="ow">or</span> <span class="n">bad</span> <span class="n">values</span>
<span class="o">*</span> <span class="n">printing</span> <span class="n">a</span> <span class="n">snapshot</span> <span class="n">of</span> <span class="nb">all</span> <span class="n">values</span> <span class="n">retrieved</span> <span class="k">for</span> <span class="n">debugging</span>
</pre></div>
</div>
<p>All the ‘default*’ and ‘bad*’ arguments have ‘use or raise’ behavior,
meaning that if they’re a subclass of Exception, they’re raised. If
they’re anything else, that value is substituted for the missing/bad
value.</p>
<p>The simplest usage is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>#silent $webInput(['choice'])
$choice
dic = self.webInput(['choice'])
write(dic['choice'])
</pre></div>
</div>
<p>Both these examples retrieves the GET/POST field ‘choice’ and print it.
If you leave off the’#silent’, all the values would be printed too.
But a better way to preview the values is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1">#silent $webInput(['name'], $debug=1)</span>
</pre></div>
</div>
<p>because this pretty-prints all the values inside HTML <PRE> tags.</p>
<p>*** KLUDGE: ‘debug’ is supposed to insert into the template output,
but it wasn’t working so I changed it to a’print’ statement.
So the debugging output will appear wherever standard output
is pointed, whether at the terminal, in a Webware log file,
or whatever. ***</p>
<p>Since we didn’t specify any coversions, the value is a string. It’s a
‘single’ value because we specified it in ‘names’ rather than
‘namesMulti’. Single values work like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*</span> <span class="n">If</span> <span class="n">one</span> <span class="n">value</span> <span class="ow">is</span> <span class="n">found</span><span class="p">,</span> <span class="n">take</span> <span class="n">it</span><span class="o">.</span>
<span class="o">*</span> <span class="n">If</span> <span class="n">several</span> <span class="n">values</span> <span class="n">are</span> <span class="n">found</span><span class="p">,</span> <span class="n">choose</span> <span class="n">one</span> <span class="n">arbitrarily</span>
<span class="ow">and</span> <span class="n">ignore</span> <span class="n">the</span> <span class="n">rest</span><span class="o">.</span>
<span class="o">*</span> <span class="n">If</span> <span class="n">no</span> <span class="n">values</span> <span class="n">are</span> <span class="n">found</span><span class="p">,</span> <span class="n">use</span> <span class="ow">or</span> <span class="k">raise</span>
<span class="n">the</span> <span class="n">appropriate</span> <span class="s1">'default*'</span> <span class="n">value</span><span class="o">.</span>
</pre></div>
</div>
<p>Multi values work like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">*</span> <span class="n">If</span> <span class="n">one</span> <span class="n">value</span> <span class="ow">is</span> <span class="n">found</span><span class="p">,</span> <span class="n">put</span> <span class="n">it</span> <span class="ow">in</span> <span class="n">a</span> <span class="nb">list</span><span class="o">.</span>
<span class="o">*</span> <span class="n">If</span> <span class="n">several</span> <span class="n">values</span> <span class="n">are</span> <span class="n">found</span><span class="p">,</span> <span class="n">leave</span> <span class="n">them</span> <span class="ow">in</span> <span class="n">a</span> <span class="nb">list</span><span class="o">.</span>
<span class="o">*</span> <span class="n">If</span> <span class="n">no</span> <span class="n">values</span> <span class="n">are</span> <span class="n">found</span><span class="p">,</span> <span class="n">use</span> <span class="n">the</span> <span class="n">empty</span> <span class="nb">list</span> <span class="p">([])</span><span class="o">.</span> <span class="n">The</span> <span class="s1">'default*'</span>
<span class="n">arguments</span> <span class="n">are</span> <span class="o">*</span><span class="ow">not</span><span class="o">*</span> <span class="n">consulted</span> <span class="ow">in</span> <span class="n">this</span> <span class="n">case</span><span class="o">.</span>
</pre></div>
</div>
<p>Example: assume ‘days’ came from a set of checkboxes
or a multiple combo box on a form, and the user chose’Monday’,
‘Tuesday’ and ‘Thursday’:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>#silent $webInput([], ['days'])
The days you chose are: #slurp
#for $day in $days
$day #slurp
#end for
dic = self.webInput([], ['days'])
write('The days you chose are: ')
for day in dic['days']:
write(day + ' ')
</pre></div>
</div>
<p>Both these examples print: ‘The days you chose are:
Monday Tuesday Thursday’.</p>
<p>By default, missing strings are replaced by ‘’ and missing/bad numbers
by zero. (A’bad number’ means the converter raised an exception for
it, usually because of non-numeric characters in the value.) This
mimics Perl/PHP behavior, and simplifies coding for many applications
where missing/bad values <em>should</em> be blank/zero. In those relatively
few cases where you must distinguish between empty-string/zero on the
one hand and missing/bad on the other, change the appropriate
‘default*’ and ‘bad*’ arguments to something like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>* None
* another constant value
* $NonNumericInputError/self.NonNumericInputError
* $ValueError/ValueError
</pre></div>
</div>
<p>(NonNumericInputError is defined in this class and is useful for
distinguishing between bad input vs a TypeError/ValueError thrown for
some other rason.)</p>
<p>Here’s an example using multiple values to schedule newspaper
deliveries. ‘checkboxes’ comes from a form with checkboxes for all the
days of the week. The days the user previously chose are preselected.
The user checks/unchecks boxes as desired and presses Submit.
The value of ‘checkboxes’ is a list of checkboxes that were checked
when Submit was pressed. Our task now is to turn on the days
the user checked, turn off the days he unchecked, and leave on or off
the days he didn’t change.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">dic</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">webInput</span><span class="p">([],</span> <span class="p">[</span><span class="s1">'dayCheckboxes'</span><span class="p">])</span>
<span class="n">wantedDays</span> <span class="o">=</span> <span class="n">dic</span><span class="p">[</span><span class="s1">'dayCheckboxes'</span><span class="p">]</span> <span class="c1"># The days the user checked.</span>
<span class="k">for</span> <span class="n">day</span><span class="p">,</span> <span class="n">on</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">getAllValues</span><span class="p">():</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">on</span> <span class="ow">and</span> <span class="n">day</span> <span class="ow">in</span> <span class="n">wantedDays</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">TurnOn</span><span class="p">(</span><span class="n">day</span><span class="p">)</span>
<span class="c1"># ... Set a flag or insert a database record ...</span>
<span class="k">elif</span> <span class="n">on</span> <span class="ow">and</span> <span class="n">day</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">wantedDays</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">TurnOff</span><span class="p">(</span><span class="n">day</span><span class="p">)</span>
<span class="c1"># ... Unset a flag or delete a database record ...</span>
</pre></div>
</div>
<p>‘source’ allows you to look up the variables from a number of different
sources:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="s1">'f'</span> <span class="n">fields</span> <span class="p">(</span><span class="n">CGI</span> <span class="n">GET</span><span class="o">/</span><span class="n">POST</span> <span class="n">parameters</span><span class="p">)</span>
<span class="s1">'c'</span> <span class="n">cookies</span>
<span class="s1">'s'</span> <span class="n">session</span> <span class="n">variables</span>
<span class="s1">'v'</span> <span class="s1">'values'</span><span class="p">,</span> <span class="n">meaning</span> <span class="n">fields</span> <span class="ow">or</span> <span class="n">cookies</span>
</pre></div>
</div>
<p>In many forms, you’re dealing only with strings, which is why the
‘default’ argument is third and the numeric arguments are banished to
the end. But sometimes you want automatic number conversion, so that
you can do numeric comparisions in your templates without having to
write a bunch of conversion/exception handling code. Example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>#silent $webInput(['name', 'height:int'])
$name is $height cm tall.
#if $height >= 300
Wow, you're tall!
#else
Pshaw, you're short.
#end if
dic = self.webInput(['name', 'height:int'])
name = dic[name]
height = dic[height]
write('%s is %s cm tall.' % (name, height))
if height > 300:
write('Wow, you're tall!')
else:
write('Pshaw, you're short.')
</pre></div>
</div>
<p>To convert a value to a number, suffix ‘:int’ or ‘:float’ to the name.
The method will search first for a ‘height:int’ variable
and then for a ‘height’ variable. (It will be called ‘height’
in the final dictionary.) If a numeric conversion fails,
use or raise ‘badInt’ or ‘badFloat’. Missing values work the same way
as for strings, except the default is ‘defaultInt’
or ‘defaultFloat’ instead of ‘default’.</p>
<p>If a name represents an uploaded file, the entire file will be read
into memory. For more sophistocated file-upload handling,
leave that name out of the list and do your own handling,
or wait for Cheetah.Utils.UploadFileMixin.</p>
<p>This only in a subclass that also inherits from Webware’s Servlet or
HTTPServlet. Otherwise you’ll get an AttributeError on ‘self.request’.</p>
<p>EXCEPTIONS: ValueError if ‘source’ is not one of the stated characters.
TypeError if a conversion suffix is not ‘:int’ or ‘:float’.</p>
<p>FUTURE EXPANSION: a future version of this method may allow source
cascading; e.g., ‘vs’ would look first in ‘values’ and then in session
variables.</p>
<p>Meta-Data:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Author</span><span class="p">:</span> <span class="n">Mike</span> <span class="n">Orr</span> <span class="o"><</span><span class="n">iron</span><span class="nd">@mso</span><span class="o">.</span><span class="n">oz</span><span class="o">.</span><span class="n">net</span><span class="o">></span>
<span class="n">License</span><span class="p">:</span> <span class="n">This</span> <span class="n">software</span> <span class="ow">is</span> <span class="n">released</span> <span class="k">for</span> <span class="n">unlimited</span> <span class="n">distribution</span>
<span class="n">under</span> <span class="n">the</span> <span class="n">terms</span> <span class="n">of</span> <span class="n">the</span> <span class="n">MIT</span> <span class="n">license</span><span class="o">.</span> <span class="n">See</span> <span class="n">the</span> <span class="n">LICENSE</span> <span class="n">file</span><span class="o">.</span>
<span class="n">Version</span><span class="p">:</span> <span class="mf">1.186</span>
<span class="n">Start</span> <span class="n">Date</span><span class="p">:</span> <span class="mi">2002</span><span class="o">/</span><span class="mi">03</span><span class="o">/</span><span class="mi">17</span>
<span class="n">Last</span> <span class="n">Revision</span> <span class="n">Date</span><span class="p">:</span> <span class="mi">2008</span><span class="o">/</span><span class="mi">03</span><span class="o">/</span><span class="mi">10</span> <span class="mi">04</span><span class="p">:</span><span class="mi">48</span><span class="p">:</span><span class="mi">11</span>
</pre></div>
</div>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="Cheetah.Template.TemplatePreprocessor">
<em class="property">class </em><code class="descclassname">Cheetah.Template.</code><code class="descname">TemplatePreprocessor</code><span class="sig-paren">(</span><em>settings</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.TemplatePreprocessor" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">object</span></code></p>
<p>This is used with the preprocessors argument to Template.compile().</p>
<p>See the docstring for Template.compile</p>
<p>** Preprocessors are an advanced topic **</p>
<dl class="method">
<dt id="Cheetah.Template.TemplatePreprocessor.preprocess">
<code class="descname">preprocess</code><span class="sig-paren">(</span><em>source</em>, <em>file</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.TemplatePreprocessor.preprocess" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an intermediate template and return the source code
it outputs</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="Cheetah.Template.checkFileMtime">
<code class="descclassname">Cheetah.Template.</code><code class="descname">checkFileMtime</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.checkFileMtime" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="Cheetah.Template.createMethod">
<code class="descclassname">Cheetah.Template.</code><code class="descname">createMethod</code><span class="sig-paren">(</span><em>func</em>, <em>cls</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.createMethod" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="Cheetah.Template.genParserErrorFromPythonException">
<code class="descclassname">Cheetah.Template.</code><code class="descname">genParserErrorFromPythonException</code><span class="sig-paren">(</span><em>source</em>, <em>file</em>, <em>generatedPyCode</em>, <em>exception</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.genParserErrorFromPythonException" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="Cheetah.Template.hashDict">
<code class="descclassname">Cheetah.Template.</code><code class="descname">hashDict</code><span class="sig-paren">(</span><em>d</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.hashDict" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="Cheetah.Template.hashList">
<code class="descclassname">Cheetah.Template.</code><code class="descname">hashList</code><span class="sig-paren">(</span><em>l</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.hashList" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="Cheetah.Template.updateLinecache">
<code class="descclassname">Cheetah.Template.</code><code class="descname">updateLinecache</code><span class="sig-paren">(</span><em>filename</em>, <em>src</em><span class="sig-paren">)</span><a class="headerlink" href="#Cheetah.Template.updateLinecache" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</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="nav-item nav-item-0"><a href="../index.html">Cheetah3 - The Python-Powered Template Engine</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>
|
