diff options
Diffstat (limited to 'tutorius')
| -rw-r--r-- | tutorius/core.py | 7 | ||||
| -rw-r--r-- | tutorius/vault.py (renamed from tutorius/bundler.py) | 483 |
2 files changed, 326 insertions, 164 deletions
diff --git a/tutorius/core.py b/tutorius/core.py index 6030457..15a0c87 100644 --- a/tutorius/core.py +++ b/tutorius/core.py @@ -515,9 +515,10 @@ class FiniteStateMachine(State): #TODO : Move this code inside the State itself - we're breaking # encap :P - for event, state in st._transitions: - if state == state_name: - del st._transitions[event] + if st._transitions: + for event, state in st._transitions.items(): + if state == state_name: + del st._transitions[event] # Remove the state from the dictionary del self._states[state_name] diff --git a/tutorius/bundler.py b/tutorius/vault.py index c9558b1..9215e8d 100644 --- a/tutorius/bundler.py +++ b/tutorius/vault.py @@ -22,32 +22,40 @@ This module contains all the data handling class of Tutorius import logging import os +import shutil +import tempfile import uuid import xml.dom.minidom from xml.dom import NotFoundErr +import zipfile from sugar.tutorius import addon from sugar.tutorius.core import Tutorial, State, FiniteStateMachine -from sugar.tutorius.filters import * -from sugar.tutorius.actions import * from ConfigParser import SafeConfigParser +logger = logging.getLogger("tutorius") + # this is where user installed/generated tutorials will go def _get_store_root(): profile_name = os.getenv("SUGAR_PROFILE") or "default" return os.path.join(os.getenv("HOME"), ".sugar",profile_name,"tutorius","data") # this is where activity bundled tutorials should be, under the activity bundle -def _get_bundle_root(base_path=None): - base_path = base_path or os.getenv("SUGAR_BUNDLE_PATH") - if base_path: +def _get_bundle_root(): + """ + Return the path of the bundled activity, or None if not applicable. + """ + if os.getenv("SUGAR_BUNDLE_PATH") != None: return os.path.join(os.getenv("SUGAR_BUNDLE_PATH"),"data","tutorius","data") + else: + return None INI_ACTIVITY_SECTION = "RELATED_ACTIVITIES" INI_METADATA_SECTION = "GENERAL_METADATA" -INI_GUID_PROPERTY = "GUID" -INI_NAME_PROPERTY = "NAME" -INI_XML_FSM_PROPERTY = "FSM_FILENAME" +INI_GUID_PROPERTY = "guid" +INI_NAME_PROPERTY = "name" +INI_XML_FSM_PROPERTY = "fsm_filename" +INI_VERSION_PROPERTY = 'version' INI_FILENAME = "meta.ini" TUTORIAL_FILENAME = "tutorial.xml" NODE_COMPONENT = "Component" @@ -55,65 +63,263 @@ NODE_SUBCOMPONENT = "property" NODE_SUBCOMPONENTLIST = "listproperty" NEXT_STATE_ATTR = "next_state" -class TutorialStore(object): - - def list_available_tutorials(self, activity_name, activity_vers): +class Vault(object): + + ## Vault internal functions : + @staticmethod + def list_available_tutorials(activity_name = None, activity_vers = 0): """ Generate the list of all tutorials present on disk for a given activity. + @param activity_name the name of the activity associated with this tutorial. None means ALL activities + @param activity_vers the version number of the activity to find tutorail for. 0 means find for ANY version. Ifactivity_ame is None, version number is not used @returns a map of tutorial {names : GUID}. """ # check both under the activity data and user installed folders - paths = [p for p in [_get_store_root(), _get_bundle_root()] if p ] + if _get_bundle_root() != None: + paths = [_get_store_root(), _get_bundle_root()] + else: + paths = [_get_store_root()] tutoGuidName = {} for repository in paths: # (our) convention dictates that tutorial folders are named - # with their GUID (for unicity) but this is not enforced. + # with their GUID (for unicity) try: for tuto in os.listdir(repository): parser = SafeConfigParser() - parser.read(os.path.join(repository, tuto, INI_FILENAME)) - guid = parser.get(INI_METADATA_SECTION, INI_GUID_PROPERTY) - name = parser.get(INI_METADATA_SECTION, INI_NAME_PROPERTY) - activities = parser.options(INI_ACTIVITY_SECTION) - # enforce matching activity name AND version, as UI changes - # break tutorials. We may lower this requirement when the - # UAM gets less dependent on the widget order. - # Also note property names are always stored lowercase. - if activity_name.lower() in activities: - version = parser.get(INI_ACTIVITY_SECTION, activity_name) - if activity_vers == version: + file = parser.read(os.path.join(repository, tuto, INI_FILENAME)) + if file != []: + # If parser can read at least section + guid = parser.get(INI_METADATA_SECTION, INI_GUID_PROPERTY) + name = parser.get(INI_METADATA_SECTION, INI_NAME_PROPERTY) + activities = parser.options(INI_ACTIVITY_SECTION) + # enforce matching activity name AND version, as UI changes + # break tutorials. We may lower this requirement when the + # UAM gets less dependent on the widget order. + # Also note property names are always stored lowercase. + if (activity_name != None) and (activity_name.lower() in activities): + version = parser.get(INI_ACTIVITY_SECTION, activity_name) + if (activity_vers == version) or (activity_vers == 0): + tutoGuidName[guid] = name + elif (activity_name == None): tutoGuidName[guid] = name except OSError: # the repository may not exist. Continue scanning pass return tutoGuidName - - def load_tutorial(self, Guid, bundle_path=None): + + ## Vault interface functions : + @staticmethod + def installTutorials(path, zip_file_name, forceinstall=False): + """ + Extract the tutorial files in the ZIPPED tutorial archive at the + specified path and add them inside the vault. This should remove any previous + version of this tutorial, if there's any. On the opposite, if we are + trying to install an earlier version, the function will return 1 if + forceInstall is not set to true. + + @params path The path where the zipped tutorial archive is present + @params forceinstall A flag that indicate if we need to force overwrite + of a tutorial even if is version number is lower than the existing one. + + @returns 0 if it worked, 1 if the user needs to confirm the installation + and 2 to mean an error happened + """ + # TODO : Check with architecture team for exception vs error returns + + # test if the file is a valid pkzip file + if zipfile.is_zipfile(os.path.join(path, zip_file_name)) != True: + assert False, "Error : The given file is not a valid PKZip file" + + # unpack the zip archive + zfile = zipfile.ZipFile(os.path.join(path, zip_file_name), "r" ) + + temp_path = tempfile.mkdtemp(dir=_get_store_root()) + zfile.extractall(temp_path) + + # get the tutorial file + ini_file_path = os.path.join(temp_path, INI_FILENAME) + ini_file = SafeConfigParser() + ini_file.read(ini_file_path) + + # get the tutorial guid + guid = ini_file.get(INI_METADATA_SECTION, INI_GUID_PROPERTY) + + # Check if tutorial already exist + tutorial_path = os.path.join(_get_store_root(), guid) + if os.path.isdir(tutorial_path) == False: + # Copy the tutorial in the Vault + shutil.copytree(temp_path, tutorial_path) + + else: + # Check the version of the existing tutorial + existing_version = ini_file.get(INI_METADATA_SECTION, INI_VERSION_PROPERTY) + # Check the version of the new tutorial + new_ini_file = SafeConfigParser() + new_ini_file.read(os.path.join(tutorial_path, INI_FILENAME)) + new_version = new_ini_file.get(INI_METADATA_SECTION, INI_VERSION_PROPERTY) + + if new_version < existing_version and forceinstall == False: + # Version of new tutorial is older and forceinstall is false, return exception + return 1 + else : + # New tutorial is newer or forceinstall flag is set, can overwrite the existing tutorial + shutil.rmtree(tutorial_path) + shutil.copytree(temp_path, tutorial_path) + + # Remove temp data + shutil.rmtree(temp_path) + + return 0 + + @staticmethod + def query(keyword=[], relatedActivityNames=[], category=[]): + """ + Returns the list of tutorials that corresponds to the specified parameters. + + @returns a list of Tutorial meta-data (TutorialID, Description, + Rating, Category, PublishState, etc...) + TODO : Search for tuto caracterised by the entry : OR between [], and between each + + The returned dictionnary is of this format : key = property name, value = property value + The dictionnary also contain one dictionnary element whose key is the string 'activities' + and whose value is another dictionnary of this form : key = related activity name, + value = related activity version number """ - Rebuilds a tutorial object from it's serialized state. - Common storing paths will be scanned. - @param Guid the generic identifier of the tutorial - @returns a Tutorial object containing an FSM + # Temp solution for returning all tutorials metadata + + tutorial_list = [] + tuto_guid_list = [] + ini_file = SafeConfigParser() + if keyword == [] and relatedActivityNames == [] and category == []: + # get all tutorials tuples (name:guid) for all activities and version + tuto_dict = Vault.list_available_tutorials() + for id in tuto_dict.keys(): + tuto_guid_list.append(id) + + # Find .ini metadata files with the guid list + + # Get the guid from the tuto tuples + for guid in tuto_guid_list: + # Create a dictionnary containing the metadata and also + # another dictionnary containing the tutorial Related Acttivities, + # and add it to a list + + # Create a TutorialBundler object from the guid + bundler = TutorialBundler(guid) + # Find the .ini file path for this guid + ini_file_path = bundler.get_tutorial_path(guid) + # Read the .ini file + ini_file.read(os.path.join(ini_file_path, 'meta.ini')) + + metadata_dictionnary = {} + related_act_dictionnary = {} + metadata_list = ini_file.options(INI_METADATA_SECTION) + for metadata_name in metadata_list: + # Create a dictionnary of tutorial metadata + metadata_dictionnary[metadata_name] = ini_file.get(INI_METADATA_SECTION, metadata_name) + # Get Related Activities data from.ini files + related_act_list = ini_file.options(INI_ACTIVITY_SECTION) + for related_act in related_act_list: + # For related activites, the format is : key = activity name, value = activity version + related_act_dictionnary[related_act] = ini_file.get(INI_ACTIVITY_SECTION, related_act) + + # Add Related Activities dictionnary to metadata dictionnary + metadata_dictionnary['activities'] = related_act_dictionnary + + # Add this dictionnary to tutorial list + tutorial_list.append(metadata_dictionnary) + + # Return tutorial list + return tutorial_list + + @staticmethod + def loadTutorial(Guid): + """ + Creates an executable version of a tutorial from its saved representation. + @returns an executable representation of a tutorial """ - bundler = TutorialBundler(Guid, bundle_path=bundle_path) - bundler_path = bundler.get_tutorial_path() + + bundle = TutorialBundler(Guid) + bundle_path = bundle.get_tutorial_path(Guid) config = SafeConfigParser() - config.read(os.path.join(bundler_path, INI_FILENAME)) + config.read(os.path.join(bundle_path, INI_FILENAME)) serializer = XMLSerializer() name = config.get(INI_METADATA_SECTION, INI_NAME_PROPERTY) - fsm = serializer.load_fsm(Guid, bundler.Path) + fsm = serializer.load_fsm(Guid, bundle_path) tuto = Tutorial(name, fsm) return tuto + + @staticmethod + def saveTutorial(tutorial, metadata_dict): + """ + Creates a persistent version of a tutorial in the Vault. + @returns true if the tutorial was saved correctly + """ + + # Get the tutorial guid from metadata dictionnary + guid = metadata_dict[INI_GUID_PROPERTY] + + # Check if tutorial already exist + tutorial_path = os.path.join(_get_store_root(), guid) + if os.path.isdir(tutorial_path) == False: + + # Serialize the tutorial and write it to disk + xml_ser = XMLSerializer() + os.makedirs(tutorial_path) + xml_ser.save_fsm(tutorial.state_machine, TUTORIAL_FILENAME, tutorial_path) + + # Create the metadata file + ini_file_path = os.path.join(tutorial_path, "meta.ini") + parser = SafeConfigParser() + parser.add_section(INI_METADATA_SECTION) + for key, value in metadata_dict.items(): + if key != 'activities': + parser.set(INI_METADATA_SECTION, key, value) + else: + related_activities_dict = value + parser.add_section(INI_ACTIVITY_SECTION) + for related_key, related_value in related_activities_dict.items(): + parser.set(INI_ACTIVITY_SECTION, related_key, related_value) + # Write the file to disk + with open(ini_file_path, 'wb') as configfile: + parser.write(configfile) + + else: + # Error, tutorial already exist + return False + + # TODO : wait for Ben input on how to unpublish tuto before coding this function + # For now, no unpublishing will occur. + + + @staticmethod + def deleteTutorial(Tutorial): + """ + Removes the tutorial from the Vault. It will unpublish the tutorial if need be, + and it will also wipe it from the persistent storage. + @returns true is the tutorial was deleted from the Vault + """ + bundle = TutorialBundler(Guid) + bundle_path = bundle.get_tutorial_path(Guid) + + # TODO : Need also to unpublish tutorial, need to interact with webservice module + + shutil.rmtree(bundle_path) + if os.path.isdir(bundle_path) == False: + return True + else: + return False + class Serializer(object): """ @@ -129,13 +335,13 @@ class Serializer(object): exception occur. If no GUID is provided, FSM is written in a new file in the store root. """ - return NotImplementedError() + raise NotImplementedError() def load_fsm(self): """ Load fsm from disk. """ - return NotImplementedError() + raise NotImplementedError() class XMLSerializer(Serializer): """ @@ -271,7 +477,7 @@ class XMLSerializer(Serializer): def _create_event_filters_node(self, event_filters, doc): """ - Create and return a xml Node from a event filters. + Create and return a xml Node from an event filters. """ eventFiltersList = doc.createElement("EventFiltersList") for event, state in event_filters: @@ -300,60 +506,7 @@ class XMLSerializer(Serializer): file_object = open(os.path.join(path, xml_filename), "w") file_object.write(doc.toprettyxml()) file_object.close() - - - def _find_tutorial_dir_with_guid(self, guid): - """ - Finds the tutorial with the associated GUID. If it is found, return - the path to the tutorial's directory. If it doesn't exist, raise an - IOError. - - A note : if there are two tutorials with this GUID in the folders, - they will both be inspected and the one with the highest version - number will be returned. If they have the same version number, the one - from the global store will be returned. - - @param guid The GUID of the tutorial that is to be loaded. - """ - # Attempt to find the tutorial's directory in the global directory - global_dir = os.path.join(_get_store_root(), guid) - # Then in the activty's bundle path - activity_dir = os.path.join(_get_bundle_root(), guid) - - # If they both exist - if os.path.isdir(global_dir) and os.path.isdir(activity_dir): - # Inspect both metadata files - global_meta = os.path.join(global_dir, "meta.ini") - activity_meta = os.path.join(activity_dir, "meta.ini") - - # Open both config files - global_parser = SafeConfigParser() - global_parser.read(global_meta) - - activity_parser = SafeConfigParser() - activity_parser.read(activity_meta) - - # Get the version number for each tutorial - global_version = global_parser.get(INI_METADATA_SECTION, "version") - activity_version = activity_parser.get(INI_METADATA_SECTION, "version") - - # If the global version is higher or equal, we'll take it - if global_version >= activity_version: - return global_dir - else: - return activity_dir - - # Do we just have the global directory? - if os.path.isdir(global_dir): - return global_dir - - # Or just the activity's bundle directory? - if os.path.isdir(activity_dir): - return activity_dir - - # Error : none of these directories contain the tutorial - raise IOError(2, "Neither the global nor the bundle directory contained the tutorial with GUID %s"%guid) - + def _get_direct_descendants_by_tag_name(self, node, name): """ Searches in the list of direct descendants of a node to find all the node @@ -375,14 +528,15 @@ class XMLSerializer(Serializer): return_list.append(childNode) return return_list - def _load_xml_properties(self, properties_elem): - """ - Changes a list of properties into fully instanciated properties. - - @param properties_elem An XML element reprensenting a list of - properties - """ - return [] + +## def _load_xml_properties(self, properties_elem): +## """ +## Changes a list of properties into fully instanciated properties. +## +## @param properties_elem An XML element reprensenting a list of +## properties +## """ +## return [] def _load_xml_event_filters(self, filters_elem): """ @@ -510,7 +664,7 @@ class XMLSerializer(Serializer): return reformed_state_list - def _load_xml_fsm(self, fsm_elem): + def load_xml_fsm(self, fsm_elem): """ Takes in an XML element representing an FSM and returns the fully crafted FSM. @@ -551,7 +705,8 @@ class XMLSerializer(Serializer): Load fsm from xml file whose .ini file guid match argument guid. """ # Fetch the directory (if any) - tutorial_dir = path or self._find_tutorial_dir_with_guid(guid) + bundler = TutorialBundler(guid) + tutorial_dir = bundler.get_tutorial_path(guid) # Open the XML file tutorial_file = os.path.join(tutorial_dir, TUTORIAL_FILENAME) @@ -560,7 +715,7 @@ class XMLSerializer(Serializer): fsm_elem = xml_dom.getElementsByTagName("FSM")[0] - return self._load_xml_fsm(fsm_elem) + return self.load_xml_fsm(fsm_elem) class TutorialBundler(object): @@ -582,20 +737,18 @@ class TutorialBundler(object): #Look for the file in the path if a uid is supplied if generated_guid: #General store - store_path = os.path.join(_get_store_root(), generated_guid, INI_FILENAME) + store_path = os.path.join(_get_store_root(), str(generated_guid), INI_FILENAME) if os.path.isfile(store_path): self.Path = os.path.dirname(store_path) - else: + elif _get_bundle_root() != None: #Bundle store - base_bundle_path = _get_bundle_root(bundle_path) - if base_bundle_path: - bundle_path = os.path.join(base_bundle_path, generated_guid, INI_FILENAME) - if os.path.isfile(bundle_path): - self.Path = os.path.dirname(bundle_path) - else: - raise IOError(2,"Unable to locate metadata file for guid '%s'" % generated_guid) + bundle_path = os.path.join(_get_bundle_root(), str(generated_guid), INI_FILENAME) + if os.path.isfile(bundle_path): + self.Path = os.path.dirname(bundle_path) else: raise IOError(2,"Unable to locate metadata file for guid '%s'" % generated_guid) + else: + raise IOError(2,"Unable to locate metadata file for guid '%s'" % generated_guid) else: #Create the folder, any failure will go through to the caller for now @@ -615,67 +768,75 @@ class TutorialBundler(object): cfg.set(INI_METADATA_SECTION, INI_NAME_PROPERTY, tutorial.name) cfg.set(INI_METADATA_SECTION, INI_XML_FSM_PROPERTY, TUTORIAL_FILENAME) cfg.add_section(INI_ACTIVITY_SECTION) - cfg.set(INI_ACTIVITY_SECTION, os.environ['SUGAR_BUNDLE_NAME'], + if os.environ['SUGAR_BUNDLE_NAME'] != None and os.environ['SUGAR_BUNDLE_VERSION'] != None: + cfg.set(INI_ACTIVITY_SECTION, os.environ['SUGAR_BUNDLE_NAME'], os.environ['SUGAR_BUNDLE_VERSION']) + else: + cfg.set(INI_ACTIVITY_SECTION, 'not_an_activity', '0') #Write the ini file cfg.write( file( os.path.join(self.Path, INI_FILENAME), 'w' ) ) - def get_tutorial_path(self): - """ - Return the path of the .ini file associated with the guiven guid set in - the Guid property of the Tutorial_Bundler. If the guid is present in - more than one path, the store_root is given priority. + + @staticmethod + def get_tutorial_path(guid): """ + Finds the tutorial with the associated GUID. If it is found, return + the path to the tutorial's directory. If it doesn't exist, raise an + IOError. - store_root = _get_store_root() - bundle_root = _get_bundle_root() + A note : if there are two tutorials with this GUID in the folders, + they will both be inspected and the one with the highest version + number will be returned. If they have the same version number, the one + from the global store will be returned. - config = SafeConfigParser() - path = None + @param guid The GUID of the tutorial that is to be loaded. + """ + # Attempt to find the tutorial's directory in the global directory + global_dir = os.path.join(_get_store_root(),str(guid)) + # Then in the activty's bundle path + if _get_bundle_root() != None: + activity_dir = os.path.join(_get_bundle_root(), str(guid)) + else: + activity_dir = '' - logging.debug("************ Path of store_root folder of activity : " \ - + store_root) - - # iterate in each GUID subfolder - for dir in os.listdir(store_root): + # If they both exist + if os.path.isdir(global_dir) and os.path.isdir(activity_dir): + # Inspect both metadata files + global_meta = os.path.join(global_dir, "meta.ini") + activity_meta = os.path.join(activity_dir, "meta.ini") - # iterate for each .ini file in the store_root folder - - for file_name in os.listdir(os.path.join(store_root, dir)): - if file_name.endswith(".ini"): - logging.debug("******************* Found .ini file : " \ - + file_name) - config.read(os.path.join(store_root, dir, file_name)) - if config.get(INI_METADATA_SECTION, INI_GUID_PROPERTY) == self.Guid: - xml_filename = config.get(INI_METADATA_SECTION, - INI_XML_FSM_PROPERTY) - - path = os.path.join(store_root, dir) - return path + # Open both config files + global_parser = SafeConfigParser() + global_parser.read(global_meta) - logging.debug("************ Path of bundle_root folder of activity : " \ - + bundle_root) + activity_parser = SafeConfigParser() + activity_parser.read(activity_meta) - - # iterate in each GUID subfolder - for dir in os.listdir(bundle_root): + # Get the version number for each tutorial + global_version = global_parser.get(INI_METADATA_SECTION, "version") + activity_version = activity_parser.get(INI_METADATA_SECTION, "version") - # iterate for each .ini file in the bundle_root folder - for file_name in os.listdir(os.path.join(bundle_root, dir)): - if file_name.endswith(".ini"): - logging.debug("******************* Found .ini file : " \ - + file_name) - config.read(os.path.join(bundle_root, dir, file_name)) - if config.get(INI_METADATA_SECTION, INI_GUID_PROPERTY) == self.Guid: - path = os.path.join(bundle_root, self.Guid) - return path - - if path is None: - logging.debug("**************** Error : GUID not found") - raise KeyError - - def write_fsm(self, fsm): + # If the global version is higher or equal, we'll take it + if global_version >= activity_version: + return global_dir + else: + return activity_dir + + # Do we just have the global directory? + if os.path.isdir(global_dir): + return global_dir + + # Or just the activity's bundle directory? + if os.path.isdir(activity_dir): + return activity_dir + + # Error : none of these directories contain the tutorial + raise IOError(2, "Neither the global nor the bundle directory contained the tutorial with GUID %s"%guid) + + + @staticmethod + def write_fsm(fsm): """ Save fsm to disk. If a GUID parameter is provided, the existing GUID is @@ -692,8 +853,8 @@ class TutorialBundler(object): xml_filename = config.get(INI_METADATA_SECTION, INI_XML_FSM_PROPERTY) serializer.save_fsm(fsm, xml_filename, self.Path) - - def add_resources(self, typename, file): + @staticmethod + def add_resources(typename, file): """ Add ressources to metadata. """ |