Browse Source

[Doc] First Draft of docstrings

monf 8 years ago
parent
commit
8e51c11274

+ 86 - 5
core/ConfigurationManager/BrainLoader.py

@@ -16,11 +16,30 @@ logger = logging.getLogger("kalliope")
 
 class BrainLoader(object):
 
+    """
+        This Class is used to get the brain YAML and the Brain as an object
+
+    """
+
     def __init__(self):
         pass
 
     @classmethod
     def get_yaml_config(cls, file_path=None):
+        """
+
+        Class Methods which loads default or the provided YAML file and return it as a String
+
+        :param file_path: the brain file path to load
+        :type file_path: String
+        :return: The loaded brain YAML
+        :rtype: String
+
+        :Example:
+            brain_yaml = BrainLoader.get_yaml_config(/var/tmp/brain.yml)
+
+        .. warnings:: Class Method
+        """
         if file_path is None:
             brain_file_path = cls._get_root_brain_path()
         else:
@@ -30,9 +49,20 @@ class BrainLoader(object):
     @classmethod
     def get_brain(cls, file_path=None):
         """
-        return a brain object from YAML settings
-        :return: Brain object
+
+        Class Methods which loads default or the provided YAML file and return a Brain
+
+        :param file_path: the brain file path to load
+        :type file_path: String
+        :return: The loaded Brain
         :rtype: Brain
+
+        :Example:
+
+            brain = BrainLoader.get_brain(file_path="/var/tmp/brain.yml")
+
+        .. seealso:: Brain
+        .. warnings:: Class Method
         """
 
         # Instantiate a brain
@@ -70,10 +100,22 @@ class BrainLoader(object):
     @staticmethod
     def _get_neurons(neurons_dict):
         """
+
         Get a list of Neuron object from a neuron dict
-        :param neurons_dict:
-        :return:
+
+        :param neurons_dict: Neuron name or dictionary of Neuron_name/Neuron_parameters
+        :type neurons_dict: String or dict
+        :return: A list of Neurons
+        :rtype: List
+
+        :Example:
+
+            neurons = cls._get_neurons(synapses_dict["neurons"])
+
+        .. seealso:: Neuron
+        .. warnings:: Static and Private
         """
+
         neurons = list()
         for neuron_dict in neurons_dict:
             if isinstance(neuron_dict, dict):
@@ -96,6 +138,22 @@ class BrainLoader(object):
 
     @classmethod
     def _get_signals(cls, signals_dict):
+        """
+
+        Get a list of Signal object from a signals dict
+
+        :param signals_dict: Signal name or dictionary of Signal_name/Signal_parameters
+        :type signals_dict: String or dict
+        :return: A list of Event and/or Order
+        :rtype: List
+
+        :Example:
+
+            signals = cls._get_signals(synapses_dict["signals"])
+
+        .. seealso:: Event, Order
+        .. warnings:: Class method and Private
+        """
         # print signals_dict
         signals = list()
         for signal_dict in signals_dict:
@@ -108,7 +166,22 @@ class BrainLoader(object):
 
     @staticmethod
     def _get_event_or_order_from_dict(signal_or_event_dict):
+        """
+
+        The signal is either an Event or an Order
 
+        :param signal_or_event_dict: A dict of event or signal
+        :type signal_or_event_dict: dict
+        :return: The object corresponding to An Order or an Event
+        :rtype: An Order or an Event
+
+        :Example:
+
+            event_or_order = cls._get_event_or_order_from_dict(signal_dict)
+
+        .. seealso:: Event, Order
+        .. warnings:: Static method and Private
+        """
         if 'event' in signal_or_event_dict:
             # print "is event"
             event = signal_or_event_dict["event"]
@@ -123,9 +196,17 @@ class BrainLoader(object):
     @staticmethod
     def _get_root_brain_path():
         """
+
         Return the full path of the default brain file
-        :return:
+
+        :Example:
+
+            brain.brain_file = cls._get_root_brain_path()
+
+        .. raises:: IOError
+        .. warnings:: Static method and Private
         """
+
         # get current script directory path. We are in /an/unknown/path/kalliope/core/ConfigurationManager
         cur_script_directory = os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe())))
         # get parent dir. Now we are in /an/unknown/path/kalliope

+ 22 - 0
core/ConfigurationManager/ConfigurationChecker.py

