diff options
Diffstat (limited to 'www/dev_guide/pyModules.rst')
| -rw-r--r-- | www/dev_guide/pyModules.rst | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/www/dev_guide/pyModules.rst b/www/dev_guide/pyModules.rst new file mode 100644 index 0000000..ceaf53f --- /dev/null +++ b/www/dev_guide/pyModules.rst @@ -0,0 +1,252 @@ +.py Template Modules +==================== + +(pyModules) + +This chapter examines the structure of a .py template module. The +following few chapters will then show how each placeholder and +directive affects the generated Python code. + +An example +---------- + +(pyModules.example) + +Our first template follows a long noble tradition in computer +tutorials. It produces a familiar, friendly greeting. Here's the +template: + +:: + + Hello, world! + +... the output: + +:: + + Hello, world! + +... and the .py template module cheetah-compile produced, with line +numbers added: + +:: + + 1 #!/usr/bin/env python + + 2 """ + 3 Autogenerated by CHEETAH: The Python-Powered Template Engine + 4 CHEETAH VERSION: 0.9.12 + 5 Generation time: Sat Apr 20 14:27:47 2002 + 6 Source file: x.tmpl + 7 Source file last modified: Wed Apr 17 22:10:59 2002 + 8 """ + + 9 __CHEETAH_genTime__ = 'Sat Apr 20 14:27:47 2002' + 10 __CHEETAH_src__ = 'x.tmpl' + 11 __CHEETAH_version__ = '0.9.12' + + 12 ################################################## + 13 ## DEPENDENCIES + + 14 import sys + 15 import os + 16 import os.path + 17 from os.path import getmtime, exists + 18 import time + 19 import types + 20 from Cheetah.Template import Template + 21 from Cheetah.DummyTransaction import DummyTransaction + 22 from Cheetah.NameMapper import NotFound, valueForName, + valueFromSearchList + 23 import Cheetah.Filters as Filters + 24 import Cheetah.ErrorCatchers as ErrorCatchers + + 25 ################################################## + 26 ## MODULE CONSTANTS + + 27 try: + 28 True, False + 29 except NameError: + 30 True, False = (1==1), (1==0) + + 31 ################################################## + 32 ## CLASSES + + 33 class x(Template): + 34 """ + 35 + 36 Autogenerated by CHEETAH: The Python-Powered Template Engine + 37 """ + +:: + + 38 ################################################## + 39 ## GENERATED METHODS + + + 40 def __init__(self, *args, **KWs): + 41 """ + 42 + 43 """ + + 44 Template.__init__(self, *args, **KWs) + 45 self._filePath = 'x.tmpl' + 46 self._fileMtime = 1019106659 + + 47 def respond(self, + 48 trans=None, + 49 dummyTrans=False, + 50 VFS=valueFromSearchList, + 51 VFN=valueForName, + 52 getmtime=getmtime, + 53 currentTime=time.time): + + + 54 """ + 55 This is the main method generated by Cheetah + 56 """ + + 57 if not trans: + 58 trans = DummyTransaction() + 59 dummyTrans = True + 60 write = trans.response().write + 61 SL = self._searchList + 62 filter = self._currentFilter + 63 globalSetVars = self._globalSetVars + 64 + 65 ######################################## + 66 ## START - generated method body + 67 + 68 if exists(self._filePath) and getmtime(self._filePath) > \ + self._fileMtime: + 69 self.compile(file=self._filePath) + 70 write(getattr(self, self._mainCheetahMethod_for_x) + (trans=trans)) + 71 if dummyTrans: + 72 return trans.response().getvalue() + 73 else: + 74 return "" + 75 write('Hello, world!\n') + 76 + 77 ######################################## + 78 ## END - generated method body + 79 + 80 if dummyTrans: + 81 return trans.response().getvalue() + 82 else: + 83 return "" + +:: + + 84 + 85 ################################################## + 86 ## GENERATED ATTRIBUTES + + + 87 __str__ = respond + + 88 _mainCheetahMethod_for_x= 'respond' + + + 89 # CHEETAH was developed by Tavis Rudd, Chuck Esterbrook, Ian Bicking + # and Mike Orr; + 90 # with code, advice and input from many other volunteers. + 91 # For more information visit http://www.CheetahTemplate.org + + 92 ################################################## + 93 ## if run from command line: + 94 if __name__ == '__main__': + 95 x().runAsMainProgram() + + +(I added the line numbers for this Guide, and split a few lines to +fit the page width. The continuation lines don't have line numbers, +and I added indentation, backslashes and '#' as necessary to make +the result a valid Python program.) + +The examples were generated from CVS versions of Cheetah between +0.9.12 and 0.9.14. + +A walk through the example +-------------------------- + +(pyModules.walk) + +Lines 20-24 are the Cheetah-specific imports. Line 33 introduces +our generated class, {x}, a subclass of {Template}. It's called x +because the source file was x.tmpl. + +Lines 40-46 are the {.\_\_init\_\_} method called when the template +is instantiated or used as a Webware servlet, or when the module is +run as a standalone program. We can see it calling its superclass +constructor and setting {.\_filePath} and {.\_fileMtime} to the +filename and modification time (in Unix ticks) of the source .tmpl +file. + +Lines 47-84 are the main method {.respond}, the one that fills the +template. Normally you call it without arguments, but Webware calls +it with a Webware {Transaction} object representing the current +request. Lines 57-59 set up the {trans} variable. If a real or +dummy transaction is passed in, the method uses it. Otherwise (if +the {trans} argument is {None}), the method creates a +{DummyTransaction} instance. {dummyTrans} is a flag that just tells +whether a dummy transaction is in effect; it'll be used at the end +of the method. + +The other four {.respond} arguments aren't anything you'd ever want +to pass in; they exist solely to speed up access to these +frequently-used global functions. This is a standard Python trick +described in question 4.7 of the Python FAQ +(http://www.python.org/cgi-bin/faqw.py). {VFS} and {VFN} are the +functions that give your template the benefits of NameMapper +lookup, such as the ability to use the searchList. + +Line 60 initializes the {write} variable. This important variable +is discussed below. + +Lines 60-63 initialize a few more local variables. {SL} is the +searchList. {filter} is the current output filter. {globalSetVars} +are the variables that have been defined with {#set global}. + +The comments at lines 65 and 78 delimit the start and end of the +code that varies with each template. The code outside this region +is identical in all template modules. That's not quite true - +{#import} for instance generates additional {import} statements at +the top of the module - but it's true enough for the most part. + +Lines 68-74 exist only if the template source was a named file +rather than a string or file object. The stanza recompiles the +template if the source file has changed. Lines 70-74 seem to be +redundant with 75-83: both fill the template and send the output. +The reason the first set of lines exists is because the second set +may become invalid when the template is recompiled. (This is for { +re} compilation only. The initial compilation happened in the +{.\_\_init\_\_} method if the template wasn't precompiled.) + +Line 75 is the most interesting line in this module. It's a direct +translation of what we put in the template definition, +"Hello, world!" Here the content is a single string literal. +{write} looks like an ordinary function call, but remember that +line 60 made it an alias to {trans.response().write}, a method in +the transaction. The next few chapters describe how the different +placeholders and directives influence this portion of the generated +class. + +Lines 80-83 finish the template filling. If {trans} is a real +Webware transaction, {write} has already sent the output to Webware +for handling, so we return {""}. If {trans} is a dummy transaction, +{write} has been accumulating the output in a Python {StringIO} +object rather than sending it anywhere, so we have to return it. + +Line 83 is the end of the {.respond} method. + +Line 87 makes code{.\_\_str\_\_} an alias for the main method, so +that you can {print} it or apply {str} to it and it will fill the +template. Line 88 gives the name of the main method, because +sometimes it's not {.respond}. + +Lines 94-95 allow the module to be run directly as a script. +Essentially, they process the command-line arguments and them make +the template fill itself. + + |