Merge pull request #27 from niclabs/feat-numpydoc

Numpy documentation of SCHC handlers package

fragmentation_layer/code/schc_handlers/schc_gateway_handler.py

@@ -11,8 +11,27 @@
 
 
 class SCHCGatewayHandler(SCHCHandler):
+    """
+    SCHC Gateway Handler
+    To be used as an API on Gateway side of communication
+
+    Attributes
+    ----------
+    callback_creator : Callable
+        A function to be used on reassembled message
+    """
 
     def __init__(self, protocol, mtu, on_receive_callback=None):
+        """
+        Constructor
+
+        Parameters
+        ----------
+        protocol
+        mtu
+        on_receive_callback : Callable
+            A function to be used when message is reassembled
+        """
         super().__init__(protocol, mtu)
         if on_receive_callback:
             used_callback = on_receive_callback
@@ -29,13 +48,48 @@ def after_reassembly_processing(msg_bytes):
         self.callback_creator = create_after_processing_callback
 
     def send_package(self, packet):
+        """
+        Load package to send
+
+        Parameters
+        ----------
+        packet : bytes
+            Packet to be fragmented
+
+        Returns
+        -------
+        None
+        Parameters
+        ----------
+        packet
+
+        Returns
+        -------
+
+        """
         if self.__protocol__.id == SCHCProtocol.LoRaWAN:
             from schc_machines.lorawan import AckAlwaysSender
             self.assign_session(LoRaWAN.ACK_ALWAYS, None, AckAlwaysSender(LoRaWAN(LoRaWAN.ACK_ALWAYS), packet))
         else:
             raise NotImplementedError("Just LoRaWAN implemented")
 
     def receive(self, rule_id, dtag, message):
+        """
+        Defines behaviour after receiving a message
+
+        Parameters
+        ----------
+        rule_id : int
+            Rule id of received message
+        dtag : int or None
+            DTag of received message
+        message : bytes
+            Message receive
+
+        Returns
+        -------
+        None
+        """
         if self.__protocol__.id == SCHCProtocol.LoRaWAN:
             if rule_id == LoRaWAN.ACK_ON_ERROR:
                 # message received
@@ -54,6 +108,25 @@ def receive(self, rule_id, dtag, message):
             raise NotImplementedError("Just LoRaWAN implemented")
 
     def handle(self, message, f_port=None, url=None, dev_id=None):
+        """
+        Handles a reception of SCHCMessages
+
+        Parameters
+        ----------
+        message : bytes
+            A message received
+        f_port : int, optional
+            In case of using LoRaWAN, rule id to handled message
+        url : str, optional
+            In case of using LoRaWAN, url to send answer
+        dev_id : str, optional
+            In case of using LoRaWAN, unique identifier of device
+            that sent the received message
+
+        Returns
+        -------
+        None
+        """
         if self.__protocol__.id == SCHCProtocol.LoRaWAN:
             r, d = self.identify_session_from_message(message, f_port)
             self.receive(r, d, bytes([f_port]) + message)
@@ -72,6 +145,23 @@ def handle(self, message, f_port=None, url=None, dev_id=None):
             r = requests.post(url, data=json.dumps(post_obj), headers={'content-type': 'application/json'})
 
     def generate_message(self, rule_id, dtag, mtu=512):
+        """
+        Generates a message to response
+
+        Parameters
+        ----------
+        rule_id : int
+            Rule id to identify session
+        dtag : int
+            Dtag to identify session
+        mtu : mtu, optional
+            MTU to use. Default 512 bytes
+
+        Returns
+        -------
+        bytes
+            Response to be send as bytes
+        """
         message = self.__sessions__[rule_id][dtag].generate_message(mtu)
         if message is None:
             return message

fragmentation_layer/code/schc_handlers/schc_handler.py

@@ -6,13 +6,59 @@
 
 # TODO: 
 class SCHCHandler:
+    """
+    SCHC Handler super class
+    Define functions and interface of Node and Gateway concrete class
 
+    Attributes
+    ----------
+    __protocol__ : SCHCProtocol
+        Protocol to be use
+    __sessions__ : Dict[int, Dict[int, SCHCFiniteStateMachine]]
+        A dictionary with rule_id and DTag assigned to a SCGHCFiniteStateMachine
+    __mtu__ : int
+        MTU to use
+
+    See Also
+    --------
+    SCHCFiniteStateMachine
+    """
     def __init__(self, protocol, mtu):