@@ -41,11 +41,33 @@ class NotValidSynapseName(Exception):
 
 class ConfigurationChecker:
 
+    """
+
+        This Class provides all method to Check the configuration files are properly set up.
+    """
+
     def __init__(self):
         pass
 
     @staticmethod
     def check_synape_dict(synape_dict):
+        """
+
+        Return True if the provided dict is corresponding to a Synapse
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: the path to store the cache
+        :rtype: String
+
+        :Example:
+
+            ConfigurationChecker().check_synape_dict(synapses_dict):
+
+        .. seealso:: Synapse
+        .. raises:: NoSynapeName, InvalidSynapeName, NoSynapeNeurons, NoSynapeSignals
+        .. warnings:: Static and Public
+        """
 
         if 'name' not in synape_dict:
             raise NoSynapeName("The Synapse does not have a name: %s" % synape_dict)

+ 199 - 14
core/ConfigurationManager/SettingLoader.py

@@ -28,12 +28,31 @@ class SettingNotFound(Exception):
 
 
 class SettingLoader(object):
+    """
+        This Class is used to get the Settings YAML and the Settings as an object
+
+    """
 
     def __init__(self):
         pass
 
     @classmethod
     def get_yaml_config(cls, file_path=None):
+        """
+
+        Class Methods which loads default or the provided YAML file and return it as a String
+
+        :param file_path: the setting file path to load if None takes default
+        :type file_path: String
+        :return: The loaded settings YAML
+        :rtype: String
+
+        :Example:
+            settings_yaml = SettingLoader.get_yaml_config(/var/tmp/settings.yml)
+
+        .. warnings:: Class Method
+        """
+
         if file_path is None:
             file_path = FILE_NAME
         return YAMLLoader.get_config(file_path)
@@ -41,8 +60,20 @@ class SettingLoader(object):
     @classmethod
     def get_settings(cls, file_path=None):
         """
-        Return a Settings object from settings.yml file
-        :return:
+
+        Class Methods which loads default or the provided YAML file and return a Settings Object
+
+        :param file_path: the setting file path to load
+        :type file_path: String
+        :return: The loaded Settings
+        :rtype: Settings
+
+        :Example:
+
+            settings = SettingLoader.get_settings(file_path="/var/tmp/settings.yml")
+
+        .. seealso:: Settings
+        .. warnings:: Class Method
         """
 
         # create a new setting
@@ -81,6 +112,23 @@ class SettingLoader(object):
 
     @staticmethod
     def _get_default_speech_to_text(settings):
+        """
+
+        Get the default speech to text defined in the settings.yml file
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: the default speech to text
+        :rtype: String
+
+        :Example:
+
+            default_stt_name = cls._get_default_speech_to_text(settings)
+
+        .. seealso:: Stt
+        .. raises:: NullSettingException, SettingNotFound
+        .. warnings:: Static and Private
+        """
 
         try:
             default_speech_to_text = settings["default_speech_to_text"]
@@ -93,6 +141,24 @@ class SettingLoader(object):
 
     @staticmethod
     def _get_default_text_to_speech(settings):
+        """
+
+        Get the default text to speech defined in the settings.yml file
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: the default text to speech
+        :rtype: String
+
+        :Example:
+
+            default_tts_name = cls._get_default_text_to_speech(settings)
+
+        .. seealso:: Tts
+        .. raises:: NullSettingException, SettingNotFound
+        .. warnings:: Static and Private
+        """
+
         try:
             default_text_to_speech = settings["default_text_to_speech"]
             if default_text_to_speech is None:
@@ -104,6 +170,24 @@ class SettingLoader(object):
 
     @staticmethod
     def _get_default_trigger(settings):
+        """
+
+        Get the default trigger defined in the settings.yml file
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: the default trigger
+        :rtype: String
+
+        :Example:
+
+            default_trigger_name = cls._get_default_trigger(settings)
+
+        .. seealso:: Trigger
+        .. raises:: NullSettingException, SettingNotFound
+        .. warnings:: Static and Private
+        """
+
         try:
             default_trigger = settings["default_trigger"]
             if default_trigger is None:
