Cheetah.Template module

Provides the core API for Cheetah

See the docstring in the Template class and the Users’ Guide for more information.

class Cheetah.Template.CompileCacheItem

Bases: object

exception Cheetah.Template.Error

Bases: exceptions.Exception

exception Cheetah.Template.PreprocessError

Bases: Cheetah.Template.Error

Cheetah.Template.T

alias of Cheetah.Template.Template

class Cheetah.Template.Template(source=None, namespaces=None, searchList=None, file=None, filter='RawOrEncodedUnicode', filtersLib=<module 'Cheetah.Filters' from '/home/phd/current/projects/cheetah3/cheetah3/Cheetah/Filters.pyc'>, errorCatcher=None, compilerSettings=Unspecified, _globalSetVars=None, _preBuiltSearchList=None)

Bases: Cheetah.Servlet.Servlet

This class provides a) methods used by templates at runtime and b) methods for compiling Cheetah source code into template classes.

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.

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.

There are several possible usage patterns:

1) tclass = Template.compile(src)
   t1 = tclass() # or tclass(namespaces=[namespace,...])
   t2 = tclass() # or tclass(namespaces=[namespace2,...])
   outputStr = str(t1) # or outputStr = t1.aMethodYouDefined()

   Template.compile provides a rich and very flexible API via its
   optional arguments so there are many possible variations of this
   pattern.  One example is:
     tclass = Template.compile('hello $name from $caller',
                               baseclass=dict)
     print(tclass(name='world', caller='me'))
   See the Template.compile() docstring for more details.

2) tmplInstance = Template(src)
      # or Template(src, namespaces=[namespace,...])
   outputStr = str(tmplInstance)
   # or outputStr = tmplInstance.aMethodYouDefined(...args...)

Notes on the usage patterns:

usage pattern 1)
   This is the most flexible, but it is slightly more verbose unless you
   write a wrapper function to hide the plumbing.  Under the hood, all
   other usage patterns are based on this approach.  Templates compiled
   this way can #extend (subclass) any Python baseclass: old-style or
   new-style (based on object or a builtin type).

usage pattern 2)
   This was Cheetah's original usage pattern.  It returns an instance,
   but you can still access the generated class via
   tmplInstance.__class__.  If you want to use several different
   namespace 'searchLists' with a single template source definition,
   you're better off with Template.compile (1).

   Limitations (use pattern 1 instead)::

    - Templates compiled this way can only #extend subclasses of the
      new-style 'object' baseclass.  Cheetah.Template is a subclass of
      'object'.  You also can not #extend dict, list, or other builtin
      types.
    - If your template baseclass' __init__ constructor expects args
      there is currently no way to pass them in.

If you need to subclass a dynamically compiled Cheetah class, do something like this:

from Cheetah.Template import Template
T1 = Template.compile('$meth1 #def meth1: this is meth1 in T1')
T2 = Template.compile(
    '#implements meth1\nthis is meth1 redefined in T2', baseclass=T1)
print(T1, T1())
print(T2, T2())

Note about class and instance attribute names:

Attributes used by Cheetah have a special prefix to avoid confusion with
the attributes of the templates themselves or those of template
baseclasses.

Class attributes which are used in class methods look like this::

    klass._CHEETAH_useCompilationCache (_CHEETAH_xxx)

Instance attributes look like this::

    klass._CHEETAH__globalSetVars (_CHEETAH__xxx with 2 underscores)

exception NonNumericInputError

Bases: exceptions.ValueError

