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
|
<!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>Error Handling — 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="Instructions to the Parser/Compiler" href="parserInstructions.html" />
<link rel="prev" title="Flow Control" href="flowControl.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="parserInstructions.html" title="Instructions to the Parser/Compiler"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="flowControl.html" title="Flow Control"
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="index.html" accesskey="U">Cheetah User’s Guide</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="#">Error Handling</a><ul>
<li><a class="reference internal" href="#try-except-end-try-finally-and-assert">#try … #except … #end try, #finally, and #assert</a></li>
<li><a class="reference internal" href="#errorcatcher-and-errorcatcher-objects">#errorCatcher and ErrorCatcher objects</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="flowControl.html"
title="previous chapter">Flow Control</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="parserInstructions.html"
title="next chapter">Instructions to the Parser/Compiler</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/users_guide/errorHandling.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="error-handling">
<h1>Error Handling<a class="headerlink" href="#error-handling" title="Permalink to this headline">¶</a></h1>
<p>(errorHandling)</p>
<p>There are two ways to handle runtime errors (exceptions) in
Cheetah. The first is with the Cheetah directives that mirror
Python’s structured exception handling statements. The second is
with Cheetah’s {ErrorCatcher} framework. These are described
below.</p>
<div class="section" id="try-except-end-try-finally-and-assert">
<h2>#try … #except … #end try, #finally, and #assert<a class="headerlink" href="#try-except-end-try-finally-and-assert" title="Permalink to this headline">¶</a></h2>
<p>(errorHandling.directives)</p>
<p>Cheetah’s exception-handling directives are exact mirrors Python’s
exception-handling statements. See Python’s documentation for
details. The following Cheetah code demonstrates their use:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>#try
$mightFail()
#except
It failed
#end try
#try
#assert $x == $y
#except AssertionError
They're not the same!
#end try
#try
#raise ValueError
#except ValueError
#pass
#end try
#try
$mightFail()
#except ValueError
Hey, it raised a ValueError!
#except NameMapper.NotFound
Hey, it raised a NameMapper.NotFound!
#else
It didn't raise anything!
#end try
#try
$mightFail()
#finally
$cleanup()
#end try
</pre></div>
</div>
<p>Like Python, {#except} and {#finally} cannot appear in the same
try-block, but can appear in nested try-blocks.</p>
</div>
<div class="section" id="errorcatcher-and-errorcatcher-objects">
<h2>#errorCatcher and ErrorCatcher objects<a class="headerlink" href="#errorcatcher-and-errorcatcher-objects" title="Permalink to this headline">¶</a></h2>
<p>(errorHandling.errorCatcher)</p>
<p>Syntax:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1">#errorCatcher CLASS</span>
<span class="c1">#errorCatcher $PLACEHOLDER_TO_AN_ERROR_CATCHER_INSTANCE</span>
</pre></div>
</div>
<p>{ErrorCatcher} is a debugging tool that catches exceptions that
occur inside {$placeholder} tags and provides a customizable
warning to the developer. Normally, the first missing namespace
value raises a {NameMapper.NotFound} error and halts the filling of
the template. This requires the developer to resolve the exceptions
in order without seeing the subsequent output. When an
{ErrorCatcher} is enabled, the developer can see all the exceptions
at once as well as the template output around them.</p>
<p>The {Cheetah.ErrorCatchers} module defines the base class for
ErrorCatchers:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ErrorCatcher</span><span class="p">:</span>
<span class="n">_exceptionsToCatch</span> <span class="o">=</span> <span class="p">(</span><span class="n">NameMapper</span><span class="o">.</span><span class="n">NotFound</span><span class="p">,)</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">templateObj</span><span class="p">):</span>
<span class="k">pass</span>
<span class="k">def</span> <span class="nf">exceptions</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_exceptionsToCatch</span>
<span class="k">def</span> <span class="nf">warn</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc_val</span><span class="p">,</span> <span class="n">code</span><span class="p">,</span> <span class="n">rawCode</span><span class="p">,</span> <span class="n">lineCol</span><span class="p">):</span>
<span class="k">return</span> <span class="n">rawCode</span>
</pre></div>
</div>
<p>This ErrorCatcher catches {NameMapper.NotFound} exceptions and
leaves the offending placeholder visible in its raw form in the
template output. If the following template is executed:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1">#errorCatcher Echo</span>
<span class="c1">#set $iExist = 'Here I am!'</span>
<span class="n">Here</span><span class="s1">'s a good placeholder: $iExist</span>
<span class="n">Here</span><span class="s1">'s bad placeholder: $iDontExist</span>
</pre></div>
</div>
<p>the output will be:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Here</span><span class="s1">'s a good placeholder: Here I am!</span>
<span class="n">Here</span><span class="s1">'s bad placeholder: $iDontExist</span>
</pre></div>
</div>
<p>The base class shown above is also accessible under the alias
{Cheetah.ErrorCatchers.Echo}. {Cheetah.ErrorCatchers} also provides
a number of specialized subclasses that warn about exceptions in
different ways. {Cheetah.ErrorCatchers.BigEcho} will output</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Here</span><span class="s1">'s a good placeholder: Here I am!</span>
<span class="n">Here</span><span class="s1">'s bad placeholder: ===============&lt;$iDontExist could not be found&gt;===============</span>
</pre></div>
</div>
<p>ErrorCatcher has a significant performance impact and is turned off
by default. It can also be turned on with the {Template} class’
{‘errorCatcher’} keyword argument. The value of this argument
should either be a string specifying which of the classes in
{Cheetah.ErrorCatchers} to use, or a class that subclasses
{Cheetah.ErrorCatchers.ErrorCatcher}. The {#errorCatcher} directive
can also be used to change the errorCatcher part way through a
template.</p>
<p>{Cheetah.ErrorCatchers.ListErrors} will produce the same ouput as
{Echo} while maintaining a list of the errors that can be retrieved
later. To retrieve the list, use the {Template} class’
{‘errorCatcher’} method to retrieve the errorCatcher and then call
its {listErrors} method.</p>
<p>ErrorCatcher doesn’t catch exceptions raised inside directives.</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="parserInstructions.html" title="Instructions to the Parser/Compiler"
>next</a> |</li>
<li class="right" >
<a href="flowControl.html" title="Flow Control"
>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="index.html" >Cheetah User’s Guide</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>
|
