root/Cheetah/Template.py

#!/usr/bin/env python
# $Id: Template.py,v 1.181 2006/06/22 20:25:16 hierro Exp $
"""Provides the core API for Cheetah.

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

Meta-Data
================================================================================
Author: Tavis Rudd <tavis@damnsimple.com>
License: This software is released for unlimited distribution under the
         terms of the MIT license.  See the LICENSE file.
Version: $Revision: 1.181 $
Start Date: 2001/03/30
Last Revision Date: $Date: 2006/06/22 20:25:16 $
""" 
__author__ = "Tavis Rudd <tavis@damnsimple.com>"
__revision__ = "$Revision: 1.181 $"[11:-2]

################################################################################
## DEPENDENCIES
import sys                        # used in the error handling code
import re                         # used to define the internal delims regex
import new                        # used to bind methods and create dummy modules
import string
import os.path
import time                       # used in the cache refresh code
from random import randrange
import imp
import inspect
import StringIO
import traceback
import pprint
import cgi                # Used by .webInput() if the template is a CGI script.
import types 
from types import StringType, ClassType
try:
    from types import StringTypes
except ImportError:
    StringTypes = (types.StringType,types.UnicodeType)
try:
    from types import BooleanType
    boolTypeAvailable = True
except ImportError:
    boolTypeAvailable = False
    
try:
    from threading import Lock
except ImportError:
    class Lock:
        def acquire(self): pass
        def release(self): pass

from Cheetah.Version import convertVersionStringToTuple, MinCompatibleVersionTuple
from Cheetah.Version import MinCompatibleVersion
# Base classes for Template
from Cheetah.Servlet import Servlet                 
# More intra-package imports ...
from Cheetah.Parser import ParseError, SourceReader
from Cheetah.Compiler import Compiler, DEFAULT_COMPILER_SETTINGS
from Cheetah import ErrorCatchers              # for placeholder tags
from Cheetah import Filters                    # the output filters
from Cheetah.convertTmplPathToModuleName import convertTmplPathToModuleName
from Cheetah.Utils import VerifyType             # Used in Template.__init__
from Cheetah.Utils.Misc import checkKeywords     # Used in Template.__init__
from Cheetah.Utils.Indenter import Indenter      # Used in Template.__init__ and for
                                                 # placeholders
from Cheetah.NameMapper import NotFound, valueFromSearchList
from Cheetah.CacheStore import MemoryCacheStore, MemcachedCacheStore
from Cheetah.CacheRegion import CacheRegion
from Cheetah.Utils.WebInputMixin import _Converter, _lookup, NonNumericInputError

from Cheetah.Unspecified import Unspecified

class Error(Exception):  pass
class PreprocessError(Error): pass

def hashList(l):
    hashedList = []
    for v in l:
        if isinstance(v, dict):
            v = hashDict(v)
        elif isinstance(v, list):
            v = hashList(v)
        hashedList.append(v)
    return hash(tuple(hashedList))

def hashDict(d):
    items = d.items()
    items.sort()
    hashedList = []
    for k, v in items:
        if isinstance(v, dict):
            v = hashDict(v)
        elif isinstance(v, list):
            v = hashList(v)
        hashedList.append((k,v))
    return hash(tuple(hashedList))

################################################################################
## MODULE GLOBALS AND CONSTANTS

def _genUniqueModuleName(baseModuleName):
    """The calling code is responsible for concurrency locking.
    """
    if baseModuleName not in sys.modules:
        finalName = baseModuleName
    else:
        finalName = ('cheetah_'+baseModuleName
                     +'_'
                     +''.join(map(lambda x: '%02d' % x, time.localtime(time.time())[:6]))
                     + str(randrange(10000, 99999)))
    return finalName

# Cache of a cgi.FieldStorage() instance, maintained by .webInput().
# This is only relavent to templates used as CGI scripts.
_formUsedByWebInput = None

# used in Template.compile()
def valOrDefault(val, default):                
    if val is not Unspecified: return val
    else: return default


class CompileCacheItem:
    pass

class TemplatePreprocessor:
    """This is used with the preprocessors argument to Template.compile().

    See the docstring for Template.compile
    
    ** Preprocessors are an advanced topic **
    """
    def __init__(self, settings):
        self._settings = settings

    def preprocess(self, source, file):
        """Create an intermediate template and return the source code
        it outputs                
        """
        settings = self._settings
        if not source: # @@TR: this needs improving
            if isinstance(file, (str, unicode)): # it's a filename.
                f = open(file)
                source = f.read()
                f.close()
            elif hasattr(file, 'read'):
                source = file.read()
            file = None        

        templateAPIClass = settings.templateAPIClass
        possibleKwArgs = [
            arg for arg in
            inspect.getargs(templateAPIClass.compile.im_func.func_code)[0]
            if arg not in ('klass', 'source', 'file',)]

        compileKwArgs = {}
        for arg in possibleKwArgs:
            if hasattr(settings, arg):
                compileKwArgs[arg] = getattr(settings, arg)

        tmplClass = templateAPIClass.compile(source=source, file=file, **compileKwArgs)
        tmplInstance = tmplClass(**settings.templateInitArgs)
        outputSource = settings.outputTransformer(tmplInstance)
        outputFile = None
        return outputSource, outputFile
        
