library.py

Go to the documentation of this file.

#................................................................................
# The MIT License

# Copyright (c) 2009 David Car, david.car7@gmail.com

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
#................................................................................

__all__ = ['Library',
           'CacheManager']

from tables import SymbolTable
from scanners import LineScanner
import shelve
import os
import sys
import time
import pickle
import glob

#................................................................................
# Library helper functions
#................................................................................

#................................................................................
class Library(object):
    '''This is a class which acts as a library to store/retrieve pre-parsed
    blocks.  It uses the Python shelve module for peristent storage.  It will
    also have the ability to store instantiated templates correlated with
    their parent file.

    '''

    VERSION = '1.1'

    def __init__(self, name, blockList):
        '''Library constructor

        Input
        -----
        name : library file name
        blockList : list of block types for use with library.  This is needed
                    for block reconstruction.

        '''
        
        self._name = name
        self._blockDict = {}
        for blk in blockList:
            self._blockDict[blk.BLOCKTYPE] = blk
        self._metadata = None
        self._lib = None
        self.open()

    def __getitem__(self, name):
        '''Return an item from the library.

        '''
        return self._lib.get(name, None)

    def __setitem__(self, name, item):
        '''Store an item in the library.  The item must be serializable.

        '''
        self._lib[name] = item

    def close(self):
        '''Close the database to make sure it is current.

        '''
        if self._lib is None: return
        try:
            self._metadata['LAST CLOSED'] = time.asctime()
            self._lib['METADATA'] = self._metadata
            self._lib.close()
        except:
            pass

    def open(self):
        '''Open the database.

        '''
        self.close()
        _newLib = not os.path.exists(self._name)
        self._lib = shelve.DbfilenameShelf(self._name)
        #................................................................................
        # Check the Library metadata
        #................................................................................
        _metadata = self._lib.get('METADATA', None)
        if _metadata:
            self._metadata = _metadata
            _ver = _metadata.get('VERSION', None)
        else:
            _ver = None
            self._metadata = {'VERSION': self.VERSION,
                              'LAST OPENED': time.asctime(),
                              'LAST CLOSED': time.asctime()}
            self._lib['METADATA'] = self._metadata
        if _newLib: return

        if _ver == None:
            print 'WARNING: Library missing version number'
            print 'MESSAGE: Storing version as %s'%(self.VERSION,)
            self._metadata['VERSION'] = self.VERSION
            self._lib['METADATA'] = self._metadata
        elif str(_ver) > self.VERSION:
            print 'WARNING: Library is newer than your version of BlockIt'
            print 'WARNING: Unknown behaviour can result'
            print '''MESSAGE: You may consider using a library tool or
        rebuilding the library'''
            print 'MESSAGE: Your version is %s'%(str(_ver),)
            print 'MESSAGE: Library class version is %s'%(self.VERSION,)
        elif str(_ver) < self.VERSION:
            print 'MESSAGE: Library is older than your version of BlockIt'
            print 'MESSAGE: Upgrading metadata'
            self._metadata['VERSION'] = self.VERSION
            self._upgradeLib()

        diff = 0
        try:
            lastOpened = self._metadata['LAST OPENED']
            lastClosed = self._metadata['LAST CLOSED']
            diff = time.mktime(time.strptime(lastOpened, '%a %b %d %H:%M:%S %Y'))-\
                time.mktime(time.strptime(lastClosed, '%a %b %d %H:%M:%S %Y'))
        except:
            self._metadata['LAST CLOSED'] = time.asctime()

        if diff > 0:
            print '*'*80
            print 'WARNING: Library %s was not closed properly!'%(self._name,)
            print '*'*80

        self._metadata['LAST OPENED'] = time.asctime()
        self._lib['METADATA'] = self._metadata

    def keys(self):
        '''Wrapper to return the database keys.

        '''
        try:
            return self._lib.keys()
        except:
            return []

    def name(self):
        return self._name

    def fromFile(self, name, hsh=None):
        '''Read a block from a pickled block file.  This will restore everything
        necessary to for the block and all its children which was written
        using the blocks toFile method.

        Input
        -----
        name : block fileName to read from
        hsh : a hash to compare file hash with.  If the same, then pickle file is
              read, else None is returned.

        '''
        import pickle

        input = open(name+'.pkl','rb')
        _hsh, _tree = pickle.load(hsh_)
        if hsh is not None:
            if hsh != _hsh: return None

        input.close()
        return self.unpackTree(_tree)

    def unpackTree(self, tree):
        '''Unpack a dictionary tree of blocks and return parent block.

        '''
        _parent, _children = tree
        _params = _parent['_parameters']
        _blockType = _parent['_blockType']
        cons = self._blockDict.get(_blockType, None)
        if cons is None:
            print '''WARNING: Library does not have necessary constructor to
        build block "%s"'''%(_blockType,)
            return None

        parent = cons(_params)
        parent.__dict__.update(_parent)

        for node in _children:
            child = self.unpackTree(node)
            child.setParent(parent)
            parent._children.register(child)

        return parent

    def get( self, item, default ):
        try:
            value = self._lib[ item ]
        except:
            value = default
        return value
    
    def pop(self, item):
        try:
            return self._lib.pop(item)
        except:
            pass
        
    @staticmethod
    def genKey(blk):
        '''Static method to generate a library key from an object that has
        a fileName() or name() and hash() method.

        Input
        -----
        blk : object with a fileName() or name() and hash() method. fileName()
              is tried first, then name().

        '''

        name = getattr(blk, 'fileName', None) or getattr(blk, 'name', None)
        if name is not None:
            return os.path.join(name(), blk.hash())
        else:
            raise Exception('''Object does not support correct API to generate
        key name''')

    def _upgradeLib( self ):
        '''Function called when a library version number is less than the the
        current codes version number for the library.

        '''
        pass

    def __iadd__(self, other):
        '''Add contents of another library into this library using unary add,
        i.e. self += other.  
        '''
        try:
            self._lib.update(other._lib)
            self._blockDict.update(other._blockDict)
            self._lib['METADATA'] = self._metadata
        except:
            print "Error merging library %s into this library."%(other._name,)

        return self