@@ -116,14 +200,27 @@ class SettingLoader(object):
     @classmethod
     def _get_stts(cls, settings):
         """
+
         Return a list of stt object
-        :param settings: loaded settings file
+
+        :param settings: The YAML settings file
+        :type settings: String
         :return: List of Stt
+        :rtype: List
+
+        :Example:
+
+            stts = cls._get_stts(settings)
+
+        .. seealso:: Stt
+        .. raises:: SettingNotFound
+        .. warnings:: Class Method and Private
         """
+
         try:
             speechs_to_text_list = settings["speech_to_text"]
         except KeyError:
-            raise NullSettingException("speech_to_text settings not found")
+            raise SettingNotFound("speech_to_text settings not found")
 
         stts = list()
         for speechs_to_text_el in speechs_to_text_list:
@@ -143,10 +240,23 @@ class SettingLoader(object):
     @classmethod
     def _get_ttss(cls, settings):
         """
-        Return a list of Tts object
-        :param settings: loaded settings file
-        :return: List of Tts
+
+        Return a list of stt object
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: List of Ttss
+        :rtype: List
+
+        :Example:
+
+            ttss = cls._get_ttss(settings)
+
+        .. seealso:: Tts
+        .. raises:: SettingNotFound
+        .. warnings:: Class Method and Private
         """
+
         try:
             text_to_speech_list = settings["text_to_speech"]
         except KeyError, e:
@@ -170,10 +280,23 @@ class SettingLoader(object):
     @classmethod
     def _get_triggers(cls, settings):
         """
+
         Return a list of Trigger object
-        :param settings: loaded settings file
+
+        :param settings: The YAML settings file
+        :type settings: String
         :return: List of Trigger
+        :rtype: List
+
+        :Example:
+
+            triggers = cls._get_triggers(settings)
+
+        .. seealso:: Trigger
+        .. raises:: SettingNotFound
+        .. warnings:: Class Method and Private
         """
+
         try:
             triggers_list = settings["triggers"]
         except KeyError, e:
@@ -197,10 +320,23 @@ class SettingLoader(object):
     @classmethod
     def _get_random_wake_up_answers(cls, settings):
         """
-        return a list of string
-        :param settings:
-        :return:
+
+        Return a list of the wake up answers set up on the settings.yml file
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: List of wake up answers
+        :rtype: List of Strings
+
+        :Example:
+
+            wakeup = cls._get_random_wake_up_answers(settings)
+
+        .. seealso::
+        .. raises:: NullSettingException
+        .. warnings:: Class Method and Private
         """
+
         try:
             random_wake_up_answers_list = settings["random_wake_up_answers"]
         except KeyError:
@@ -216,10 +352,23 @@ class SettingLoader(object):
     @classmethod
     def _get_random_wake_up_sounds(cls, settings):
         """
-        return a list of string
-        :param settings:
-        :return: List of string
+
+        Return a list of the wake up sounds set up on the settings.yml file
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: List of wake up sounds
+        :rtype: List of Strings (paths)
+
+        :Example:
+
+            wakeup_sounds = cls._get_random_wake_up_sounds(settings)
+
+        .. seealso::
+        .. raises:: NullSettingException
+        .. warnings:: Class Method and Private
         """
+
         try:
             random_wake_up_sounds_list = settings["random_wake_up_sounds"]
         except KeyError:
@@ -234,6 +383,24 @@ class SettingLoader(object):
 
     @classmethod
     def _get_rest_api(cls, settings):
+        """
+
+        Return the settings of the RestApi
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: the RestApi object
+        :rtype: RestApi
+
+        :Example:
+
+            rest_api = cls._get_rest_api(settings)
+
+        .. seealso:: RestApi
+        .. raises:: SettingNotFound, NullSettingException, SettingInvalidException
+        .. warnings:: Class Method and Private
+        """
+
         try:
             rest_api = settings["rest_api"]
         except KeyError, e:
@@ -278,6 +445,24 @@ class SettingLoader(object):
 
     @classmethod
     def _get_cache_path(cls, settings):
+        """
+
+        Return the path where to store the cache
+
+        :param settings: The YAML settings file
+        :type settings: String
+        :return: the path to store the cache
+        :rtype: String
+
+        :Example:
+
+            cache_path = cls._get_cache_path(settings)
+
+        .. seealso::
+        .. raises:: SettingNotFound, NullSettingException, SettingInvalidException
+        .. warnings:: Class Method and Private
+        """
+
         try:
             cache_path = settings["cache_path"]
         except KeyError, e: