# Copyright (c) 2005, Enthought, Inc. # All rights reserved. # # This software is provided without warranty under the terms of the BSD # license included in enthought/LICENSE.txt and may be redistributed only # under the conditions described in the aforementioned license. The license # is also available online at http://www.enthought.com/licenses/BSD.txt # # Thanks for using Enthought open source! # # Author: David C. Morrill # Date: 11/03/2007 """ Defines the ImageLibrary object used to manage Traits UI image libraries. """ import sys from os import (environ, listdir, remove, stat, makedirs, rename, access, R_OK, W_OK, X_OK) from os.path import (join, isdir, isfile, splitext, abspath, dirname, basename, exists) from stat import ST_MTIME from platform import system from zipfile import is_zipfile, ZipFile, ZIP_DEFLATED from time import time, sleep, localtime, strftime from thread import allocate_lock from threading import Thread from traits.api import (HasPrivateTraits, Property, Str, Int, List, Dict, File, Instance, Bool, Undefined, TraitError, Float, Any, cached_property) from traits.trait_base import get_resource_path, traits_home from traitsui.ui_traits import HasMargin, HasBorder, Alignment from traitsui.theme import Theme from traitsui.toolkit import toolkit from pyface.api import ImageResource from pyface.resource_manager import resource_manager from pyface.resource.resource_reference import (ImageReference, ResourceReference) #--------------------------------------------------------------------------- # Constants: #--------------------------------------------------------------------------- # Standard image file extensions: ImageFileExts = ( '.png', '.gif', '.jpg', 'jpeg' ) # The image_cache root directory: image_cache_path = join( traits_home(), 'image_cache' ) # Names of files that should not be copied when ceating a new library copy: dont_copy_list = ( 'image_volume.py', 'image_info.py', 'license.txt' ) #-- Code Generation Templates ---------------------------------------------- # Template for creating an ImageVolumeInfo object: ImageVolumeInfoCodeTemplate = \ """ ImageVolumeInfo( description = %(description)s, copyright = %(copyright)s, license = %(license)s, image_names = %(image_names)s )""" # Template for creating an ImageVolumeInfo license text: ImageVolumeInfoTextTemplate = \ """Description: %s Copyright: %s License: %s Applicable Images: %s""" # Template for creating an ImageVolume object: ImageVolumeTemplate = \ """from traitsui.image.image import ImageVolume, ImageVolumeInfo volume = ImageVolume( category = %(category)s, keywords = %(keywords)s, aliases = %(aliases)s, time_stamp = %(time_stamp)s, info = [ %(info)s ] )""" # Template for creating an ImageVolume 'images' list: ImageVolumeImagesTemplate = \ """from traitsui.image.image import ImageInfo from traitsui.ui_traits import Margin, Border images = [ %s ]""" # Template for creating an ImageInfo object: ImageInfoTemplate = \ """ ImageInfo( name = %(name)s, image_name = %(image_name)s, description = %(description)s, category = %(category)s, keywords = %(keywords)s, width = %(width)d, height = %(height)d, border = Border( %(bleft)d, %(bright)d, %(btop)d, %(bbottom)d ), content = Margin( %(cleft)d, %(cright)d, %(ctop)d, %(cbottom)d ), label = Margin( %(lleft)d, %(lright)d, %(ltop)d, %(lbottom)d ), alignment = %(alignment)s )""" #------------------------------------------------------------------------------- # Returns the contents of the specified file: #------------------------------------------------------------------------------- def read_file ( file_name ): """ Returns the contents of the specified *file_name*. """ fh = file( file_name, 'rb' ) try: return fh.read() finally: fh.close() #------------------------------------------------------------------------------- # Writes the specified data to the specified file: #------------------------------------------------------------------------------- def write_file ( file_name, data ): """ Writes the specified data to the specified file. """ fh = file( file_name, 'wb' ) try: fh.write( data ) finally: fh.close() #------------------------------------------------------------------------------- # Returns the value of a Python symbol loaded from a specified source code # string: #------------------------------------------------------------------------------- def get_python_value ( source, name ): """ Returns the value of a Python symbol loaded from a specified source code string. """ temp = {} source = source.replace('traitsui', 'traitsui') exec source.replace( '\r', '' ) in globals(), temp return temp[ name ] #------------------------------------------------------------------------------- # Returns a specified time as a text string: #------------------------------------------------------------------------------- def time_stamp_for ( time ): """ Returns a specified time as a text string. """ return strftime( '%Y%m%d%H%M%S', localtime( time ) ) #------------------------------------------------------------------------------- # Adds all traits from a specified object to a dictionary with a specified name # prefix: #------------------------------------------------------------------------------- def add_object_prefix ( dict, object, prefix ): """ Adds all traits from a specified object to a dictionary with a specified name prefix. """ for name, value in object.get().iteritems(): dict[ prefix + name ] = value #------------------------------------------------------------------------------- # Splits a specified **image_name** into its constituent volume and file names # and returns a tuple of the form: ( volume_name, file_name ). #------------------------------------------------------------------------------- def split_image_name ( image_name ): """ Splits a specified **image_name** into its constituent volume and file names and returns a tuple of the form: ( volume_name, file_name ). """ col = image_name.find( ':' ) volume_name = image_name[ 1: col ] file_name = image_name[ col + 1: ] if file_name.find( '.' ) < 0: file_name += '.png' return ( volume_name, file_name ) #------------------------------------------------------------------------------- # Joins a specified **volume_name** and **file_name** into an image name, and # return the resulting image name: #------------------------------------------------------------------------------- def join_image_name ( volume_name, file_name ): """ Joins a specified **volume_name** and **file_name** into an image name, and return the resulting image name. """ root, ext = splitext( file_name ) if (ext == '.png') and (root.find( '.' ) < 0): file_name = root return '@%s:%s' % ( volume_name, file_name ) #------------------------------------------------------------------------------- # 'FastZipFile' class: #------------------------------------------------------------------------------- class FastZipFile ( HasPrivateTraits ): """ Provides fast access to zip files by keeping the underlying zip file open across multiple uses. """ # The path to the zip file: path = File # The open zip file object (if None, the file is closed): zf = Property # The time stamp of when the zip file was most recently accessed: time_stamp = Float # The lock used to manage access to the 'zf' trait between the two threads: access = Any #-- Public Methods --------------------------------------------------------- def namelist ( self ): """ Returns the names of all files in the top-level zip file directory. """ self.access.acquire() try: return self.zf.namelist() finally: self.access.release() def read ( self, file_name ): """ Returns the contents of the specified **file_name** from the zip file. """ self.access.acquire() try: return self.zf.read( file_name ) finally: self.access.release() def close ( self ): """ Temporarily closes the zip file (usually while the zip file is being replaced by a different version). """ self.access.acquire() try: if self._zf is not None: self._zf.close() self._zf = None finally: self.access.release() #-- Default Value Implementations ------------------------------------------ def _access_default ( self ): return allocate_lock() #-- Property Implementations ----------------------------------------------- def _get_zf ( self ): # Restart the time-out: self.time_stamp = time() if self._zf is None: self._zf = ZipFile( self.path, 'r' ) if self._running is None: Thread( target = self._process ).start() self._running = True return self._zf #-- Private Methods -------------------------------------------------------- def _process ( self ): """ Waits until the zip file has not been accessed for a while, then closes the file and exits. """ while True: sleep( 1 ) self.access.acquire() if time() > (self.time_stamp + 2.0): if self._zf is not None: self._zf.close() self._zf = None self._running = None self.access.release() break self.access.release() #------------------------------------------------------------------------------- # 'ImageInfo' class: #------------------------------------------------------------------------------- class ImageInfo ( HasPrivateTraits ): """ Defines a class that contains information about a specific Traits UI image. """ # The volume this image belongs to: volume = Instance( 'ImageVolume' ) # The user friendly name of the image: name = Str # The full image name (e.g. '@standard:floppy'): image_name = Str # A description of the image: description = Str # The category that the image belongs to: category = Str( 'General' ) # A list of keywords used to describe/categorize the image: keywords = List( Str ) # The image width (in pixels): width = Int # The image height (in pixels): height = Int # The theme for this image: theme = Instance( Theme ) # The border inset: border = HasBorder # The margin to use around the content: content = HasMargin # The margin to use around the label: label = HasMargin # The alignment to use for the label: alignment = Alignment # The copyright that applies to this image: copyright = Property # The license that applies to this image: license = Property # A read-only string containing the Python code needed to construct this # ImageInfo object: image_info_code = Property #-- Default Value Implementations ------------------------------------------ def _name_default ( self ): return split_image_name( self.image_name )[1] def _width_default ( self ): if self.volume is None: return 0 image = self.volume.image_resource( self.image_name ) if image is None: self.height = 0 return 0 width, self.height = toolkit().image_size( image.create_image() ) return width def _height_default ( self ): if self.volume is None: return 0 image = self.volume.image_resource( self.image_name ) if image is None: self.width = 0 return 0 self.width, height = toolkit().image_size( image.create_image() ) return height def _theme_default ( self ): image = None if self.volume is not None: image = self.volume.image_resource( self.image_name ) return Theme( image, border = self.border, content = self.content, label = self.label, alignment = self.alignment ) #-- Property Implementations ----------------------------------------------- def _get_image_info_code ( self ): data = dict( [ ( name, repr( value ) ) for name, value in self.get( 'name', 'image_name', 'description', 'category', 'keywords' ).iteritems() ] ) data.update( self.get( 'width', 'height' ) ) theme = self.theme data[ 'alignment' ] = repr( theme.alignment ) add_object_prefix( data, theme.border, 'b' ) add_object_prefix( data, theme.content, 'c' ) add_object_prefix( data, theme.label, 'l' ) return (ImageInfoTemplate % data) def _get_copyright ( self ): return self._volume_info( 'copyright' ) def _get_license ( self ): return self._volume_info( 'license' ) #-- Private Methods -------------------------------------------------------- def _volume_info ( self, name ): """ Returns the VolumeInfo object that applies to this image. """ info = self.volume.volume_info( self.image_name ) if info is not None: return getattr( info, name, 'Unknown' ) return 'Unknown' #------------------------------------------------------------------------------- # 'ImageVolumeInfo' class: #------------------------------------------------------------------------------- class ImageVolumeInfo ( HasPrivateTraits ): # A general description of the images: description = Str( 'No volume description specified.' ) # The copyright that applies to the images: copyright = Str( 'No copyright information specified.' ) # The license that applies to the images: license = Str( 'No license information specified.' ) # The list of image names within the volume the information applies to. # Note that an empty list means that the information applies to all images # in the volume: image_names = List( Str ) # A read-only string containing the Python code needed to construct this # ImageVolumeInfo object: image_volume_info_code = Property # A read-only string containing the text describing the volume info: image_volume_info_text = Property #-- Property Implementations ----------------------------------------------- @cached_property def _get_image_volume_info_code ( self ): data = dict( [ ( name, repr( value ) ) for name, value in self.get( 'description', 'copyright', 'license', 'image_names' ).iteritems() ] ) return (ImageVolumeInfoCodeTemplate % data) @cached_property def _get_image_volume_info_text ( self ): description = self.description.replace( '\n', '\n ' ) license = self.license.replace( '\n', '\n ' ).strip() image_names = self.image_names image_names.sort() if len( image_names ) == 0: image_names = [ 'All' ] images = '\n'.join( [ ' - ' + image_name for image_name in image_names ] ) return (ImageVolumeInfoTextTemplate % ( description, self.copyright, license, images )) #-- Public Methods --------------------------------------------------------- def clone ( self ): """ Returns a copy of the ImageVolumeInfo object. """ return self.__class__( **self.get( 'description', 'copyright', 'license' ) ) #------------------------------------------------------------------------------- # 'ImageVolume' class: #------------------------------------------------------------------------------- class ImageVolume ( HasPrivateTraits ): # The canonical name of this volume: name = Str # The list of volume descriptors that apply to this volume: info = List( ImageVolumeInfo ) # The category that the volume belongs to: category = Str( 'General' ) # A list of keywords used to describe the volume: keywords = List( Str ) # The list of aliases for this volume: aliases = List( Str ) # The path of the file that defined this volume: path = File # Is the path a zip file? is_zip_file = Bool( True ) # The FastZipFile object used to access the underlying zip file: zip_file = Instance( FastZipFile ) # The list of images available in the volume: images = List( ImageInfo ) # A dictionary mapping image names to ImageInfo objects: catalog = Property( depends_on = 'images' ) # The time stamp of when the image library was last modified: time_stamp = Str # A read-only string containing the Python code needed to construct this # ImageVolume object: image_volume_code = Property # A read-only string containing the Python code needed to construct the # 'images' list for this ImageVolume object: images_code = Property # A read-only string containing the text describing the contents of the # volume (description, copyright, license information, and the images they # apply to): license_text = Property #-- Public Methods --------------------------------------------------------- def update ( self ): """ Updates the contents of the image volume from the underlying image store, and saves the results. """ # Unlink all our current images: for image in self.images: image.volume = None # Make sure the images are up to date by deleting any current value: del self.images # Save the new image volume information: self.save() def save ( self ): """ Saves the contents of the image volume using the current contents of the **ImageVolume**. """ path = self.path if not self.is_zip_file: # Make sure the directory is writable: if not access( path, R_OK | W_OK | X_OK ): return False # Make sure the directory and zip file are writable: elif ((not access( dirname( path ), R_OK | W_OK | X_OK )) or (exists( path ) and (not access( path, W_OK )))): return False # Pre-compute the images code, because it can require a long time # to load all of the images so that we can determine their size, and we # don't want that time to interfere with the time stamp of the image # volume: images_code = self.images_code if not self.is_zip_file: # We need to time stamp when this volume info was generated, but # it needs to be the same or newer then the time stamp of the file # it is in. So we use the current time plus a 'fudge factor' to # allow for some slop in when the OS actually time stamps the file: self.time_stamp = time_stamp_for( time() + 5.0 ) # Write the volume manifest source code to a file: write_file( join( path, 'image_volume.py' ), self.image_volume_code ) # Write the image info source code to a file: write_file( join( path, 'image_info.py' ), images_code ) # Write a separate license file for human consumption: write_file( join( path, 'license.txt' ), self.license_text ) return True # Create a temporary name for the new .zip file: file_name = path + '.###' # Create the new zip file: new_zf = ZipFile( file_name, 'w', ZIP_DEFLATED ) try: # Get the current zip file: cur_zf = self.zip_file # Copy all of the image files from the current zip file to the new # zip file: for name in cur_zf.namelist(): if name not in dont_copy_list: new_zf.writestr( name, cur_zf.read( name ) ) # Temporarily close the current zip file while we replace it with # the new version: cur_zf.close() # We need to time stamp when this volume info was generated, but # it needs to be the same or newer then the time stamp of the file # it is in. So we use the current time plus a 'fudge factor' to # allow for some slop in when the OS actually time stamps the file: self.time_stamp = time_stamp_for( time() + 10.0 ) # Write the volume manifest source code to the zip file: new_zf.writestr( 'image_volume.py', self.image_volume_code ) # Write the image info source code to the zip file: new_zf.writestr( 'image_info.py', images_code ) # Write a separate license file for human consumption: new_zf.writestr( 'license.txt', self.license_text ) # Done creating the new zip file: new_zf.close() new_zf = None # Rename the original file to a temporary name, so we can give the # new file the original name. Note that unlocking the original zip # file after the previous close sometimes seems to take a while, # which is why we repeatedly try the rename until it either succeeds # or takes so long that it must have failed for another reason: temp_name = path + '.$$$' for i in range( 50 ): try: rename( path, temp_name ) break except: sleep( 0.1 ) try: rename( file_name, path ) file_name = temp_name except: rename( temp_name, path ) raise finally: if new_zf is not None: new_zf.close() remove( file_name ) return True def image_resource ( self, image_name ): """ Returns the ImageResource object for the specified **image_name**. """ # Get the name of the image file: volume_name, file_name = split_image_name( image_name ) if self.is_zip_file: # See if we already have the image file cached in the file system: cache_file = self._check_cache( file_name ) if cache_file is None: # If not cached, then create a zip file reference: ref = ZipFileReference( resource_factory = resource_manager.resource_factory, zip_file = self.zip_file, path = self.path, volume_name = self.name, file_name = file_name ) else: # Otherwise, create a cache file reference: ref = ImageReference( resource_manager.resource_factory, filename = cache_file ) else: # Otherwise, create a normal file reference: ref = ImageReference( resource_manager.resource_factory, filename = join( self.path, file_name ) ) # Create the ImageResource object using the reference (note that the # ImageResource class will not allow us to specify the reference in the # constructor): resource = ImageResource( file_name ) resource._ref = ref # Return the ImageResource: return resource def image_data ( self, image_name ): """ Returns the image data (i.e. file contents) for the specified image name. """ volume_name, file_name = split_image_name( image_name ) if self.is_zip_file: return self.zip_file.read( file_name ) else: return read_file( join( self.path, file_name ) ) def volume_info ( self, image_name ): """ Returns the ImageVolumeInfo object that corresponds to the image specified by **image_name**. """ for info in self.info: if ((len( info.image_names ) == 0) or (image_name in info.image_names)): return info # Should never occur: return None #-- Default Value Implementations ------------------------------------------ def _info_default ( self ): return [ ImageVolumeInfo() ] def _images_default ( self ): return self._load_image_info() #-- Property Implementations ----------------------------------------------- @cached_property def _get_catalog ( self ): return dict( [ ( image.image_name, image ) for image in self.images ] ) def _get_image_volume_code ( self ): data = dict( [ ( name, repr( value ) ) for name, value in self.get( 'description', 'category', 'keywords', 'aliases', 'time_stamp' ).iteritems() ] ) data['info'] = ',\n'.join( [ info.image_volume_info_code for info in self.info ] ) return (ImageVolumeTemplate % data) def _get_images_code ( self ): images = ',\n'.join( [ info.image_info_code for info in self.images ] ) return (ImageVolumeImagesTemplate % images) def _get_license_text ( self ): return (('\n\n%s\n' % ('-' * 79)).join( [ info.image_volume_info_text for info in self.info ] )) #-- Private Methods -------------------------------------------------------- def _load_image_info ( self ): """ Returns the list of ImageInfo objects for the images in the volume. """ # If there is no current path, then return a default list of images: if self.path == '': return [] time_stamp = time_stamp_for( stat( self.path )[ ST_MTIME ] ) volume_name = self.name old_images = [] cur_images = [] if self.is_zip_file: zf = self.zip_file # Get the names of all top-level entries in the zip file: names = zf.namelist() # Check to see if there is an image info manifest file: if 'image_info.py' in names: # Load the manifest code and extract the images list: old_images = get_python_value( zf.read( 'image_info.py' ), 'images' ) # Check to see if our time stamp is up to data with the file: if self.time_stamp < time_stamp: # If not, create an ImageInfo object for all image files # contained in the .zip file: for name in names: root, ext = splitext( name ) if ext in ImageFileExts: cur_images.append( ImageInfo( name = root, image_name = join_image_name( volume_name, name ) ) ) else: image_info_path = join( self.path, 'image_info.py' ) if exists( image_info_path ): # Load the manifest code and extract the images list: old_images = get_python_value( read_file( image_info_path ), 'images' ) # Check to see if our time stamp is up to data with the file: if self.time_stamp < time_stamp: # If not, create an ImageInfo object for each image file # contained in the path: for name in listdir( self.path ): root, ext = splitext( name ) if ext in ImageFileExts: cur_images.append( ImageInfo( name = root, image_name = join_image_name( volume_name, name ) ) ) # Merge the old and current images into a single up to date list: if len( cur_images ) == 0: images = old_images else: cur_image_set = dict( [ ( image.image_name, image ) for image in cur_images ] ) for old_image in old_images: cur_image = cur_image_set.get( old_image.image_name ) if cur_image is not None: cur_image_set[ old_image.image_name ] = old_image cur_image.volume = self old_image.width = cur_image.width old_image.height = cur_image.height cur_image.volume = None images = cur_image_set.values() # Set the new time stamp of the volume: self.time_stamp = time_stamp # Return the resulting sorted list as the default value: images.sort( key = lambda item: item.image_name ) # Make sure all images reference this volume: for image in images: image.volume = self return images def _check_cache ( self, file_name ): """ Checks to see if the specified zip file name has been saved in the image cache. If it has, it returns the fully-qualified cache file name to use; otherwise it returns None. """ cache_file = join( image_cache_path, self.name, file_name ) if (exists( cache_file ) and (time_stamp_for( stat( cache_file )[ ST_MTIME ] ) > self.time_stamp)): return cache_file return None #------------------------------------------------------------------------------- # 'ZipFileReference' class: #------------------------------------------------------------------------------- class ZipFileReference ( ResourceReference ): # The zip file to read; zip_file = Instance( FastZipFile ) # The volume name: volume_name = Str # The file within the zip file: file_name = Str # The name of the cached image file: cache_file = File #-- The 'ResourceReference' API -------------------------------------------- # The file name of the image (in this case, the cache file name): filename = Property #-- ResourceReference Interface Implementation ----------------------------- def load ( self ): """ Loads the resource. """ # Check if the cache file has already been created: cache_file = self.cache_file if cache_file == '': # Extract the data from the zip file: data = self.zip_file.read( self.file_name ) # Try to create an image from the data, without writing it to a # file first: image = self.resource_factory.image_from_data( data, Undefined ) if image is not None: return image # Make sure the correct image cache directory exists: cache_dir = join( image_cache_path, self.volume_name ) if not exists( cache_dir ): makedirs( cache_dir ) # Write the image data to the cache file: cache_file = join( cache_dir, self.file_name ) fh = file( cache_file, 'wb' ) try: fh.write( data ) finally: fh.close() # Save the cache file name in case we are called again: self.cache_file = cache_file # Release our reference to the zip file object: self.zip_file = None # Return the image data from the image cache file: return self.resource_factory.image_from_file( cache_file ) #-- Property Implementations ----------------------------------------------- def _get_filename ( self ): if self.cache_file == '': self.load() return self.cache_file #------------------------------------------------------------------------------- # 'ImageLibrary' class: #------------------------------------------------------------------------------- class ImageLibrary ( HasPrivateTraits ): """ Manages Traits UI image libraries. """ # The list of available image volumes in the library: volumes = List( ImageVolume ) # The volume dictionary (the keys are volume names, and the values are the # corresponding ImageVolume objects): catalog = Dict( Str, ImageVolume ) # The list of available images in the library: images = Property( List, depends_on = 'volumes.images' ) #-- Private Traits --------------------------------------------------------- # Mapping from a 'virtual' library name to a 'real' library name: aliases = Dict #-- Public methods --------------------------------------------------------- def image_info ( self, image_name ): """ Returns the ImageInfo object corresponding to a specified **image_name**. """ volume = self.find_volume( image_name ) if volume is not None: return volume.catalog.get( image_name ) return None def image_resource ( self, image_name ): """ Returns an ImageResource object for the specified image name. """ # If no volume was specified, use the standard volume: if image_name.find( ':' ) < 0: image_name = '@images:%s' % image_name[1:] # Find the correct volume, possible resolving any aliases used: volume = self.find_volume( image_name ) # Find the image within the volume and return its ImageResource object: if volume is not None: return volume.image_resource( image_name ) # Otherwise, the volume was not found: return None def find_volume ( self, image_name ): """ Returns the ImageVolume object corresponding to the specified **image_name** or None if the volume cannot be found. """ # Extract the volume name from the image name: volume_name, file_name = split_image_name( image_name ) # Find the correct volume, possibly resolving any aliases used: catalog = self.catalog aliases = self.aliases while volume_name not in catalog: volume_name = aliases.get( volume_name ) if volume_name is None: return None return catalog[ volume_name ] def add_volume ( self, file_name = None ): """ If **file_name** is a file, it adds an image volume specified by **file_name** to the image library. If **file_name** is a directory, it adds all image libraries contained in the directory to the image library. If **file_name** is omitted, all image libraries located in the *images* directory contained in the same directory as the caller are added. """ # If no file name was specified, derive a path from the caller's # source code location: if file_name is None: file_name = join( get_resource_path( 2 ), 'images' ) if isfile( file_name ): # Load an image volume from the specified file: volume = self._add_volume( file_name ) if volume is None: raise TraitError( "'%s' is not a valid image volume." % file_name ) if volume.name in self.catalog: self._duplicate_volume( volume.name ) self.catalog[ volume.name ] = volume self.volumes.append( volume ) elif isdir( file_name ): # Load all image volumes from the specified path: catalog = self.catalog volumes = self._add_path( file_name ) for volume in volumes: if volume.name in catalog: self._duplicate_volume( volume.name ) catalog[ volume.name ] = volume self.volumes.extend( volumes ) else: # Handle an unrecognized argument: raise TraitError( "The add method argument must be None or a file " "or directory path, but '%s' was specified." % file_name ) def add_path ( self, volume_name, path = None ): """ Adds the directory specified by **path** as a *virtual* volume called **volume_name**. All image files contained within path define the contents of the volume. If **path** is None, the *images* contained in the 'images' subdirectory of the same directory as the caller are is used as the path for the *virtual* volume.. """ # Make sure we don't already have a volume with that name: if volume_name in self.catalog: raise TraitError( ("The volume name '%s' is already in the image " "library.") % volume_name ) # If no path specified, derive one from the caller's source code # location: if path is None: path = join( get_resource_path( 2 ), 'images' ) # Make sure that the specified path is a directory: if not isdir( path ): raise TraitError( "The image volume path '%s' does not exist." % path ) # Create the ImageVolume to describe the path's contents: image_volume_path = join( path, 'image_volume.py' ) if exists( image_volume_path ): volume = get_python_value( read_file( image_volume_path ), 'volume' ) else: volume = ImageVolume() # Set up the rest of the volume information: volume.set( name = volume_name, path = path, is_zip_file = False ) # Try to bring the volume information up to date if necessary: if volume.time_stamp < time_stamp_for( stat( path )[ ST_MTIME ] ): # Note that the save could fail if the volume is read-only, but # that's OK, because we're only trying to do the save in case # a developer had added or deleted some image files, which would # require write access to the volume: volume.save() # Add the new volume to the library: self.catalog[ volume_name ] = volume self.volumes.append( volume ) def extract ( self, file_name, image_names ): """ Builds a new image volume called **file_name** from the list of image names specified by **image_names**. Each image name should be of the form: '@volume:name'. """ # Get the volume name and file extension: volume_name, ext = splitext( basename( file_name ) ) # If no extension specified, add the '.zip' file extension: if ext == '': file_name += '.zip' # Create the ImageVolume object to describe the new volume: volume = ImageVolume( name = volume_name ) # Make sure the zip file does not already exists: if exists( file_name ): raise TraitError( "The '%s' file already exists." % file_name ) # Create the zip file: zf = ZipFile( file_name, 'w', ZIP_DEFLATED ) # Add each of the specified images to it and the ImageVolume: error = True aliases = set() keywords = set() images = [] info = {} try: for image_name in set( image_names ): # Verify the image name is legal: if (image_name[:1] != '@') or (image_name.find( ':' ) < 0): raise TraitError( ("The image name specified by '%s' is " "not of the form: @volume:name.") % image_name ) # Get the reference volume and image file names: image_volume_name, image_file_name = \ split_image_name( image_name ) # Get the volume for the image name: image_volume = self.find_volume( image_name ) if image_volume is None: raise TraitError( ("Could not find the image volume " "specified by '%s'.") % image_name ) # Get the image info: image_info = image_volume.catalog.get( image_name ) if image_info is None: raise TraitError( ("Could not find the image specified by " "'%s'.") % image_name ) # Add the image info to the list of images: images.append( image_info ) # Add the image file to the zip file: zf.writestr( image_file_name, image_volume.image_data( image_name ) ) # Add the volume alias needed by the image (if any): if image_volume_name != volume_name: if image_volume_name not in aliases: aliases.add( image_volume_name ) # Add the volume keywords as well: for keyword in image_volume.keywords: keywords.add( keyword ) # Add the volume info for the image: volume_info = image_volume.volume_info( image_name ) vinfo = info.get( image_volume_name ) if vinfo is None: info[ image_volume_name ] = vinfo = volume_info.clone() vinfo.image_names.append( image_name ) # Create the list of images for the volume: images.sort( key = lambda item: item.image_name ) volume.images = images # Create the list of aliases for the volume: volume.aliases = list( aliases ) # Create the list of keywords for the volume: volume.keywords = list( keywords ) # Create the final volume info list for the volume: volume.info = info.values() # Write the volume manifest source code to the zip file: zf.writestr( 'image_volume.py', volume.image_volume_code ) # Write the image info source code to the zip file: zf.writestr( 'image_info.py', volume.images_code ) # Write a separate licenses file for human consumption: zf.writestr( 'license.txt', volume.license_text ) # Indicate no errors occurred: error = False finally: zf.close() if error: remove( file_name ) #-- Default Value Implementations ------------------------------------------ def _volumes_default ( self ): result = [] # Check for and add the 'application' image library: app_library = join( dirname( abspath( sys.argv[0] ) ), 'library' ) if isdir( app_library ): result.extend( self._add_path( app_library ) ) # Get all volumes in the standard Traits UI image library directory: result.extend( self._add_path( join( get_resource_path( 1 ), 'library' ) ) ) # Check to see if there is an environment variable specifying a list # of paths containing image libraries: paths = environ.get( 'TRAITS_IMAGES' ) if paths is not None: # Determine the correct OS path separator to use: separator = ';' if system() != 'Windows': separator = ':' # Add all image volumes found in each path in the environment # variable: for path in paths.split( separator ): result.extend( self._add_path( path ) ) # Return the list of default volumes found: return result def _catalog_default ( self ): return dict( [ ( volume.name, volume ) for volume in self.volumes ] ) #-- Property Implementations ----------------------------------------------- @cached_property def _get_images ( self ): return self._get_images_list() #-- Private Methods -------------------------------------------------------- def _get_images_list ( self ): """ Returns the list of all library images. """ # Merge the list of images from each volume: images = [] for volume in self.volumes: images.extend( volume.images ) # Sort the result: images.sort( key = lambda image: image.image_name ) # Return the images list: return images def _add_path ( self, path ): """ Returns a list of ImageVolume objects, one for each image library located in the specified **path**. """ result = [] # Make sure the path is a directory: if isdir( path ): # Find each zip file in the directory: for base in listdir( path ): if splitext( base )[1] == '.zip': # Try to create a volume from the zip file and add it to # the result: volume = self._add_volume( join( path, base ) ) if volume is not None: result.append( volume ) # Return the list of volumes found: return result def _add_volume ( self, path ): """ Returns an ImageVolume object for the image library specified by **path**. If **path** does not specify a valid ImageVolume, None is returned. """ path = abspath( path ) # Make sure the path is a valid zip file: if is_zipfile( path ): # Create a fast zip file for reading: zf = FastZipFile( path = path ) # Extract the volume name from the path: volume_name = splitext( basename( path ) )[0] # Get the names of all top-level entries in the zip file: names = zf.namelist() # Check to see if there is a manifest file: if 'image_volume.py' in names: # Load the manifest code and extract the volume object: volume = get_python_value( zf.read( 'image_volume.py' ), 'volume' ) # Set the volume name: volume.name = volume_name # Try to add all of the external volume references as # aliases for this volume: self._add_aliases( volume ) # Set the path to this volume: volume.path = path # Save the reference to the zip file object we are using: volume.zip_file = zf else: # Create a new volume from the zip file: volume = ImageVolume( name = volume_name, path = path, zip_file = zf ) # If this volume is not up to date, update it: if volume.time_stamp < time_stamp_for( stat( path )[ ST_MTIME ] ): # Note that the save could fail if the volume is read-only, but # that's OK, because we're only trying to do the save in case # a developer had added or deleted some image files, which would # require write access to the volume: volume.save() # Return the volume: return volume # Indicate no volume was found: return None def _add_aliases ( self, volume ): """ Try to add all of the external volume references as aliases for this volume. """ aliases = self.aliases volume_name = volume.name for vname in volume.aliases: if ((vname in aliases) and (volume_name != aliases[ vname ])): raise TraitError( ("Image library error: " "Attempt to alias '%s' to '%s' when it is " "already aliased to '%s'") % ( vname, volume_name, aliases[ volume_name ] ) ) aliases[ vname ] = volume_name def _duplicate_volume ( self, volume_name ): """ Raises a duplicate volume name error. """ raise TraitError( ("Attempted to add an image volume called '%s' when " "a volume with that name is already defined.") % volume_name ) # Create the singleton image object: ImageLibrary = ImageLibrary()