class Template(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)
    """

    # this is used by ._addCheetahPlumbingCodeToClass()
    _CHEETAH_requiredCheetahMethods = (
         '_initCheetahInstance',
         'searchList',
         'errorCatcher',
         'getVar',
         'varExists',
         'getFileContents',
         'i18n',
         'runAsMainProgram',
         'respond',
         'shutdown',
         'webInput',
         'serverSidePath',
         'generatedClassCode',
         'generatedModuleCode',

         '_getCacheStore',
         '_getCacheStoreIdPrefix',
         '_createCacheRegion',
         'getCacheRegion',
         'getCacheRegions',
         'refreshCache',
         
         '_handleCheetahInclude',
         '_getTemplateAPIClassForIncludeDirectiveCompilation',
         )
    _CHEETAH_requiredCheetahClassMethods = ('subclass',) 
    _CHEETAH_requiredCheetahClassAttributes = ('cacheRegionClass','cacheStore',
                                               'cacheStoreIdPrefix','cacheStoreClass')

    ## the following are used by .compile(). Most are documented in its docstring.
    _CHEETAH_cacheModuleFilesForTracebacks = False
    _CHEETAH_cacheDirForModuleFiles = None # change to a dirname

    _CHEETAH_compileCache = dict() # cache store for compiled code and classes
    # To do something other than simple in-memory caching you can create an
    # alternative cache store. It just needs to support the basics of Python's
    # mapping/dict protocol. E.g.:
    #   class AdvCachingTemplate(Template):
    #       _CHEETAH_compileCache = MemoryOrFileCache()
    _CHEETAH_compileLock = Lock() # used to prevent race conditions
    _CHEETAH_defaultMainMethodName = None
    _CHEETAH_compilerSettings = None
    _CHEETAH_compilerClass = Compiler
    _CHEETAH_cacheCompilationResults = True
    _CHEETAH_useCompilationCache = True
    _CHEETAH_keepRefToGeneratedCode = True
    _CHEETAH_defaultBaseclassForTemplates = None
    _CHEETAH_defaultClassNameForTemplates = None
    # defaults to DEFAULT_COMPILER_SETTINGS['mainMethodName']:
    _CHEETAH_defaultMainMethodNameForTemplates = None 
    _CHEETAH_defaultModuleNameForTemplates = 'DynamicallyCompiledCheetahTemplate'
    _CHEETAH_defaultModuleGlobalsForTemplates = None
    _CHEETAH_preprocessors = None
    _CHEETAH_defaultPreprocessorClass = TemplatePreprocessor    
    
    ## The following attributes are used by instance methods:
    _CHEETAH_generatedModuleCode = None
    NonNumericInputError = NonNumericInputError
    _CHEETAH_cacheRegionClass = CacheRegion
    _CHEETAH_cacheStoreClass = MemoryCacheStore
    #_CHEETAH_cacheStoreClass = MemcachedCacheStore
    _CHEETAH_cacheStore = None  
    _CHEETAH_cacheStoreIdPrefix = None  

    def _getCompilerClass(klass, source=None, file=None):
        return klass._CHEETAH_compilerClass
    _getCompilerClass = classmethod(_getCompilerClass)

    def _getCompilerSettings(klass, source=None, file=None):
        return klass._CHEETAH_compilerSettings
    _getCompilerSettings = classmethod(_getCompilerSettings)
    
    def 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=[...]) ] )
            
        """
        ##################################################           
        ## normalize and validate args 
        try:
            vt = VerifyType.VerifyType
            vtc = VerifyType.VerifyTypeClass
            N = types.NoneType; S = types.StringType; U = types.UnicodeType
            D = types.DictType; F = types.FileType
            C = types.ClassType;  M = types.ModuleType
            I = types.IntType

            if boolTypeAvailable:         
                B = types.BooleanType
            
            vt(source, 'source', [N,S,U], 'string or None')
            vt(file, 'file',[N,S,U,F], 'string, file-like object, or None')

            baseclass = valOrDefault(baseclass, klass._CHEETAH_defaultBaseclassForTemplates)
            if isinstance(baseclass, Template):
                baseclass = baseclass.__class__
            vt(baseclass, 'baseclass', [N,S,C,type], 'string, class or None')

            cacheCompilationResults = valOrDefault(
                cacheCompilationResults, klass._CHEETAH_cacheCompilationResults)
            if boolTypeAvailable:         
                vt(cacheCompilationResults, 'cacheCompilationResults', [I,B], 'boolean')

            useCache = valOrDefault(useCache, klass._CHEETAH_useCompilationCache)
            if boolTypeAvailable:         
                vt(cacheCompilationResults, 'cacheCompilationResults', [I,B], 'boolean')

            compilerSettings = valOrDefault(
                compilerSettings, klass._getCompilerSettings(source, file) or {})
            vt(compilerSettings, 'compilerSettings', [D], 'dictionary')

            compilerClass = valOrDefault(compilerClass, klass._getCompilerClass(source, file))

            preprocessors = valOrDefault(preprocessors, klass._CHEETAH_preprocessors)

            keepRefToGeneratedCode = valOrDefault(
                keepRefToGeneratedCode, klass._CHEETAH_keepRefToGeneratedCode)
            if boolTypeAvailable:         
                vt(cacheCompilationResults, 'cacheCompilationResults', [I,B], 'boolean')
        
            vt(moduleName, 'moduleName', [N,S], 'string or None')
            __orig_file__ = None
            if not moduleName:
                if file and type(file) in StringTypes:
                    moduleName = convertTmplPathToModuleName(file)
                    __orig_file__ = file
                else:
                    moduleName = klass._CHEETAH_defaultModuleNameForTemplates
        
            className = valOrDefault(
                className, klass._CHEETAH_defaultClassNameForTemplates)
            vt(className, 'className', [N,S], 'string or None')
            className = className or moduleName

            mainMethodName = valOrDefault(
                mainMethodName, klass._CHEETAH_defaultMainMethodNameForTemplates)
            vt(mainMethodName, 'mainMethodName', [N,S], 'string or None')

            moduleGlobals = valOrDefault(
                moduleGlobals, klass._CHEETAH_defaultModuleGlobalsForTemplates)

            cacheModuleFilesForTracebacks = valOrDefault(
                cacheModuleFilesForTracebacks, klass._CHEETAH_cacheModuleFilesForTracebacks)
            if boolTypeAvailable:
                vt(cacheModuleFilesForTracebacks, 'cacheModuleFilesForTracebacks', [I,B], 'boolean')
            
            cacheDirForModuleFiles = valOrDefault(
                cacheDirForModuleFiles, klass._CHEETAH_cacheDirForModuleFiles)
            vt(cacheDirForModuleFiles, 'cacheDirForModuleFiles', [N,S], 'string or None')

        except TypeError, reason:
            raise TypeError(reason)

        ##################################################           
        ## handle any preprocessors
        if preprocessors:
            origSrc = source
            source, file = klass._preprocessSource(source, file, preprocessors)

        ##################################################                       
        ## compilation, using cache if requested/possible
        baseclassValue = None
        baseclassName = None
        if baseclass:
            if type(baseclass) in StringTypes:
                baseclassName = baseclass
            elif type(baseclass) in (ClassType, type):
                # @@TR: should soft-code this
                baseclassName = 'CHEETAH_dynamicallyAssignedBaseClass_'+baseclass.__name__
                baseclassValue = baseclass


        cacheHash = None
        cacheItem = None
        if source or isinstance(file, (str, unicode)):                
            compilerSettingsHash = None
            if compilerSettings:
                compilerSettingsHash = hashDict(compilerSettings)

            moduleGlobalsHash = None
            if moduleGlobals:
                moduleGlobalsHash = hashDict(moduleGlobals)

            fileHash = None
            if file:
                fileHash = str(hash(file))+str(os.path.getmtime(file))
                
            try:
                cacheHash = ''.join([str(v) for v in
                                     [hash(source),
                                      fileHash,
                                      className,
                                      moduleName,
                                      mainMethodName,
                                      hash(compilerClass),
                                      hash(baseclass),
                                      compilerSettingsHash,
                                      moduleGlobalsHash,
                                      hash(cacheDirForModuleFiles),
                                      ]])
            except:
                #@@TR: should add some logging to this
                pass
        if useCache and cacheHash and klass._CHEETAH_compileCache.has_key(cacheHash):
            cacheItem = klass._CHEETAH_compileCache[cacheHash]
            generatedModuleCode = cacheItem.code
            #print 'DEBUG: found cached copy'
        else:
            compiler = compilerClass(source, file,
                                     moduleName=moduleName,
                                     mainClassName=className,
                                     baseclassName=baseclassName,
                                     mainMethodName=mainMethodName,
                                     settings=(compilerSettings or {}))
            compiler.compile()
            generatedModuleCode = compiler.getModuleCode()

        if not returnAClass:
            return generatedModuleCode
        else:
            if cacheItem:
                cacheItem.lastCheckoutTime = time.time()
                return cacheItem.klass

            def updateLinecache(filename, src):
                import linecache
                size = len(src)
                mtime = time.time()
                lines = src.splitlines()
                fullname = filename
                linecache.cache[filename] = size, mtime, lines, fullname


            try:
                klass._CHEETAH_compileLock.acquire()
                uniqueModuleName = _genUniqueModuleName(moduleName)
                __file__ = uniqueModuleName+'.py' # relative file path with no dir part
                mod = new.module(uniqueModuleName)
                sys.modules[uniqueModuleName] = mod
            finally:
                klass._CHEETAH_compileLock.release()

            try:
                if cacheModuleFilesForTracebacks: