From 0c3f127c86af818d260966d2292b199757087157 Mon Sep 17 00:00:00 2001 From: Simon Poirier Date: Sat, 11 Jul 2009 21:39:46 +0000 Subject: repackage --- (limited to 'tutorius/bundler.py') diff --git a/tutorius/bundler.py b/tutorius/bundler.py new file mode 100644 index 0000000..8e7fc3d --- /dev/null +++ b/tutorius/bundler.py @@ -0,0 +1,556 @@ +# Copyright (C) 2009, Tutorius.org +# Copyright (C) 2009, Jean-Christophe Savard +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + +""" +This module contains all the data handling class of Tutorius +""" + +import logging +import os +import uuid +import xml.dom.minidom + +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 + +# this is where user installed/generated tutorials will go +def _get_store_root(): + return os.path.join(os.getenv("HOME"),".sugar",os.getenv("SUGAR_PROFILE"),"tutorius","data") +# this is where activity bundled tutorials should be, under the activity bundle +def _get_bundle_root(): + return os.path.join(os.getenv("SUGAR_BUNDLE_PATH"),"data","tutorius","data") + +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_FILENAME = "meta.ini" +TUTORIAL_FILENAME = "tutorial.xml" +NODE_COMPONENT = "Component" + +class TutorialStore(object): + + def list_available_tutorials(self, activity_name, activity_vers): + """ + Generate the list of all tutorials present on disk for a + given activity. + + @returns a map of tutorial {names : GUID}. + """ + # check both under the activity data and user installed folders + paths = [_get_store_root(), _get_bundle_root()] + + tutoGuidName = {} + + for repository in paths: + # (our) convention dictates that tutorial folders are named + # with their GUID (for unicity) but this is not enforced. + 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: + tutoGuidName[guid] = name + except OSError: + # the repository may not exist. Continue scanning + pass + + return tutoGuidName + + def load_tutorial(self, Guid): + """ + 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 + """ + bundle = TutorialBundler(Guid) + bundle_path = bundle.get_tutorial_path() + config = SafeConfigParser() + 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) + + tuto = Tutorial(name, fsm) + return tuto + + +class Serializer(object): + """ + Interface that provide serializing and deserializing of the FSM + used in the tutorials to/from disk. Must be inherited. + """ + + def save_fsm(self,fsm): + """ + Save fsm to disk. If a GUID parameter is provided, the existing GUID is + located in the .ini files in the store root and bundle root and + the corresponding FSM is/are overwritten. If the GUId is not found, an + exception occur. If no GUID is provided, FSM is written in a new file + in the store root. + """ + NotImplementedError + + def load_fsm(self): + """ + Load fsm from disk. + """ + NotImplementedError + +class XMLSerializer(Serializer): + """ + Class that provide serializing and deserializing of the FSM + used in the tutorials to/from a .xml file. Inherit from Serializer + """ + + def _create_state_dict_node(self, state_dict, doc): + """ + Create and return a xml Node from a State dictionnary. + """ + statesList = doc.createElement("States") + for state_name, state in state_dict.items(): + stateNode = doc.createElement("State") + statesList.appendChild(stateNode) + stateNode.setAttribute("Name", state_name) + actionsList = stateNode.appendChild(self._create_action_list_node(state.get_action_list(), doc)) + eventfiltersList = stateNode.appendChild(self._create_event_filters_node(state.get_event_filter_list(), doc)) + return statesList + + def _create_component_node(self, comp, doc): + """ + Takes a single component (action or eventfilter) and transforms it + into a xml node. + + @param comp A single component + @param doc The XML document root (used to create nodes only + @return A XML Node object with the component tag name + """ + compNode = doc.createElement(NODE_COMPONENT) + + # Write down just the name of the Action class as the Class + # property -- + compNode.setAttribute("Class",type(comp).__name__) + + # serialize all tutorius properties + for propname in comp.get_properties(): + propval = getattr(comp, propname) + if getattr(type(comp), propname).type == "addonlist": + for subval in propval: + compNode.appendChild(self._create_component_node(subval, doc)) + elif getattr(type(comp), propname).type == "addonlist": + compNode.appendChild(self._create_component_node(subval, doc)) + else: + # repr instead of str, as we want to be able to eval() it into a + # valid object. + compNode.setAttribute(propname, repr(propval)) + + return compNode + + def _create_action_list_node(self, action_list, doc): + """ + Create and return a xml Node from a Action list. + + @param action_list A list of actions + @param doc The XML document root (used to create new nodes only) + @return A XML Node object with the Actions tag name and a serie of + Action children + """ + actionsList = doc.createElement("Actions") + for action in action_list: + # Create the action node + actionNode = self._create_component_node(action, doc) + # Append it to the list + actionsList.appendChild(actionNode) + + return actionsList + + def _create_event_filters_node(self, event_filters, doc): + """ + Create and return a xml Node from a event filters. + """ + eventFiltersList = doc.createElement("EventFiltersList") + for event_f in event_filters: + eventFilterNode = self._create_component_node(event_f, doc) + eventFiltersList.appendChild(eventFilterNode) + + return eventFiltersList + + def save_fsm(self, fsm, xml_filename, path): + """ + Save fsm to disk, in the xml file specified by "xml_filename", in the + "path" folder. If the specified file doesn't exist, it will be created. + """ + self.doc = doc = xml.dom.minidom.Document() + fsm_element = doc.createElement("FSM") + doc.appendChild(fsm_element) + fsm_element.setAttribute("Name", fsm.name) + fsm_element.setAttribute("StartStateName", fsm.start_state_name) + statesDict = fsm_element.appendChild(self._create_state_dict_node(fsm._states, doc)) + + fsm_actions_node = self._create_action_list_node(fsm.actions, doc) + fsm_actions_node.tagName = "FSMActions" + actionsList = fsm_element.appendChild(fsm_actions_node) + + 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 _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): + """ + Loads up a list of Event Filters. + + @param filters_elem An XML Element representing a list of event filters + """ + reformed_event_filters_list = [] + event_filter_element_list = filters_elem.getElementsByTagName(NODE_COMPONENT) + new_event_filter = None + + for event_filter in event_filter_element_list: + new_event_filter = self._load_xml_component(event_filter) + + if new_event_filter is not None: + reformed_event_filters_list.append(new_event_filter) + + return reformed_event_filters_list + + def _load_xml_component(self, node): + """ + Loads a single addon component instance from an Xml node. + + @param node The component XML Node to transform + object + @return The addon component object of the correct type according to the XML + description + """ + new_action = addon.create(node.getAttribute("Class")) + if not new_action: + return None + + for attrib in node.attributes.keys(): + if attrib == "Class": continue + # security note: keep sandboxed + setattr(new_action, attrib, eval(node.getAttribute(attrib), {}, {})) + + # recreate complex attributes + for sub in node.childNodes: + name = getattr(new_action, sub.nodeName) + if name == "addon": + setattr(new_action, sub.getAttribute("Name"), self._load_xml_action(sub)) + + return new_action + + def _load_xml_actions(self, actions_elem): + """ + Transforms an Actions element into a list of instanciated Action. + + @param actions_elem An XML Element representing a list of Actions + """ + reformed_actions_list = [] + actions_element_list = actions_elem.getElementsByTagName(NODE_COMPONENT) + + for action in actions_element_list: + new_action = self._load_xml_component(action) + + reformed_actions_list.append(new_action) + + return reformed_actions_list + + def _load_xml_states(self, states_elem): + """ + Takes in a States element and fleshes out a complete list of State + objects. + + @param states_elem An XML Element that represents a list of States + """ + reformed_state_list = [] + # item(0) because there is always only one tag in the xml file + # so states_elem should always contain only one element + states_element_list = states_elem.item(0).getElementsByTagName("State") + + for state in states_element_list: + stateName = state.getAttribute("Name") + # Using item 0 in the list because there is always only one + # Actions and EventFilterList element per State node. + actions_list = self._load_xml_actions(state.getElementsByTagName("Actions")[0]) + event_filters_list = self._load_xml_event_filters(state.getElementsByTagName("EventFiltersList")[0]) + reformed_state_list.append(State(stateName, actions_list, event_filters_list)) + + return reformed_state_list + + def _load_xml_fsm(self, fsm_elem): + """ + Takes in an XML element representing an FSM and returns the fully + crafted FSM. + + @param fsm_elem The XML element that describes a FSM + """ + # Load the FSM's name and start state's name + fsm_name = fsm_elem.getAttribute("Name") + + fsm_start_state_name = None + try: + fsm_start_state_name = fsm_elem.getAttribute("StartStateName") + except: + pass + + fsm = FiniteStateMachine(fsm_name, start_state_name=fsm_start_state_name) + + # Load the states + states = self._load_xml_states(fsm_elem.getElementsByTagName("States")) + for state in states: + fsm.add_state(state) + + # Load the actions on this FSM + actions = self._load_xml_actions(fsm_elem.getElementsByTagName("FSMActions")[0]) + for action in actions: + fsm.add_action(action) + + # Load the event filters + events = self._load_xml_event_filters(fsm_elem.getElementsByTagName("EventFiltersList")[0]) + for event in events: + fsm.add_event_filter(event) + + return fsm + + + def load_fsm(self, guid): + """ + Load fsm from xml file whose .ini file guid match argument guid. + """ + # Fetch the directory (if any) + tutorial_dir = self._find_tutorial_dir_with_guid(guid) + + # Open the XML file + tutorial_file = os.path.join(tutorial_dir, TUTORIAL_FILENAME) + + xml_dom = xml.dom.minidom.parse(tutorial_file) + + fsm_elem = xml_dom.getElementsByTagName("FSM")[0] + + return self._load_xml_fsm(fsm_elem) + + +class TutorialBundler(object): + """ + This class provide the various data handling methods useable by the tutorial + editor. + """ + + def __init__(self,generated_guid = None): + """ + Tutorial_bundler constructor. If a GUID is given in the parameter, the + Tutorial_bundler object will be associated with it. If no GUID is given, + a new GUID will be generated, + """ + + self.Guid = generated_guid or str(uuid.uuid1()) + + #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) + if os.path.isfile(store_path): + self.Path = os.path.dirname(store_path) + else: + #Bundle store + bundle_path = os.path.join(_get_bundle_root(), 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: + #Create the folder, any failure will go through to the caller for now + store_path = os.path.join(_get_store_root(), self.Guid) + os.makedirs(store_path) + self.Path = store_path + + def write_metadata_file(self, tutorial): + """ + Write metadata to the property file. + @param tutorial Tutorial for which to write metadata + """ + #Create the Config Object and populate it + cfg = SafeConfigParser() + cfg.add_section(INI_METADATA_SECTION) + cfg.set(INI_METADATA_SECTION, INI_GUID_PROPERTY, self.Guid) + 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'], + os.environ['SUGAR_BUNDLE_VERSION']) + + #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. + """ + + store_root = _get_store_root() + bundle_root = _get_bundle_root() + + config = SafeConfigParser() + path = None + + logging.debug("************ Path of store_root folder of activity : " \ + + store_root) + + # iterate in each GUID subfolder + for dir in os.listdir(store_root): + + # 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 + + logging.debug("************ Path of bundle_root folder of activity : " \ + + bundle_root) + + + # iterate in each GUID subfolder + for dir in os.listdir(bundle_root): + + # 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): + + """ + Save fsm to disk. If a GUID parameter is provided, the existing GUID is + located in the .ini files in the store root and bundle root and + the corresponding FSM is/are created or overwritten. If the GUID is not + found, an exception occur. + """ + + config = SafeConfigParser() + + serializer = XMLSerializer() + path = os.path.join(self.Path, "meta.ini") + config.read(path) + 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): + """ + Add ressources to metadata. + """ + raise NotImplementedError("add_resources not implemented") -- cgit v0.9.1