From c745023137b7a6d84ac5eb37bde6c5a363767256 Mon Sep 17 00:00:00 2001 From: erick Date: Tue, 27 Oct 2009 03:19:16 +0000 Subject: Updated interface for Tutorial, Started writing tests to Tutorial --- (limited to 'tutorius/tutorial.py') diff --git a/tutorius/tutorial.py b/tutorius/tutorial.py index a4da092..a902201 100644 --- a/tutorius/tutorial.py +++ b/tutorius/tutorial.py @@ -7,19 +7,24 @@ class Tutorial(object): _INIT = "INIT" _END = "END" + _INITIAL_TRANSITION_NAME = "Transition1" + _AUTOMATIC_TRANSITION_EVENT = "automatic" def __init__(self, name, state_dict=None): """ The constructor for the Tutorial. By default, the tutorial contains only an initial state and an end state. - The initial state doesn't contain any action or transition. - The end state doesn't contain any action either. + The initial state doesn't contain any action but it contains + a single automatic transition between the initial state and the + end state, named _INITIAL_TRANSITION. + The end state doesn't contain any action nor transition. If state_dict is provided, a valid initial state and an end state must be provided. @param name The name of the tutorial @param state_dict optional, a valid dictionary of states + @raise InvalidStateDictionary """ self.name = name @@ -54,13 +59,13 @@ class Tutorial(object): initialized with the action list and transition list and a new unique name is returned for this state. - The action is added using add_action. + The actions are added using add_action. - The transitions is added using add_transition. + The transitions are added using add_transition. @param action_list The list of valid actions for this state @param transition_list The list of valid transitions - @return string unique name for this state + @return unique name for this state """ name = self._generate_unique_state_name() @@ -162,47 +167,155 @@ class Tutorial(object): pointed to this one to the next state and remove all the unreachable states recursively. + All but the INIT and END states can be deleted. + @param state_name The name of the state to remove + @raise StateDeletionError when trying to delete the INIT or the END state """ pass - def get_actions(self, state_name): + def get_action_dict(self, state_name=None): """ + Returns a dictionary of all actions for a specific state. + If no state_name is provided, returns an action dictionary + containing actions for all states. + @param state_name The name of the state to list actions from - @return A list of actions for state_name + @return A dictionary of actions with action_name as key and action as value for state_name + @raise NameError if state_name doesn't exist """ pass - def get_events(self, state_name): + def get_transition_dict(self, state_name=None): """ + Returns a dictionary of all actions for a specific state. + If no state_name is provided, returns an action dictionary + containing actions for all states. + @param state_name The name of the state to list actions from - @return A list of events for state_name + @return A dictionary of transitions with transition_name as key and transition as value for state_name + @raise NameError if state_name doesn't exist + """ + pass + + def get_state_dict(self): + """ + @return A dictionary of all the states in the tutorial with state_name as key and state as value """ pass - def get_following_states(self, state_name): + def get_following_states_dict(self, state_name): """ - Returns a tuple of the names of the states that point to the given - state. If there is no such state, the function raises a KeyError. + Returns a dictionary of the states that are immediately reachable from + a specific state. - @param state_name The name of the state to analyse - @raise KeyError When there is no state by this name in the FSM + @param state_name The name of the state + @raise NameError if state_name doesn't exist """ pass - def get_previous_states(self, state_name): + def get_previous_states_dict(self, state_name): """ - Returns a tuple of the names of the state that can transition to - the given state. If there is no such state, the function raises a - KeyError. + Returns a dictionary of the states that can transition to a + specific state. - @param state_name The name of the state that the returned states might - transition to. - @raise KeyError When there is no state by this name in the FSM + @param state_name The name of the state + @raise NameError if state_name doesn't exist """ pass + # Convenience methods for common tutorial manipulations + def add_state_before(self, state_name, action_list=[], event_list=[]): + """ + Add a new state just before another state state_name. All transitions + going to state_name are updated to end on the new state and all + events will be converted to transitions ending on state_name. + + When event_list is empty, an automatic transition to state_name + will be added to maintain consistency. + + @param state_name The name of the state that will be preceded by the + new state + @param action_list The list of valid actions for this state + @param event_list The list of events that will be converted to transitions to state_name + @return unique name for this state + @raise NameError if state_name doesn't exist + """ + pass + + # Callback mecanism to allow automatic change notification when + # the tutorial is modified + def register_action_added_cb(self, cb): + """ + Register a function cb that will be called when any action from + the tutorial is added. + + cb should be of the form: + + cb(action_name, new_action) where: + action_name is the unique name of the action that was added + new_action is the new action + + @param cb The callback function to be called + @raise InvalidCallbackFunction if the callback has less or more than + 2 arguments + """ + pass + + def register_action_updated_cb(self, cb): + """ + Register a function cb that will be called when any action from + the tutorial is updated. + + cb should be of the form: + + cb(action_name, new_action) where: + action_name is the unique name of the action that has changed + new_action is the new action that replaces the old one + + @param cb The callback function to be called + @raise InvalidCallbackFunction if the callback has less or more than + 2 arguments + """ + pass + + def register_action_deleted_cb(self, cb): + """ + Register a function cb that will be called when any action from + the tutorial is deleted. + + cb should be of the form: + + cb(action_name, old_action) where: + action_name is the unique name of the action that was deleted + old_action is the new action that replaces the old one + + @param cb The callback function to be called + @raise InvalidCallbackFunction if the callback has less or more than + 2 arguments + """ + pass + + def register_transition_updated_cb(self, cb): + """ + Register a function cb that will be called when any transition from + the tutorial is updated. + + cb should be of the form: + + cb(transition_name, new_transition) where: + transition_name is the unique name of the transition + that has changed + new_transition is the new transition that replaces the old one + + @param cb The callback function to be called + @raise InvalidCallbackFunction if the callback has less or more than + 2 arguments + """ + pass + + # Validation to assert precondition def _validate_action(self, action): """ Validate that an action conforms to what we expect, @@ -465,3 +578,15 @@ class TransitionAlreadyExists(Exception): pass +class InvalidStateDictionary(Exception): + """ + Raised when an initialization dictionary could not be used to initialize + a tutorial + """ + pass + +class StateDeletionError(Exception): + """ + Raised when trying to delete an INIT or an END state from a tutorial + """ + pass -- cgit v0.9.1