Reserved_SearchList = set(['NonNumericInputError', '_CHEETAH_cacheCompilationResults', '_CHEETAH_cacheDirForModuleFiles', '_CHEETAH_cacheModuleFilesForTracebacks', '_CHEETAH_cacheRegionClass', '_CHEETAH_cacheStore', '_CHEETAH_cacheStoreClass', '_CHEETAH_cacheStoreIdPrefix', '_CHEETAH_compileCache', '_CHEETAH_compileLock', '_CHEETAH_compilerClass', '_CHEETAH_compilerInstance', '_CHEETAH_compilerSettings', '_CHEETAH_defaultBaseclassForTemplates', '_CHEETAH_defaultClassNameForTemplates', '_CHEETAH_defaultMainMethodName', '_CHEETAH_defaultMainMethodNameForTemplates', '_CHEETAH_defaultModuleGlobalsForTemplates', '_CHEETAH_defaultModuleNameForTemplates', '_CHEETAH_defaultPreprocessorClass', '_CHEETAH_generatedModuleCode', '_CHEETAH_keepRefToGeneratedCode', '_CHEETAH_preprocessors', '_CHEETAH_requiredCheetahClassAttributes', '_CHEETAH_requiredCheetahClassMethods', '_CHEETAH_requiredCheetahMethods', '_CHEETAH_useCompilationCache', '__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__hash__', '__init__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_addCheetahPlumbingCodeToClass', '_compile', '_createCacheRegion', '_getCacheStore', '_getCacheStoreIdPrefix', '_getCompilerClass', '_getCompilerSettings', '_getTemplateAPIClassForIncludeDirectiveCompilation', '_handleCheetahInclude', '_initCheetahInstance', '_normalizePreprocessorArg', '_normalizePreprocessorSettings', '_preprocessSource', '_updateSettingsWithPreprocessTokens', 'application', 'compile', 'errorCatcher', 'generatedClassCode', 'generatedModuleCode', 'getCacheRegion', 'getCacheRegions', 'getFileContents', 'getVar', 'hasVar', 'i18n', 'refreshCache', 'request', 'respond', 'runAsMainProgram', 'searchList', 'serverSidePath', 'session', 'shutdown', 'sleep', 'subclass', 'transaction', 'varExists', 'webInput'])

classmethod compile(source=None, file=None, returnAClass=True, compilerSettings=Unspecified, compilerClass=Unspecified, moduleName=None, className=Unspecified, mainMethodName=Unspecified, baseclass=Unspecified, moduleGlobals=Unspecified, cacheCompilationResults=Unspecified, useCache=Unspecified, preprocessors=Unspecified, cacheModuleFilesForTracebacks=Unspecified, cacheDirForModuleFiles=Unspecified, commandlineopts=None, keepRefToGeneratedCode=Unspecified)

The core API for compiling Cheetah source code into template classes.

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.

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.

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.

Hooks are provided template source preprocessing. See the notes on the ‘preprocessors’ arg.

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.

Arguments:

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=[...])])

errorCatcher()

Return a reference to the current errorCatcher

generatedClassCode()

Return the class code the compiler generated, or None if no compilation took place.

generatedModuleCode()

Return the module code the compiler generated, or None if no compilation took place.

getCacheRegion(regionID, cacheInfo=None, create=True)

getCacheRegions()

Returns a dictionary of the ‘cache regions’ initialized in a template.

Each #cache directive block or $*cachedPlaceholder is a separate ‘cache region’.

getFileContents(path)

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’.

getVar(varName, default=Unspecified, autoCall=True)

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.

hasVar(varName, autoCall=True)

Test if a variable name exists in the searchList.

i18n(message, plural=None, n=None, id=None, domain=None, source=None, target=None, comment=None)

This is just a stub at this time.

plural = the plural form of the message
n = a sized argument to distinguish
    between single and plural forms
id = msgid in the translation catalog
domain = translation domain
source = source lang
target = a specific target lang
comment = a comment to the translation team

See the following for some ideas http://www.zope.org/DevHome/Wikis/DevSite/Projects/ComponentArchitecture/ZPTInternationalizationSupport

Other notes:

- There is no need to replicate the i18n:name attribute
  from plone / PTL, as cheetah placeholders serve the same purpose.

refreshCache(cacheRegionId=None, cacheItemId=None)

Refresh a cache region or a specific cache item within a region.

runAsMainProgram()

Allows the Template to function as a standalone command-line program for static page generation.

