Explorar o código

[Doc] Docstrings of Models

monf %!s(int64=8) %!d(string=hai) anos
pai
achega
2f7736e2ef

+ 92 - 12
core/ConfigurationManager/ConfigurationChecker.py

@@ -53,12 +53,12 @@ class ConfigurationChecker:
     def check_synape_dict(synape_dict):
         """
 
-        Return True if the provided dict is corresponding to a Synapse
+        Return True if the provided dict is well corresponding to a Synapse
 
-        :param settings: The YAML settings file
-        :type settings: String
-        :return: the path to store the cache
-        :rtype: String
+        :param synape_dict: The synapse Dictionary
+        :type synape_dict: Dict
+        :return: True if synapse are ok
+        :rtype: Boolean
 
         :Example:
 
@@ -92,11 +92,24 @@ class ConfigurationChecker:
     @staticmethod
     def check_neuron_dict(neuron_dict):
         """
+
         Check received neuron dict is valid:
-        - neuron exist
-        :param neuron_dict:
-        :return:
+
+        :param neuron_dict: The neuron Dictionary
+        :type neuron_dict: Dict
+        :return: True if neuron is ok
+        :rtype: Boolean
+
+        :Example:
+
+            ConfigurationChecker().check_neuron_dict(neurons_dict):
+
+        .. seealso:: Synapse
+        .. raises:: ModuleNotFoundError
+        .. warnings:: Static and Public
         """
+
+
         def check_neuron_exist(neuron_name):
             package_name = "neurons"
             mod = __import__(package_name, fromlist=[neuron_name])
@@ -115,12 +128,48 @@ class ConfigurationChecker:
 
     @staticmethod
     def check_signal_dict(signal_dict):
+        """
+
+        Check received signal dictionary is valid:
+
+        :param signal_dict: The signal Dictionary
+        :type signal_dict: Dict
+        :return: True if signal are ok
+        :rtype: Boolean
+
+        :Example:
+
+            ConfigurationChecker().check_signal_dict(signal_dict):
+
+        .. seealso:: Order, Event
+        .. raises:: NoValidSignal
+        .. warnings:: Static and Public
+        """
+
         if ('event' not in signal_dict) and ('order' not in signal_dict):
             raise NoValidSignal("The signal is not an event or an order %s" % signal_dict)
         return True
 
     @staticmethod
     def check_event_dict(event_dict):
+        """
+
+        Check received event dictionary is valid:
+
+        :param event_dict: The event Dictionary
+        :type event_dict: Dict
+        :return: True if event are ok
+        :rtype: Boolean
+
+        :Example:
+
+            ConfigurationChecker().check_event_dict(event_dict):
+
+        .. seealso::  Event
+        .. raises:: NoEventPeriod
+        .. warnings:: Static and Public
+        """
+
         if event_dict is None:
             raise NoEventPeriod("Event must contain a period: %s" % event_dict)
 
@@ -128,6 +177,24 @@ class ConfigurationChecker:
 
     @staticmethod
     def check_order_dict(order_dict):
+        """
+
+        Check received order dictionary is valid:
+
+        :param order_dict: The Order Dict
+        :type order_dict: Dict
+        :return: True if event are ok
+        :rtype: Boolean
+
+        :Example:
+
+            ConfigurationChecker().check_order_dict(order_dict):
+
+        .. seealso::  Order
+        .. raises:: NoEventPeriod
+        .. warnings:: Static and Public
+        """
+
         if order_dict is not None:
             return True
         return False
@@ -135,12 +202,25 @@ class ConfigurationChecker:
     @staticmethod
     def check_synapes(synapses_list):
         """
+
         Check the synapse list is ok:
