Web   ·   Wiki   ·   Activities   ·   Blog   ·   Lists   ·   Chat   ·   Meeting   ·   Bugs   ·   Git   ·   Translate   ·   Archive   ·   People   ·   Donate
summaryrefslogtreecommitdiffstats
path: root/tutorius/bundler.py
diff options
context:
space:
mode:
authorSimon Poirier <simpoir@gmail.com>2009-07-11 21:39:46 (GMT)
committer Simon Poirier <simpoir@gmail.com>2009-07-11 22:00:30 (GMT)
commit0c3f127c86af818d260966d2292b199757087157 (patch)
tree62cf941aef5bde83641a17ec492e03d0ecb17386 /tutorius/bundler.py
parent9fafb49af210e956d43d6a00106558d1a00d13df (diff)
repackage
Diffstat (limited to 'tutorius/bundler.py')
-rw-r--r--tutorius/bundler.py556
1 files changed, 556 insertions, 0 deletions
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 <savard.jean.christophe@gmail.com>
+#
+# 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 <States> 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")