__init__(self, source=None, namespaces=None, searchList=None, file=None, filter='RawOrEncodedUnicode', filtersLib=<module 'Cheetah.Filters' from '/home/big/lib/python2.4/s..., errorCatcher=None, compilerSettings=Unspecified, _globalSetVars=None, _preBuiltSearchList=None)
(Constructor)

a) compiles a new template OR b) instantiates an existing template.

Read this docstring carefully as there are two distinct usage patterns.
You should also read this class' main docstring.

a) to compile a new template:
     t = Template(source=aSourceString)
         # or 
     t = Template(file='some/path')
         # or 
     t = Template(file=someFileObject)
         # or
     namespaces = [{'foo':'bar'}]               
     t = Template(source=aSourceString, namespaces=namespaces)
         # or 
     t = Template(file='some/path', namespaces=namespaces)

     print t
     
b) to create an instance of an existing, precompiled template class:
     ## i) first you need a reference to a compiled template class:
     tclass = Template.compile(source=src) # or just Template.compile(src)
         # or 
     tclass = Template.compile(file='some/path')
         # or 
     tclass = Template.compile(file=someFileObject)
         # or 
     # if you used the command line compiler or have Cheetah's ImportHooks
     # installed your template class is also available via Python's
     # standard import mechanism:
     from ACompileTemplate import AcompiledTemplate as tclass
     
     ## ii) then you create an instance
     t = tclass(namespaces=namespaces)
         # or 
     t = tclass(namespaces=namespaces, filter='RawOrEncodedUnicode')
     print t

Arguments:
  for usage pattern a)           
    If you are compiling a new template, you must provide either a
    'source' or 'file' arg, but not both:          
      - source (string or None)
      - file (string path, file-like object, or None)

    Optional args (see below for more) :
      - compilerSettings
       Default: Template._CHEETAH_compilerSettings=None
       
       a dictionary of settings to override those defined in
       DEFAULT_COMPILER_SETTINGS.  See
       Cheetah.Template.DEFAULT_COMPILER_SETTINGS and the Users' Guide
       for details.

    You can pass the source arg in as a positional arg with this usage
    pattern.  Use keywords for all other args.           

  for usage pattern b)
    Do not use positional args with this usage pattern, unless your
    template subclasses something other than Cheetah.Template and you
    want to pass positional args to that baseclass.  E.g.:
      dictTemplate = Template.compile('hello $name from $caller', baseclass=dict)
      tmplvars = dict(name='world', caller='me')
      print dictTemplate(tmplvars)
    This usage requires all Cheetah args to be passed in as keyword args.

  optional args for both usage patterns:

    - namespaces (aka 'searchList')
      Default: None
      
      an optional list of namespaces (dictionaries, objects, modules,
      etc.) which Cheetah will search through to find the variables
      referenced in $placeholders.

      If you provide a single namespace instead of a list, Cheetah will
      automatically convert it into a list.
        
      NOTE: Cheetah does NOT force you to use the namespaces search list
      and related features.  It's on by default, but you can turn if off
      using the compiler settings useSearchList=False or
      useNameMapper=False.
        
     - filter
       Default: 'EncodeUnicode'
       
       Which filter should be used for output filtering. This should
       either be a string which is the name of a filter in the
       'filtersLib' or a subclass of Cheetah.Filters.Filter. . See the
       Users' Guide for more details.

     - filtersLib
       Default: Cheetah.Filters
       
       A module containing subclasses of Cheetah.Filters.Filter. See the
       Users' Guide for more details. 

     - errorCatcher
       Default: None

       This is a debugging tool. See the Users' Guide for more details.
       Do not use this or the #errorCatcher diretive with live
       production systems.

  Do NOT mess with the args _globalSetVars or _preBuiltSearchList!

Overrides:

Cheetah.Servlet.Servlet.__init__

errorCatcher(self)

generatedClassCode(self)

generatedModuleCode(self)

getCacheRegions(self)

Returns a dictionary of the 'cache regions' initialized in a template.

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

getFileContents(self, path)

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

hasVar(self, varName, autoCall=True)

i18n(self, 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(self, cacheRegionId=None, cacheItemId=None)

runAsMainProgram(self)

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(self)

shutdown(self)

Overrides:

Cheetah.Servlet.Servlet.shutdown

varExists(self, varName, autoCall=True)

webInput(self, 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 wantedDays.has_key(day):
            self.TurnOn(day)
            # ... Set a flag or insert a database record ...
        elif on and not wantedDays.has_key(day):
            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: $Revision: 1.178 $
Start Date: 2002/03/17
Last Revision Date: $Date: 2006/02/05 03:43:11 $

_compile(self, source=None, file=None, compilerSettings=Unspecified, moduleName=None, mainMethodName=None)

Compile the template. This method is automatically called by Template.__init__ it is provided with 'file' or 'source' args.

USERS SHOULD NEVER CALL THIS METHOD THEMSELVES. Use Template.compile instead.

_getTemplateAPIClassForIncludeDirectiveCompilation(self, source, file)

Returns the subclass of Template which should be used to compile #include directives.

This abstraction allows different compiler settings to be used in the included template than were used in the parent.

_handleCheetahInclude(self, srcArg, trans=None, includeFrom='file', raw=False)

_initCheetahInstance(self, searchList=None, namespaces=None, filter='RawOrEncodedUnicode', filtersLib=<module 'Cheetah.Filters' from '/home/big/lib/python2.4/s..., errorCatcher=None, _globalSetVars=None, _preBuiltSearchList=None)

Sets up the instance attributes that cheetah templates use at run-time.

This is automatically called by the __init__ method of compiled templates.

Note that the names of instance attributes used by Cheetah are prefixed with '_CHEETAH__' (2 underscores), where class attributes are prefixed with '_CHEETAH_' (1 underscore).

compile(klass, 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, 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=[...]) ] )

subclass(klass, *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 - bar

#def meth1: this is T1.meth1')

T2 = T1.subclass('#implements meth1

this is T2.meth1')

_addCheetahPlumbingCodeToClass(klass, concreteTemplateClass)

If concreteTemplateClass is not a subclass of Cheetah.Template, add the required cheetah methods and attributes to it.

This is called on each new template class after it has been compiled. If concreteTemplateClass is not a subclass of Cheetah.Template but already has method with the same name as one of the required cheetah methods, this will skip that method.

_normalizePreprocessorArg(klass, arg)

_preprocessSource(klass, source, file, preprocessors)

Iterates through the .compile() classmethod's preprocessors argument and pipes the source code through each each preprocessor.

It returns the tuple (source, file) which is then used by Template.compile to finish the compilation.