+        """
+        Constructor
+
+        Parameters
+        ----------
+        protocol : int
+            Number indicating SCHCProtocol to use
+        mtu : int
+            MTU to use
+
+        See Also
+        --------
+        SCHCProtocol
+        """
         self.__protocol__ = get_protocol(protocol)
         self.__sessions__ = dict()
         self.__mtu__ = mtu
 
     def identify_session_from_message(self, message, f_port=None):
+        """
+        Identifies the session to use according to protocol and message
+
+        Parameters
+        ----------
+        message : bytes
+            A bytes message
+        f_port : int, optional
+            In case of using LoRaWAN, rule id to use
+
+        Returns
+        -------
+        Tuple[int, int]
+            Rule id and Dtag that are going to be use to find
+            session (and SCHCFiniteStateMachine associated)
+        """
         if self.__protocol__.id == SCHCProtocol.LoRaWAN:
             rule_id = f_port
         else:
@@ -27,12 +73,59 @@ def identify_session_from_message(self, message, f_port=None):
         return rule_id, dtag
 
     def send_package(self, packet):
+        """
+        To be implemented by concrete class
+        Load package to send
+
+        Parameters
+        ----------
+        packet : bytes
+            Packet to be fragmented
+
+        Returns
+        -------
+        None
+        """
         return
 
     def receive(self, rule_id, dtag, message):
+        """
+        To be implemented by concrete class
+        Defines behaviour after receiving a message
+
+        Parameters
+        ----------
+        rule_id : int
+            Rule id of received message
+        dtag : int or None
+            DTag of received message
+        message : bytes
+            Message receive
+
+        Returns
+        -------
+        None
+        """
         return
 
     def assign_session(self, rule_id, dtag, machine):
+        """
+        Assigns a SCHCFiniteStateMachine (machine) to the corresponding
+        rule id and dtag
+
+        Parameters
+        ----------
+        rule_id : int
+            Rule id defining mode
+        dtag : int
+            DTag to differentiates parallel packets
+        machine : SCHCFiniteStateMachine
+            Finite State Machine defining behaviour of fragmentation
+
+        Returns
+        -------
+        None, alter self.__session__
+        """
         if rule_id not in self.__sessions__.keys():
             self.__sessions__[rule_id] = dict()
         if dtag not in self.__sessions__[rule_id].keys() or self.__sessions__[rule_id][dtag].is_active() == False:

fragmentation_layer/code/schc_handlers/schc_node_handler.py

@@ -5,18 +5,63 @@
 
 
 class SCHCNodeHandler(SCHCHandler):
+    """
+    SCHC Node Handler
+    Concrete class to be used as API for sending messages
+    using SCHC Protocols on a Node
+    """
 
     def __init__(self, protocol, mtu):
+        """
+        Constructor
+
+        Parameters
+        ----------
+        protocol
+        mtu
+
+        See Also
+        --------
+        SCHCHandler
+        """
         super().__init__(protocol, mtu)
 
     def send_package(self, packet):
+        """
+        Load package to send
+
+        Parameters
+        ----------
+        packet : bytes
+            Packet to be fragmented
+
+        Returns
+        -------
+        None
+        """
         if self.__protocol__.id == SCHCProtocol.LoRaWAN:
             from schc_machines.lorawan import AckOnErrorSender
             self.assign_session(LoRaWAN.ACK_ON_ERROR, None, AckOnErrorSender(LoRaWAN(LoRaWAN.ACK_ON_ERROR), packet))
         else:
             raise NotImplementedError("Just LoRaWAN implemented")
 
     def receive(self, rule_id, dtag, message):
+        """
+        Defines behaviour after receiving a message
+
+        Parameters
+        ----------
+        rule_id : int
+            Rule id of received message
+        dtag : int or None
+            DTag of received message
+        message : bytes
+            Message receive
+
+        Returns
+        -------
+        None
+        """
         if self.__protocol__.id == SCHCProtocol.LoRaWAN:
             if rule_id == LoRaWAN.ACK_ALWAYS:
                 # message received
@@ -33,6 +78,19 @@ def receive(self, rule_id, dtag, message):
             raise NotImplementedError("Just LoRaWAN implemented")
 
     def start(self, s):
+        """
+        Starts communication, by separating message in fragments
+        and send them to Gateway
+
+        Parameters
+        ----------
+        s : socket
+            A socket
+
+        Returns
+        -------
+        None
+        """
         while True:
             for rule_id in self.__sessions__.keys():
                 for dtag in self.__sessions__[rule_id].keys():