#================================================================================
class CacheManager( object ):
    '''Class to manage cached (i.e. pickled) blocks.  Need to inherit from
    this class and add a genCacheName() method which takes a block and returns
    a tuple of (boolean, string).  See virtual method genCacheName() for details.

    '''
    def __init__( self, ext='.cache' ):
        self._ext = ext

    def fromCache( self, blk ):
        '''Check for a cached version of the given blk.  If there is and the
        block version number matches the passed in block version, then it is
        returned; else the cache is cleared and None is returned.

        '''
        _blk = None
        stat, cacheName = self.genCacheName( blk )
        newer, exists = stat
        if newer:
            try:
                fd = open( cacheName, 'rb' )
                version = fd.readline().rstrip()
                if version == blk.version(): 
                    _blk = pickle.load( fd )
                else:
                    fd.close()
                    self.clearCache( blk )
            except:
                sys.stderr.write( 'Error reading cache for file %s%s' %
                                  (blk.name(), os.linesep) )
            finally:
                fd.close()
        return _blk

    def fromCacheSerialized( self, blk ):
        '''Just read the pickled version of the block from the cache file if
        it exists and return it without unpickling.

        '''
        _blk = None
        stat, cacheName = self.genCacheName( blk )
        newer, exists = stat
        if newer:
            fd = open( cacheName, 'rb' )
            try:
                version = fd.readline().rstrip()
                if version == blk.version(): 
                    _blk = fd.read()
                else:
                    fd.close()
                    self.clearCache( blk )
            except:
                sys.stderr.write( 'Error reading cache for file %s%s' %
                                  (blk.name(), os.linesep) )
            finally:
                fd.close()
        return _blk

    def unSerialize( self, serial ):
        '''Unserialize a cached file.  This is just a wrapper for pickle.loads
        method. 

        '''
        return pickle.loads( serial )

    def clearCache( self, blk ):
        '''Clear all caches related to the block.

        '''
        stat, cacheName = self.genCacheName( blk )
        newer, exists = stat
        if exists:
            dir = os.path.dirname( cacheName )
            for f in glob.glob( os.path.join( dir, '*' + self._ext ) ):
                os.remove( f )

    def toCache( self, blk ):
        '''Write a blk to a cache file.

        '''
        stat, cacheName = self.genCacheName( blk )
        newer, exists = stat
        try:
            fd = open( cacheName, 'wb' )
            fromCache = blk.fromCache
            blk.fromCache = True
            fd.write( blk.version() + os.linesep )
            pickle.dump( blk, fd )
            blk.fromCache = fromCache
        except:
            sys.stderr.write( 'Error caching file %s%s' % 
                              (blk.name(), os.linesep) )
        finally:
            fd.close()

        return

    #................................................................................
    # Virtual Methods
    #................................................................................
    def genCacheName( self, blk ):
        '''Takes a block and returns a tuple.  The first element is a
        two-tuple with the fist elementa boolean on whether the cacheName is
        older than the originating blk (i.e. the provided argument), the
        second element is if the cacheName exists.  The second arg in the main
        tuple is the name of the cache file.  For example:

        ( ( true, true ), "myCache.pkl" ) - means that the cache file exists
        and is newer than the file that contains the passed in block and the
        name of the cache file is "myCache.pkl".

        '''
        raise NotImplementedError('''Virtual method 'genCacheName' in CacheManager
        class''')


    ext = property( fget=lambda x: x._ext )