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
|
<!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>Patching Cheetah — 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="Directives: Flow Control" href="flowControl.html" />
<link rel="prev" title="Placeholders" href="placeholders.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="flowControl.html" title="Directives: Flow Control"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="placeholders.html" title="Placeholders"
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 Developer’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="#">Patching Cheetah</a><ul>
<li><a class="reference internal" href="#file-requirements">File Requirements</a></li>
<li><a class="reference internal" href="#testing-changes-and-building-regression-tests">Testing Changes and Building Regression Tests</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="placeholders.html"
title="previous chapter">Placeholders</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="flowControl.html"
title="next chapter">Directives: Flow Control</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/dev_guide/patching.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="patching-cheetah">
<h1>Patching Cheetah<a class="headerlink" href="#patching-cheetah" title="Permalink to this headline">¶</a></h1>
<p>(patching)</p>
<p>How to commit changes to CVS or submit patches, how to run the test
suite. Describe distutils and how the regression tests work.</p>
<div class="section" id="file-requirements">
<h2>File Requirements<a class="headerlink" href="#file-requirements" title="Permalink to this headline">¶</a></h2>
<p>(patching.fileRequirements)</p>
<p>The code{Template} class contains not only the Cheetah
infrastructure, but also some convenience methods useful in all
templates. More methods may be added if it’s generally agreed among
Cheetah developers that the method is sufficiently useful to all
types of templates, or at least to all types of HTML-output
templates. If a method is too long to fit into {Template} -
especially if it has helper methods - put it in a mixin class under
{Cheetah.Utils} and inherit it.</p>
<p>Routines for a specific problem domain should be put under
{Cheetah.Tools}, so that it doesn’t clutter the namespace unless
the user asks for it.</p>
<p>Remember: {Cheetah.Utils} is for objects required by any part of
Cheetah’s core. {Cheetah.Tools} is for completely optional objects.
It should always be possible to delete {Cheetah.Tools} without
breaking Cheetah’s core services.</p>
<p>If a core method needs to look up an attribute defined under
{Cheetah.Tools}, it should use {hasattr()} and gracefully provide a
default if the attribute does not exist (meaning the user has not
imported that subsystem).</p>
</div>
<div class="section" id="testing-changes-and-building-regression-tests">
<h2>Testing Changes and Building Regression Tests<a class="headerlink" href="#testing-changes-and-building-regression-tests" title="Permalink to this headline">¶</a></h2>
<p>(patching.testing)</p>
<p>Cheetah ships with a regression test suite. To run the built-in
tests, execute at the shell prompt:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">cheetah</span> <span class="n">test</span>
</pre></div>
</div>
<p>Before checking any changes in, run the tests and verify they all
pass. That way, users can check out the CVS version of Cheetah at
any time with a fairly high confidence that it will work. If you
fix a bug or add a feature, please take the time to add a test that
exploits the bug/feature. This will help in the future, to prevent
somebody else from breaking it again without realizing it. Users
can also run the test suite to verify all the features work on
their particular platform and computer.</p>
<p>The general procedure for modifying Cheetah is as follows:</p>
<ol class="arabic simple">
<li>Write a simple Python program that exploits the bug/feature
you’re working on. You can either write a regression test (see
below), or a separate program that writes the template output to
one file and put the expected output in another file; then you can
run {diff} on the two outputs. ({diff} is a utility included on all
Unix-like systems. It shows the differences between two files line
by line. A precompiled Windows version is at
<a class="reference external" href="http://gnuwin32.sourceforge.net/packages/diffutils.htm">http://gnuwin32.sourceforge.net/packages/diffutils.htm</a>, and MacOS
sources at
<a class="reference external" href="http://perso.wanadoo.fr/gilles.depeyrot/DevTools_en.html">http://perso.wanadoo.fr/gilles.depeyrot/DevTools_en.html</a>.)</li>
<li>Make the change in your Cheetah CVS sandbox or in your installed
version of Cheetah. If you make it in the sandbox, you’ll have to
run {python setup.py install} before testing it. If you make it in
the installed version, do { not} run the installer or it will
overwrite your changes!</li>
<li>Run {cheetah test} to verify you didn’t break anything. Then run
your little test program.</li>
<li>Repeat steps 2-3 until everything is correct.</li>
<li>Turn your little program into a regression test as described
below.</li>
<li>When {cheetah test} runs cleanly with your regression test
included, update the {docs/news.rst} file and check in your changes. If
you made the changes in your installed copy of Cheetah, you’ll have
to copy them back into the CVS sandbox first. If you added any
files that must be distributed, { be sure to} {cvs add} them before
committing. Otherwise Cheetah will run fine on your computer but
fail on anybody else’s, and the test suite can’t check for this.</li>
<li>Announce the change on the cheetahtemplate-discuss list and
provide a tutorial if necessary. The documentation maintainer will
update the Users’ Guide and Developers’ Guide based on this message
and on the changelog.</li>
</ol>
<p>If you add a directory to Cheetah, you have to mention it in
{setup.py} or it won’t be installed.</p>
<p>The tests are in the {Cheetah.Tests} package, aka the {src/Tests/}
directory of your CVS sandbox. Most of the tests are in
{SyntaxAndOutput.py}. You can either run all the tests or choose
which to run:</p>
<blockquote>
<div><p>Run all the tests. (Equivalent to {cheetah test}.)</p>
<p>Run only the tests in that module.</p>
<p>Run only the tests in the class {CGI} inside the module. The class
must be a direct or indirect subclass of
{unittest_local_copy.TestCase}.</p>
<p>Run the tests in classes {CGI} and {Indenter}.</p>
<p>Run only test {test1}, which is a method in the {CGI} class.</p>
</div></blockquote>
<p>To make a SyntaxAndOutput test, first see if your test logically
fits into one of the existing classes. If so, simply add a method;
e.g., {test16}. The method should not require any arguments except
{self}, and should call {.verify(source, expectedOutput)}, where
the two arguments are a template definition string and a control
string. The tester will complain if the template output does not
match the control string. You have a wide variety of placeholder
variables to choose from, anything that’s included in the
{defaultTestNameSpace} global dictionary. If that’s not enough, add
items to the dictionary, but please keep it from being cluttered
with wordy esoteric items for a single test).</p>
<p>If your test logically belongs in a separate class, create a
subclass of {OutputTest}. You do not need to do anything else; the
test suite will automatically find your class in the module. Having
a separate class allows you to define state variables needed by
your tests (see the {CGI} class) or override {.searchList()} (see
the {Indenter} class) to provide your own searchList.</p>
<p>To modify another test module or create your own test module,
you’ll have to study the existing modules, the
{unittest_local_copy} source, and the {unittest} documentation in
the Python Library Reference. Note that we are using a hacked
version of {unittest} to make a more convenient test structure for
Cheetah. The differences between {unittest_local_copy} and
Python’s standard {unittest} are documented at the top of the
module.</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="flowControl.html" title="Directives: Flow Control"
>next</a> |</li>
<li class="right" >
<a href="placeholders.html" title="Placeholders"
>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 Developer’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>
|
