Skip to content
Newer
Older
100644 351 lines (299 sloc) 17.1 KB
32567d8 Initial revision
tavis_rudd authored
1 Cheetah TODO list
5610e47 added some instructions
tavis_rudd authored
2 -----------------
3 * If you are working on a task please put your initials at the end of the
4 description
9eb346f updated the list
tavis_rudd authored
5 * When a task is completed please remember to note it in the CHANGES file
c79ab09 *** empty log message ***
hierro authored
6 * Unresolved bugs are listed in the BUGS file. Resolved bugs are be listed
7 in the CHANGES file if the bug is considered significant enough and it
8 affected a released version of Cheetah.
5610e47 added some instructions
tavis_rudd authored
9
f5408e6 Docs.
hierro authored
10 Required for Cheetah 2.0
11 ========================
12 - Replace Optik with Python's optparse. Optik license has been removed from
13 Users' Guide.
14
262e3d4 Docs.
hierro authored
15 Desired for Cheetah 2.0
16 =======================
17 - Smart HTML filter that escapes all values except those individually marked as
18 preformatted, a la Kid/PTL/QPY. (MO)
19
f5408e6 Docs.
hierro authored
20
a7da875 update
tavis_rudd authored
21 TODO Items (many are just ideas. This is not an official roadmap!)
22 ================================================================================
e07ad1e *** empty log message ***
hierro authored
23
e9877cf *** empty log message ***
hierro authored
24 - "cheetah test" problem: subcommands fail mysteriously on Windows. Rewrite
25 to avoid using subcommands. Instead, set sys.argv and call the appropriate
26 main() for each test.
27
0becec0 updates
tavis_rudd authored
28 - Documentation: document #encoding. Explain problems "cheetah test" if they
29 haven't been fixed yet.
e9877cf *** empty log message ***
hierro authored
30
31 - There's a kludge in CheetahWrapper.py to abort with a helpful error message
32 if the user runs 'cheetah test' but doesn't have write permission in the
33 current directory. The tests should instead put their temporary files
34 under the system tmp directory.
35
9f5ff68 *** empty log message ***
hierro authored
36 - Reset the current filter to the default (or to the constructor's filter
37 if specified) at the beginning of each fill. Currently, filter changes
38 leak from one fill to the next.
e07ad1e *** empty log message ***
hierro authored
39
533f02a *** empty log message ***
hierro authored
40 - CheetahWrapper stuff: (MO)
41 * "cheetah compile --shbang '#!/usr/bin/python2.2'"
677034c *** empty log message ***
hierro authored
42 * "cheetah preview [options] [FILES]" print template-specific portion of main
43 method(s) to stdout, with line numbers based on the .py template module.
44 Make a Template method to do the same thing, a la .generatedModuleCode().
533f02a *** empty log message ***
hierro authored
45 * Refactor, make compile/fill/code routines callbacks using a bundle arg.
7822fa3 *** empty log message ***
hierro authored
46 * If an input file ends in a dot, intelligently add the input extension if
47 not found.
8e077f0 *** empty log message ***
hierro authored
48
f5408e6 Docs.
hierro authored
49 - ##null: throw this comment away, do not place it in the compiled template
50 module in any manner. Useful for obsolete text, unfinished text, or notes
51 to yourself. Do for single- and multi-line comments.
52
53 - Split out the code needed to run the generated
54 python into a base class of Template, and derive the compiled Python class
55 from that? This would allow precompiled templates to be loaded much more
56 quickly. @@TR: I've done some of the refactoring neccessary to support this as
57 part of the 0.9.16 release.
58
e9877cf *** empty log message ***
hierro authored
59 - A further 'nice to have' optimisation would be to be able to specify at
0becec0 updates
tavis_rudd authored
60 compile time that you are not using filters, Webware transactions etc, and not
61 generate code that uses them. This would remove the need to import
62 DummyTransaction and the Filters module. It would also simplify the code and
63 function calls in the compiled template module. @@TR: I've done some of the
64 refactoring neccessary to support this as part of the 0.9.16 release.
e9877cf *** empty log message ***
hierro authored
65
533f02a *** empty log message ***
hierro authored
66 - Debugging tools. See section below.
99009bd *** empty log message ***
hierro authored
67
7822fa3 *** empty log message ***
hierro authored
68 - Add --error option to compiled templates and "cheetah fill". It would
69 activate the Echo error catcher for debugging. (Maybe --list-errors to
70 suppress output and instead list the not found placeholders? Less
71 important.)
72
533055d *** empty log message ***
tavis_rudd authored
73 - Provide a utility to list the names of all placeholders in the template.
74 Requested by Tracy Ruggles on Feb 21, 2003.
75
47eece1 *** empty log message ***
tavis_rudd authored
76 - implement some better error handling for misformed #for, #if, #try directives,
77 etc. At the moment these errors are not caught until Python executes the
164322a general updates
tavis_rudd authored
78 code. @@TR: not a high priority as the python barfs suffice.
0becec0 updates
tavis_rudd authored
79
20f87b7 *** empty log message ***
tavis_rudd authored
80 - create a better error message for invalid syntax when a $var inside a
81 directive is enclosed in ${} or $(). E.g.:
82 #include raw source=${x}
f5408e6 Docs.
hierro authored
83
84 - Delete whitespace before a comment on the same line. The methods are
85 Parser.eatComment() and Parser.eatMultiLineComment(). It's already
86 working if the line contains 'STUFF#slurp ## comment'. Need to make
87 it work for 'STUFF ## comment' (but retain the EOL newline).
88 @@TR: is this really needed? It seems a bit 'magic' to me.
0beed83 *** empty log message ***
tavis_rudd authored
89
cbdb049 *** empty log message ***
hierro authored
90 - 'errorCatcher None' to stop catching errors in the middle of a template.
f4b3b51 *** empty log message ***
hierro authored
91
655c7cd *** empty log message ***
hierro authored
92 - Utils.WebInputMixin: factor out Cheetah-specific code so it can be used in
93 non-Cheetah applications. Don't modify the searchList: have a Template
94 wrapper method do that. Consider turning it into a function that does not
95 require 'self'. Consider making Webware-specific code into plugins so that,
96 e.g., other cookie-handling methods can be grafted in. Maybe use callback
97 classes like the planned rewrite for CheetahWrapper. Low priority. (MO)
98
8c8ab98 *** empty log message ***
hierro authored
99 - Look through Zope Page Templates (TAL) for ideas to borrow.
100 http://www.zope.org/Documentation/Books/ZopeBook/current/AppendixC.stx
101 http://www.owlfish.com/software/simpleTAL/index.html
d1e5768 *** empty log message ***
hierro authored
102
7822fa3 *** empty log message ***
hierro authored
103 Debugging Tools (Dump Tools)
104 ============================
8f06caf *** empty log message ***
hierro authored
105 It would be nice to provide debugging tools for users who can't figure
106 out why a certain placeholder value isn't found or is being overridden.
107 My idea is to define $dumpSearchList() and $dumpSearchListFlat() in
108 Template, which would print a stanza in the output showing all searchList
109 variables and their values. $dumpSearchList would group by searchList
110 element; $dumpSearchListFlat would combine all into a single
111 alphabetical listing.
bb5709a *** empty log message ***
hierro authored
112 I made an experimental version but it printed only instance variables,
8f06caf *** empty log message ***
hierro authored
113 not methods and not inherited attributes. Also, it wouldn't print right
114 using the usual pattern of write-to-custom-StringIO-object-and-return-
115 the-.getvalue() and I couldn't figure out why.
bb5709a *** empty log message ***
hierro authored
116 The stanza should be set apart by a row of stars with the words
8f06caf *** empty log message ***
hierro authored
117 "BEGIN/END SEARCH LIST DUMP". Then for $dumpSearchList, precede each
118 group with "*** searchList[i], type <element type>, 142 variables ***".
bb5709a *** empty log message ***
hierro authored
119 Because some elements like 'self' may have hundreds of inherited
8f06caf *** empty log message ***
hierro authored
120 methods that would create a forest-through-trees situation for the user,
121 we may need an option to supress the variable listing for elements with
122 > 20 variables (just print the summary line instead). ?
bb5709a *** empty log message ***
hierro authored
123 The final version should be in Template so it has implicit
8f06caf *** empty log message ***
hierro authored
124 access to the searchList and perhaps later to other variables (locals,
125 globals, "#set global"s, builtins) too. This is such a central
126 debugging tool that you should not have to monopolize an #extends
127 (the template's only #extends) to use it. You could import it, however,
128 if you pass in the searchList explicitly as an argument. In that case,
129 perhaps we can base it on a generic module for dumping variables/values.
bb5709a *** empty log message ***
hierro authored
130 Note that we cannot simply depend on str() and pprint, because
8f06caf *** empty log message ***
hierro authored
131 we need to show instances as dictionaries. Likewise, dir() and vars()
132 may get us part of the distance, but only if they show methods and
133 inherited attributes too.
bb5709a *** empty log message ***
hierro authored
134 These functions should print only top-level variables, not
8f06caf *** empty log message ***
hierro authored
135 the subelements of collections. I.e, if the first searchList element
136 is a dictionary, show its keys/values, but do not expand any
137 subvalues if they are dictionaries too, unless the display tool happens
138 to default to that.
139
55de2db Comment.
hierro authored
140 #entry $func($arg1, $arg2="default", $**kw)
625de1d *** empty log message ***
hierro authored
141 ===============================================================================
55de2db Comment.
hierro authored
142 Make a wrapper function in the .py template module that builds a searchList
143 from its positional arguments, then instantiates and fills a template and
144 returns the result. The preceding example would create a function thus:
bb5709a *** empty log message ***
hierro authored
145 def func(arg1, arg2="default", searchList=None, **kw):
146 """Function docstring."""
147 sl = {'arg1': arg1, 'arg2': arg2}
148 if searchList is None:
149 searchList = [sl]
150 elif type(searchList) == types.ListType:
151 searchList.insert(0, sl)
152 else:
153 raise TypeError("arg 'searchList'")
154 t = TheTemplate(searchList=searchList, **kw)
155 return str(t)
55de2db Comment.
hierro authored
156 ##doc-entry: and #*doc-entry: comments are appended to the function docstring.
bb5709a *** empty log message ***
hierro authored
157 Finally, make this function accessible directly from the shell.
625de1d *** empty log message ***
hierro authored
158 If there are any non-option arguments on the command line, call the function
159 instead of filling the template the normal way.
bb5709a *** empty log message ***
hierro authored
160 This would perhaps make more sense as arguments to .respond(). But
55de2db Comment.
hierro authored
161 .respond() has that pesky 'trans' argument that mustn't be interfered with,
162 and other programs may assume .respond() takes only one argument. Also,
163 when called via str(), str() cannot take arguments.
bb5709a *** empty log message ***
hierro authored
164
165 #indent
166 ========================================================================
4894159 *** empty log message ***
hierro authored
167 The current indenter (which exists but is undocumented) is a kludge that has an
168 indentation object, with implicit placeholder calls added at each line to
169 generate the indentation, and #silent calls to adjust the object. It should be
170 reimplemented to generate code to call the indentation object directly. Also,
171 the user interface should be cleaned up, the implementation and Users' Guide
bb5709a *** empty log message ***
hierro authored
172 synchronized, and test cases built.
173
174 The desired implementation revolves around self._indenter, which knows the
175 current indentation level (a non-negative integer), chars (the string output
176 per level, default four spaces), and stack (the previous indentation levels).
177 The .indent() method returns the indentation string currently appropriate.
4894159 *** empty log message ***
hierro authored
178 The desired interface for phase 1 (subject to change):
bb5709a *** empty log message ***
hierro authored
179 #indent strip ; strip leading whitespace from input lines
180 #indent add ; add indentation to output lines as appropriate
181 #indent on ; do both
182 #indent off ; do neither
183 #indent reset ; set level to 0 and clear stack
184 #indent ++ ; increment level
185 #indent -- ; decrement level
186 #indent pop [EXPR] ; revert to Nth previous level (default 1)
187 ; if pop past end of stack, set level to 0 and
188 ; clear stack. All +/-/= operations push the old level
189 ; onto the stack.
190 #indent debug ; dump level, chars and stack to template output
191
192 Possible extensions:
4894159 *** empty log message ***
hierro authored
193 #indent =EXPR ; set level to N (likely to be added to phase 1)
bb5709a *** empty log message ***
hierro authored
194 #indent +EXPR ; add N to level (not very necessary)
195 #indent -EXPR ; subtract N from level (not very necessary)
4894159 *** empty log message ***
hierro authored
196 #indent balance BOOL ; require all indent changes in a #def/#block to be
197 ; popped before exiting the method. (difficult to
198 ; implement)
199 #indent implicitPop BOOL ; automatically pop indent changes within a
200 ; #def/block when that method exits. (difficult to
201 ; implement)
202 #indent ?? ; a 3-way switch that combines unbalanced, balanced and
203 ; implicit pop. (difficult to implement)
204 #indent ?? ; smart stripping: strip input indentation according to
205 ; nested directive level; e.g.,
206 ; 01: #if foo=1
207 ; 02: public int foo()
208 ; 03: {
209 ; 04: return FOO;
210 ; 05: }
211 ; 06: #end if
212 ; With smart stripping, line 4 would be indented and the
213 ; others not. With "on" or "strip" stripping, all lines
214 ; 2-5 would be unindented. With "off" stripping,
215 ; lines 2-5 would not be stripped.
bb5709a *** empty log message ***
hierro authored
216
217 There should be one indentation object per Template instance, shared by
218 methods and include files.
219
625de1d *** empty log message ***
hierro authored
220
63640d7 *** empty log message ***
hierro authored
221 Upload File
222 ========================================================================
164322a general updates
tavis_rudd authored
223 @@TR: This is way outside Cheetah's scope!
224
63640d7 *** empty log message ***
hierro authored
225 A mixin method in Cheetah.Utils (for Template) that handles file uploads --
226 these are too complicated for .webInput(). The method should do a "safe"
227 file upload; e.g., http://us3.php.net/manual/en/features.file-upload.php ,
228 within the limitations of Python's cgi module. The user has the choice of
229 three destinations for the file contents: (A) copied to a local
230 path you specify, (B) placed in a namespace variable like .cgiImport()
231 does, or (C) returned. (B) parallels .webInput, but (A) will certainly be
232 desirable situations where we just want to save the file, not read it into
233 memory. Reject files larger than a user-specified size or not in a list of
234 user-approved MIME types. Define appropriate exceptions for typical
235 file-upload errors. Method name .webUploadFileAsString?
bb5709a *** empty log message ***
hierro authored
236 One situation to support is when form has a text(area) field
63640d7 *** empty log message ***
hierro authored
237 related to a file-upload control on the same form, and the user has the choice
238 of typing into the field or uploading a text file. We need a method that
239 updates the text field's value if there is an uploaded file, but not if there
240 isn't. This may be handled by the regular method(s) or may require a separate
241 method.
625de1d *** empty log message ***
hierro authored
242
e9877cf *** empty log message ***
hierro authored
243 RPM Building
244 ============
245 From: John Landahl <john@landahl.org>
246 To: cheetahtemplate-discuss@lists.sourceforge.net
247 Subject: [Cheetahtemplate-discuss] Building Cheetah RPMs
248 Date: Wed, 05 Nov 2003 01:27:24 -0800
249
250 If anyone is interested in building Cheetah RPMs, simply add the following
251 lines to a file called MANIFEST.in in the Cheetah directory and you'll be
252 able to use the "bdist_rpm" option to setup.py (i.e. "python setup.py
253 bdist_rpm"):
254
255 include SetupTools.py
256 include SetupConfig.py
257 include bin/*
258
259 Also, I've found that using /usr/lib/site-python for add-on Python
260 packages is much more convenient than the default of
261 /usr/lib/pythonX/site-packages, especially when jumping back and forth
262 between 2.2 and 2.3. If you'd like Cheetah in /usr/lib/site-python,
263 createa a setup.cfg with the following contents:
264
265 [install]
266 install-lib = /usr/lib/site-python
267
268 Of course if you do have version specific libraries they should stay in
269 /usr/lib/pythonX/site-packages, but Cheetah seems happy in both 2.2 and
270 2.3 and so is a good candidate for /usr/lib/site-python.
271
272
5e5892b *** empty log message ***
hierro authored
273 User-defined directives
274 =======================================================================
275 IF we decide to support user-defined directives someday, consider Spyce's
276 interface. Spyce uses a base class which provides generic services to
277 custom "active tags".
278 http://spyce.sourceforge.net/doc-tag.html
279 http://spyce.sourceforge.net/doc-tag_new.html
280
a08b622 *** empty log message ***
hierro authored
281
32567d8 Initial revision
tavis_rudd authored
282 Test Suite
283 ================================================================================
164322a general updates
tavis_rudd authored
284 - test cases for the SkeletonPage framework @@TR: I have no interest in this as
285 I plan on removing SkeletonPage.
0cbb2a2 updated
tavis_rudd authored
286 - add cases that test the cheetah-compile script
0916737 *** empty log message ***
hierro authored
287 - add cases that test the integration with WebKit. Since these must be called
288 from a running WebKit server, make a servlet that runs the tests and outputs
289 diagnostics to the browser.
32567d8 Initial revision
tavis_rudd authored
290
291 Website
292 ================================================================================
8d09b72 *** empty log message ***
tavis_rudd authored
293 - automate the documentation update
32567d8 Initial revision
tavis_rudd authored
294 - See if we can get WebKit working on Sourceforge...
295
296 Examples
297 ================================================================================
298 - create some non-html code generation examples
0cbb2a2 updated
tavis_rudd authored
299 - SQL
300 - LaTeX
301 - form email
6d1d0e1 *** empty log message ***
hierro authored
302 - Template definitions in a database. .py template modules in a
303 database? Caching template classes and/or instances extracted from
304 a database.
305 - Pickled templates?
5329f63 *** empty log message ***
hierro authored
306
f5408e6 Docs.
hierro authored
307
308 CheetahX: pie-in-the-sky (notes from Mike Orr)
309 ========================================================================
310 These ideas are being considered for Cheetah 2.0.
311
312 - There are five distinct objects in Cheetah which should have a clearer
313 separation.
314
315 1. TEMPLATE DEFINITION: a string.
316 2. TEMPLATE METHOD: the method that implements the desired template
317 (which may be the Main Method or a #def/#block method). This is
318 inside the generated class, which is inside the generated module.
319 3. DATA: the searchList, local variables, current filter, etc. Everything
320 that changes at runtime.
321 4. INFRASTRUCTURE: the internal code used by Cheetah to fill and maintain the
322 template.
323 5. SERVICES: convenience methods from the infrastructure exposed to user.
324
325 Cheetah combines 2-5 into a single Template subclass. CheetahX proposes to
326 keep these distinct, with defined containment and interfaces between them.
327
328 - The TEMPLATE METHOD might instantiate an INFRASTRUCTURE object for each
329 fill. The constructor arguments would be everything necessary to access
330 the DATA. Perhaps the TEMPLATE METHOD can pass its own code block, making
331 its own locals/globals accessible directly. This would be a bit
332 unorthodox, but less so than the current practice of switching the
333 template instance's class on the fly.
334
335 - For SERVICES, add a custom object to the searchList that knows how to
336 access the protected INFRASTRUCTURE data.
337
338 - Push more work into INFRASTRUCTURE, to insulate the TEMPLATE METHOD from
339 implementation changes. For instance, replace every placeholder lookup
340 with a simple INFRASTRUCTURE method call, and let the infrastructure
341 do all the processing. (It can use the code block mentioned above to
342 access the searchList and current filter.) For local variable
343 lookups, you can call another method and pass the value directly.
344 For caching, I guess you pass in the cache time (or a special constant)
345 as a separate argument, and let the INFRASTRUCTURE maintain the cache.
346
347 - The Template class needs to be split up into stuff nececssary to fill
348 a template (the INFRASTRUCTURE), and stuff necessary to comple a template
349 (which is not necessary for using precompiled templates, and slows down
350 Cheetah's import time).
Something went wrong with that request. Please try again.