-         - No double same name
-        :param synapses_list:
-        :type synapses_list: list of Synapse
-        :return:
+            - No double same name
+
+        :param synapses_list: The Synapse List
+        :type synapses_list: List
+        :return: list of Synapse
+        :rtype: List
+
+        :Example:
+
+            ConfigurationChecker().check_synapes(order_dict):
+
+        .. seealso::  Synapse
+        .. raises:: MultipleSameSynapseName
+        .. warnings:: Static and Public
         """
+
+
         seen = set()
         for synapse in synapses_list:
             # convert ascii to UTF-8

+ 7 - 0
core/Models/Brain.py

@@ -3,6 +3,13 @@ from core.Models import Singleton
 
 @Singleton
 class Brain:
+    # TODO review the Singleton, should be Instantiate at the BrainLoader level
+    """
+
+        This Class is a Singleton Representing the Brain.yml file with synapse
+
+        .. note:: the is_loaded Boolean is True when the Brain has been properly loaded.
+    """
 
     def __init__(self, synapses=None, brain_file=None, brain_yaml=None):
         self.synapses = synapses

+ 16 - 0
core/Models/Event.py

@@ -1,4 +1,12 @@
 class Event(object):
+    """
+
+        This Class is representing an Event which is raised by when the System at some defined time.
+
+        .. note:: Events are based on the system crontab
+    """
+
+
     def __init__(self, period):
         self.period = period
 
@@ -7,6 +15,14 @@ class Event(object):
                                    self.period)
 
     def serialize(self):
+        """
+
+        This method allows to serialize in a proper way this object
+
+        :return: A dict of name / perio
+        :rtype: Dict
+        """
+
         return {
             'event': self.period
         }

+ 14 - 1
core/Models/Neuron.py

@@ -1,11 +1,24 @@
+class Neuron(object):
+    """
+
+        This Class is representing a Neuron which is corresponding to an action to perform.
+
+        .. note:: Neurons are defined in the brain file
+    """
 
 
-class Neuron(object):
     def __init__(self, name=None, parameters=None):
         self.name = name
         self.parameters = parameters
 
     def serialize(self):
+        """
+
+        This method allows to serialize in a proper way this object
+
+        :return: A dict of name and parameters
+        :rtype: Dict
+        """
         return {
             'name': self.name,
             'parameters': str(self.parameters)

+ 16 - 0
core/Models/Order.py

@@ -1,4 +1,12 @@
 class Order(object):
+    """
+
+        This Class is representing an Order which is raised by when an entry (Vocal/REST/ anything ...) is matching it.
+
+        .. note:: Order are defined in the brain file for each synapse.
+    """
+
+
     def __init__(self, sentence):
         self.sentence = sentence
 
@@ -6,6 +14,14 @@ class Order(object):
         return "%s: Sentence: %s" % (self.__class__.__name__, self.sentence)
 
     def serialize(self):
+        """
+
+        This method allows to serialize in a proper way this object
+
+        :return: A dict of order
+        :rtype: Dict
+        """
+
         return {
             'order': self.sentence
         }

+ 7 - 0
core/Models/RestAPI.py

@@ -1,4 +1,11 @@
 class RestAPI(object):
+    """
+
+        This Class is representing the rest API with all its configuration.
+
+    """
+
+
     def __init__(self, password_protected=None, login=None, password=None, active=None, port=None):
         """
 

+ 7 - 0
core/Models/Settings.py

@@ -3,6 +3,13 @@ from core.Models import Singleton
 
 @Singleton
 class Settings(object):
+    # TODO review the Singleton, should be Instantiate at the BrainLoader level
+    """
+
+        This Class is a Singleton Representing the settings.yml file with synapse
+
+        .. note:: the is_loaded Boolean is True when the Settings has been properly loaded.
+    """
     def __init__(self,
                  default_tts_name=None,
                  default_stt_name=None,

+ 2 - 0
core/Models/Singleton.py

@@ -1,5 +1,7 @@
 class Singleton:
     """
+    (From Stackoverflow : http://stackoverflow.com/questions/31875/is-there-a-simple-elegant-way-to-define-singletons-in-python)
+
     A non-thread-safe helper class to ease implementing singletons.
     This should be used as a decorator -- not a metaclass -- to the
     class that should be a singleton.

+ 7 - 1
core/Models/Stt.py

@@ -1,6 +1,12 @@
+class Stt(object):
 
+    """
+
+        This Class is representing a Speech To Text (STT) element with name and parameters
+
+        .. note:: must be defined in the settings.yml
+    """
 
-class Stt(object):
     def __init__(self, name=None, parameters=None):
         self.name = name
         self.parameters = parameters

+ 17 - 1
core/Models/Synapse.py

@@ -1,10 +1,26 @@
 class Synapse(object):
-    def __init__(self, name, neurons, signals):
+    """
+
+        This Class is representing a Synapse with its name, and a dict of Neurons and a dict of signals
+
+        .. note:: must be defined in the brain.yml
+    """
+
+
+    def __init__(self, name=None, neurons=None, signals=None):
         self.name = name
         self.neurons = neurons
         self.signals = signals
 
     def serialize(self):
+        """
+
+        This method allows to serialize in a proper way this object
+
+        :return: A dict of name, neurons, signals
+        :rtype: Dict
+        """
+
         return {
             'name': self.name,
             'neurons': [e.serialize() for e in self.neurons],

+ 8 - 1
core/Models/Trigger.py

@@ -1,6 +1,13 @@
+class Trigger(object):
+
+    """
+
+        This Class is representing a Trigger with its name and parameters
+
+        .. note:: must be defined in the settings.yml
+    """
 
 
-class Trigger(object):
     def __init__(self, name=None, parameters=None):
         self.name = name
         self.parameters = parameters

+ 7 - 1
core/Models/Tts.py

@@ -1,6 +1,12 @@
+class Tts(object):
+    """
+
+        This Class is representing a Text To Speech (TTS) with its name and parameters
+
+        .. note:: must be defined in the settings.yml
+    """
 
 
-class Tts(object):
     def __init__(self, name=None, parameters=None):
         self.name = name
         self.parameters = parameters