Type ‘python yourtemplate.py –help to see what it’s capabable of.

searchList()

Return a reference to the searchlist

shutdown()

Break reference cycles before discarding a servlet.

classmethod subclass(*args, **kws)

Takes the same args as the .compile() classmethod and returns a template that is a subclass of the template this method is called from.

T1 = Template.compile(

‘foo - $meth1 - barn#def meth1: this is T1.meth1’)

T2 = T1.subclass(‘#implements meth1n this is T2.meth1’)

varExists(varName, autoCall=True)

Test if a variable name exists in the searchList.

webInput(names, namesMulti=(), default='', src='f', defaultInt=0, defaultFloat=0.0, badInt=0, badFloat=0.0, debug=False)

Method for importing web transaction variables in bulk.

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.

The public method provided is:

def webInput(self, names, namesMulti=(), default='', src='f',
             defaultInt=0, defaultFloat=0.00,
             badInt=0, badFloat=0.00, debug=False):

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:

* single vs multiple values
* conversion to integer or float for specified names
* default values/exceptions for missing or bad values
* printing a snapshot of all values retrieved for debugging

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.

The simplest usage is:

#silent $webInput(['choice'])
$choice

dic = self.webInput(['choice'])
write(dic['choice'])

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:

#silent $webInput(['name'], $debug=1)

because this pretty-prints all the values inside HTML <PRE> tags.

*** 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. ***

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:

* If one value is found, take it.
* If several values are found, choose one arbitrarily
  and ignore the rest.
* If no values are found, use or raise
  the appropriate 'default*' value.

Multi values work like this:

* If one value is found, put it in a list.
* If several values are found, leave them in a list.
* If no values are found, use the empty list ([]).  The 'default*'
  arguments are *not* consulted in this case.

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’:

#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 + ' ')

Both these examples print: ‘The days you chose are: Monday Tuesday Thursday’.

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 should 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:

* None
* another constant value
* $NonNumericInputError/self.NonNumericInputError
* $ValueError/ValueError

(NonNumericInputError is defined in this class and is useful for distinguishing between bad input vs a TypeError/ValueError thrown for some other rason.)

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.

dic = self.webInput([], ['dayCheckboxes'])
wantedDays = dic['dayCheckboxes'] # The days the user checked.
for day, on in self.getAllValues():
    if   not on and day in wantedDays:
        self.TurnOn(day)
        # ... Set a flag or insert a database record ...
    elif on and day not in wantedDays:
        self.TurnOff(day)
        # ... Unset a flag or delete a database record ...

‘source’ allows you to look up the variables from a number of different sources:

'f'   fields (CGI GET/POST parameters)
'c'   cookies
's'   session variables
'v'   'values', meaning fields or cookies

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:

#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.')

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’.

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.

This only in a subclass that also inherits from Webware’s Servlet or HTTPServlet. Otherwise you’ll get an AttributeError on ‘self.request’.

EXCEPTIONS: ValueError if ‘source’ is not one of the stated characters. TypeError if a conversion suffix is not ‘:int’ or ‘:float’.

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.

Meta-Data:

Author: Mike Orr <iron@mso.oz.net>
License: This software is released for unlimited distribution
under the terms of the MIT license.  See the LICENSE file.
Version: 1.186
Start Date: 2002/03/17
Last Revision Date: 2008/03/10 04:48:11

class Cheetah.Template.TemplatePreprocessor(settings)

Bases: object

This is used with the preprocessors argument to Template.compile().

See the docstring for Template.compile

** Preprocessors are an advanced topic **

preprocess(source, file)

Create an intermediate template and return the source code it outputs

Cheetah.Template.checkFileMtime(value)

Cheetah.Template.createMethod(func, cls)

Cheetah.Template.genParserErrorFromPythonException(source, file, generatedPyCode, exception)

Cheetah.Template.hashDict(d)

Cheetah.Template.hashList(v_list)

Cheetah.Template.updateLinecache(filename, src)