ML Streaming docstrings (#118)

* docstring for `RESTClientCommunicator` class added

* docstring for `RESTServerCommunicator` class added

* docstring for `DummyCompressor` class added

* docstring for `DummyEncryptor` class added

* docstring for `Compressor` +  `Encryptor` + `ClientCommunicator` + classes added

* docstring for `PymiloClient` class added

* docstring for `PymiloServer` class added

* tiny refactoring in `serialize_cfnode` function

* add module level docstrings + merge one line docstrings with their quotes

* add "." at the end of docstring descriptions

* docstrings fixes

* Fix docstring issues

* docstring feedbacks applied

* change `overload` to `overwrite`

Author: AHReccese

pymilo/streaming/communicator.py

@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+"""PyMilo RESTFull Communication Mediums."""
 import uvicorn
 import requests
 from fastapi import FastAPI, Request
@@ -6,8 +8,16 @@
 
 
 class RESTClientCommunicator(ClientCommunicator):
+    """Facilitate working with the communication medium from the client side for the REST protocol."""
 
     def __init__(self, server_url):
+        """
+        Initialize the Pymilo RESTClientCommunicator instance.
+
+        :param server_url: the url to which PyMilo Server listens
+        :type server_url: str
+        :return: an instance of the Pymilo RESTClientCommunicator class
+        """
         self._server_url = server_url
         self.session = requests.Session()
         retries = requests.adapters.Retry(
@@ -19,31 +29,65 @@ def __init__(self, server_url):
         self.session.mount('https://', requests.adapters.HTTPAdapter(max_retries=retries))
 
     def download(self, payload):
+        """
+        Request for the remote ML model to download.
+
+        :param payload: download request payload
+        :type payload: dict
+        :return: response of pymilo server
+        """
         return self.session.get(url=self._server_url + "/download/", json=payload, timeout=5)
 
     def upload(self, payload):
+        """
+        Upload the local ML model to the remote server.
+
+        :param payload: upload request payload
+        :type payload: dict
+        :return: response of pymilo server
+        """
         return self.session.post(url=self._server_url + "/upload/", json=payload, timeout=5)
 
     def attribute_call(self, payload):
+        """
+        Delegate the requested attribute call to the remote server.
+
+        :param payload: attribute call request payload
+        :type payload: dict
+        :return: response of pymilo server
+        """
         return self.session.post(url=self._server_url + "/attribute_call/", json=payload, timeout=5)
 
 
 
 class RESTServerCommunicator():
+    """Facilitate working with the communication medium from the server side for the REST protocol."""
 
     def __init__(
             self,
             ps,
             host: str = "127.0.0.1",
             port: int = 8000,
             ):
+        """
+        Initialize the Pymilo RESTServerCommunicator instance.
+
+        :param ps: reference to the PyMilo server
+        :type ps: pymilo.streaming.PymiloServer
+        :param host: the url to which PyMilo Server listens
+        :type host: str
+        :param port: the port to which PyMilo Server listens
+        :type port: int
+        :return: an instance of the Pymilo RESTServerCommunicator class
+        """
         self.app = FastAPI()
         self.host = host
         self.port = port
         self._ps = ps
         self.setup_routes()
 
     def setup_routes(self):
+        """Configure endpoints to handle RESTClientCommunicator requests."""
         class StandardPayload(BaseModel):
             client_id: str
             model_id: str
@@ -91,11 +135,19 @@ async def attribute_call(request: Request):
             }
 
     def parse(self, body):
+        """
+        Parse the compressed encrypted body of the request.
+
+        :param body: request body
+        :type body: str
+        :return: the extracted decrypted version
+        """
         return self._ps._compressor.extract(
             self._ps._encryptor.decrypt(
                 body
             )
         )
 
     def run(self):
+        """Run internal fastapi server."""
         uvicorn.run(self.app, host=self.host, port=self.port)

pymilo/streaming/compressor.py

@@ -1,12 +1,17 @@
+# -*- coding: utf-8 -*-
+"""Implementations of Compressor interface."""
 from .interfaces import Compressor
 
 
 class DummyCompressor(Compressor):
+    """A dummy implementation of the Compressor interface."""
 
     @staticmethod
     def compress(payload):
+        """Compress the given payload in a dummy way, simply just return it (no compression applied)."""
         return payload
 
     @staticmethod
     def extract(payload):
+        """Extract the given payload in a dummy way, simply just return it (no Extraction applied)."""
         return payload

pymilo/streaming/encryptor.py

@@ -1,12 +1,17 @@
+# -*- coding: utf-8 -*-
+"""Implementations of Encryptor interface."""
 from .interfaces import Encryptor
 
 
 class DummyEncryptor(Encryptor):
+    """A dummy implementation of the Encryptor interface."""
 
     @staticmethod
     def encrypt(payload):
+        """Encrypt the given payload in a dummy way, simply just return it (no encryption applied)."""
         return payload
 
     @staticmethod
     def decrypt(payload):
+        """Decrypt the given payload in a dummy way, simply just return it (no decryption applied)."""
         return payload

pymilo/streaming/interfaces.py

@@ -4,44 +4,94 @@
 
 
 class Compressor(ABC):
+    """
+    Compressor Interface.
+
+    Each Compressor has methods to compress the given payload or extract it back to the original one.
+    """
 
     @abstractmethod
     def compress(payload):
         """
+        Compress the given payload.
+
+        :param payload: payload to get compressed
+        :type payload: str
+        :return: the compressed version
         """
 
     @abstractmethod
     def extract(payload):
         """
+        Extract the given previously compressed payload.
+
+        :param payload: payload to get extracted
+        :type payload: str
+        :return: the extracted version
         """
 
 
 class Encryptor(ABC):
+    """
+    Encryptor Interface.
+
+    Each Encryptor has methods to encrypt the given payload or decrypt it back to the original one.
+    """
 
     @abstractmethod
     def encrypt(payload):
         """
+        Encrypt the given payload.
+
+        :param payload: payload to get encrypted
+        :type payload: str
+        :return: the encrypted version
         """
 
     @abstractmethod
     def decrypt(payload):
         """
+        Decrypt the given previously encrypted payload.
+
+        :param payload: payload to get decrypted
+        :type payload: str
+        :return: the decrypted version
         """
 
 
 class ClientCommunicator(ABC):
+    """
+    ClientCommunicator Interface.
+
+    Each ClientCommunicator has methods to upload the local ML model, download the remote ML model and delegate attribute call to the remote server.
+    """
 
     @abstractmethod
     def upload(self, payload):
         """
+        Upload the given payload to the remote server.
+
+        :param payload: request payload
+        :type payload: dict
+        :return: remote server response
         """
 
     @abstractmethod
     def download(self, payload):
         """
+        Download the remote ML model to local.
+
+        :param payload: request payload
+        :type payload: dict
+        :return: remote server response
         """
 
     @abstractmethod
     def attribute_call(self, payload):
         """
+        Execute an attribute call on the remote server.
+
+        :param payload: request payload
+        :type payload: dict
+        :return: remote server response
         """

pymilo/streaming/pymilo_client.py

@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+"""PyMiloClient for RESTFull Protocol."""
 from enum import Enum
 from .encryptor import DummyEncryptor
 from .compressor import DummyCompressor
@@ -14,6 +16,7 @@ class Mode(Enum):
 
 
 class PymiloClient:
+    """Facilitate working with the PyMilo server."""
 
     def __init__(
             self,
@@ -22,6 +25,19 @@ def __init__(
             server="http://127.0.0.1",
             port= 8000
             ):
+        """
+        Initialize the Pymilo PymiloClient instance.
+
+        :param model: the ML model PyMiloClient wrapped around
+        :type model: Any
+        :param mode: the mode in which PymiloClient should work, either LOCAL mode or DELEGATE
+        :type mode: str (LOCAL|DELEGATE)
+        :param server: the url to which PyMilo Server listens
+        :type server: str
+        :param port: the port to which PyMilo Server listens
+        :type port: int
+        :return: an instance of the Pymilo PymiloClient class
+        """
         self._client_id = "0x_client_id"
         self._model_id = "0x_model_id"
         self._model = model
@@ -32,12 +48,23 @@ def __init__(
             server_url="{}:{}".format(server, port)
         )
 
+
     def toggle_mode(self, mode=Mode.LOCAL):
+        """
+        Toggle the PyMiloClient mode, either from LOCAL to DELEGATE or vice versa.
+
+        :return: None
+        """
         if mode not in Mode.__members__.values():
             raise Exception("Invalid mode, the given mode should be either `LOCAL`[default] or `DELEGATE`.")
         self._mode = mode
 
     def download(self):
+        """
+        Request for the remote ML model to download.
+
+        :return: None
+        """
         response = self._communicator.download({
             "client_id": self._client_id,    
             "model_id": self._model_id
@@ -50,6 +77,11 @@ def download(self):
         print("Local model updated successfully.")
 
     def upload(self):
+        """
+        Upload the local ML model to the remote server.
+
+        :return: None
+        """
         response = self._communicator.upload({
             "client_id": self._client_id,    
             "model_id": self._model_id,
@@ -61,17 +93,25 @@ def upload(self):
             print("Local model upload failed.")
 
     def __getattr__(self, attribute):
+        """
+        Overwrite the __getattr__ default function to extract requested.
+
+            1. If self._mode is LOCAL, extract the requested from inner ML model and returns it
+            2. If self._mode is DELEGATE, returns a wrapper relayer which delegates the request to the remote server by execution
+
+        :return: Any
+        """
         if self._mode == Mode.LOCAL:
             if attribute in dir(self._model):
                 return getattr(self._model, attribute)
             else:
-                raise AttributeError("This attribute doesn't exist either in PymiloClient or the inner ML model.")
+                raise AttributeError("This attribute doesn't exist in either PymiloClient or the inner ML model.")
         elif self._mode == Mode.DELEGATE:
             gdst = GeneralDataStructureTransporter()
             def relayer(*args, **kwargs):
                 print(f"Method '{attribute}' called with args: {args} and kwargs: {kwargs}")
                 payload = {
-                    "client_id": self._client_id,                   
+                    "client_id": self._client_id,
                     "model_id": self._model_id,
                     'attribute': attribute,
                     'args': args,

pymilo/streaming/pymilo_server.py

@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+"""PyMiloServer for RESTFull protocol."""
 from ..pymilo_obj import Export, Import
 from .compressor import DummyCompressor
 from .encryptor import DummyEncryptor
@@ -6,21 +8,47 @@
 
 
 class PymiloServer:
+    """Facilitate streaming the ML models."""
 
     def __init__(self, port=8000):
+        """
+        Initialize the Pymilo PymiloServer instance.
+        
+        :param port: the port to which PyMiloServer listens
+        :type port: int
+        :return: an instance of the PymiloServer class
+        """
         self._model = None
         self._compressor = DummyCompressor()
         self._encryptor = DummyEncryptor()
         self._communicator = RESTServerCommunicator(ps=self, port=port)
-        self._communicator.run()
 
     def export_model(self):
+        """
+        Export the ML model to string json dump using PyMilo Export class.
+
+        :return: str
+        """
         return Export(self._model).to_json()
 
     def update_model(self, serialized_model):
+        """
+        Update the PyMilo Server's ML model.
+
+        :param serialized_model: the json dump of a pymilo export ml model
+        :type serialized_model: str
+        :return: None
+        """
         self._model = Import(file_adr=None, json_dump=serialized_model).to_model()
 
     def execute_model(self, request):
+        """
+        Execute the request attribute call from PyMilo Client.
+
+        :param request: request obj containing requested attribute to call with the associated args and kwargs
+        :type request: obj
+        :return: str | dict
+        """
         gdst = GeneralDataStructureTransporter()
         attribute = request.attribute
         retrieved_attribute = getattr(self._model, attribute, None)