epyt-flow 0.1.0__py3-none-any.whl

epyt_flow/rest_api/__init__.py

@@ -0,0 +1,4 @@
+"""
+This module contains a server providing a REST API for interacting with EPyT-Flow.
+"""
+from .server import RestApiService

epyt_flow/rest_api/base_handler.py

@@ -0,0 +1,70 @@
+"""
+This module provides a base handler with some useful methods for all REST API handlers.
+"""
+from typing import Any
+import falcon
+
+from ..serialization import my_load_from_json, my_to_json
+
+
+class BaseHandler():
+    """
+    Base class for all REST API handlers.
+    """
+    def send_invalid_resource_id_error(self, resp: falcon.Response) -> None:
+        """
+        Sends an error that th given resource ID (e.g. scenario ID, or SCADA data ID) is invalid.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        """
+        resp.status = falcon.HTTP_BAD_REQUEST
+        resp.data = "Invalid resource ID".encode()
+
+    def send_json_parsing_error(self, resp: falcon.Response) -> None:
+        """
+        Sends an error that the JSON parsing failed.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        """
+        resp.status = falcon.HTTP_BAD_REQUEST
+        resp.data = "Failed to parse JSON".encode()
+
+    def load_json_data_from_request(self, req: falcon.Request) -> Any:
+        """
+        Loads/Parses an object from given JSON data.
+
+        Parameters
+        ----------
+        req : `falcon.Request`
+            Request instance.
+
+        Returns
+        -------
+        `Any`
+            Loaded object.
+        """
+        try:
+            return my_load_from_json(req.bounded_stream.read())
+        except Exception:
+            return None
+
+    def send_json_response(self, resp: falcon.Response, data: Any) -> None:
+        """
+        Sends a JSON response.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data : `Any`
+            Data to be sent.
+        """
+        resp.content_type = falcon.MEDIA_JSON
+        resp.status = falcon.HTTP_200
+        resp.data = my_to_json(data).encode()

epyt_flow/rest_api/res_manager.py

@@ -0,0 +1,95 @@
+"""
+This module contains a class for managing recourses such as scenarios or SCADA data.
+"""
+from typing import Any
+import uuid
+
+
+class ResourceManager():
+    """
+    Class implementing a simple resource manager where resources are associated with UUIDs.
+    """
+    def __init__(self):
+        self.__resources = {}
+
+    def __create_uuid(self) -> str:
+        return str(uuid.uuid4())
+
+    def validate_uuid(self, item_uuid: str) -> bool:
+        """
+        Validates a given UUID -- i.e. checks if there is a resource associated with the given UUID.
+
+        Parameters
+        ----------
+        item_uuid : `str`
+            UUID of the item.
+
+        Returns
+        -------
+        `bool`
+            True if the given UUID is valid, False otherwise.
+        """
+        return item_uuid in self.__resources
+
+    def create_new_item(self, item: Any) -> str:
+        """
+        Adds a new item to the resource manager.
+
+        Parameters
+        ----------
+        item : `Any`
+            Item to be added.
+
+        Returns
+        -------
+        `str`
+            UUID of the new item.
+        """
+        new_item_uuid = self.__create_uuid()
+        self.__resources[new_item_uuid] = item
+
+        return new_item_uuid
+
+    def get(self, item_uuid: str) -> Any:
+        """
+        Gets the item associated with a given UUID.
+
+        Parameters
+        ----------
+        item_uuid : `str`
+            UUID of the item.
+
+        Returns
+        -------
+        `Any`
+            Resource item.
+        """
+        if item_uuid not in self.__resources:
+            raise ValueError(f"Invalid UUID '{item_uuid}'")
+
+        return self.__resources[item_uuid]
+
+    def close_item(self, item: Any):
+        """
+        Closes a given resource item -- i.e. all clean-up logic for an item should be called here.
+
+        Parameters
+        ----------
+        item : `Any`
+            Resource item.
+        """
+
+    def remove(self, item_uuid: str) -> None:
+        """
+        Removes the scenario associated with a given UUID
+
+        Parameters
+        ----------
+        item_uuid : `str`
+            UUID of the item.
+        """
+        if item_uuid not in self.__resources:
+            raise ValueError(f"Invalid UUID '{item_uuid}'")
+
+        self.close_item(self.__resources[item_uuid])
+        del self.__resources[item_uuid]

epyt_flow/rest_api/scada_data_handler.py

@@ -0,0 +1,476 @@
+"""
+The module provides all handlers for SCADA data requests.
+"""
+import warnings
+import falcon
+
+from .base_handler import BaseHandler
+from .res_manager import ResourceManager
+from ..simulation import SensorConfig, SensorFault
+
+
+class ScadaDataManager(ResourceManager):
+    """
+    Class for managing SCADA data.
+    """
+
+
+class ScadaDataBaseHandler(BaseHandler):
+    """
+    Base class for all handlers concerning SCADA data.
+
+    Parameters
+    ----------
+    scada_data_mgr : `~epyt_flow.rest_api.scenario_handler.ScadaDataBaseHandler`
+        SCADA data manager.
+    """
+    def __init__(self, scada_data_mgr: ScadaDataManager):
+        self.scada_data_mgr = scada_data_mgr
+
+
+class ScadaDataRemoveHandler(ScadaDataBaseHandler):
+    """
+    Class for handling a DELETE request for a given SCADA data instance.
+    """
+    def on_delete(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Deletes a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data instance.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            self.scada_data_mgr.remove(data_id)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataSensorConfigHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET and POST requests for the sensor configuration
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the sensor configuration of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            my_sensor_config = self.scada_data_mgr.get(data_id).sensor_config
+            self.send_json_response(resp, my_sensor_config)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+    def on_post(self, req: falcon.Request, resp: falcon.Response, data_id: str) -> None:
+        """
+        Sets the sensor configuration of a given SCADA data instance.
+
+        Parameters
+        ----------
+        req : `falcon.Request`
+            Request instance.
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            sensor_config = self.load_json_data_from_request(req)
+            if not isinstance(sensor_config, SensorConfig):
+                self.send_json_parsing_error(resp)
+                return
+
+            self.scada_data_mgr.get(data_id).sensor_config = sensor_config
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataSensorFaultsHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET and POST requests concerning sensor faults in a
+    given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets all sensor faults of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            sensor_faults = self.scada_data_mgr.get(data_id).sensor_faults
+            self.send_json_response(resp, sensor_faults)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+    def on_post(self, req: falcon.Request, resp: falcon.Response, data_id: str) -> None:
+        """
+        Sets (i.e. overrides) the sensor faults in a given SCADA data instance.
+
+        Parameters
+        ----------
+        req : `falcon.Request`
+            Request instance.
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            sensor_faults = self.load_json_data_from_request(req)
+            if not isinstance(sensor_faults, list) or \
+                    any(not isinstance(e, SensorFault) for e in sensor_faults):
+                self.send_json_parsing_error(resp)
+                return
+
+            self.scada_data_mgr.get(data_id).sensor_faults = sensor_faults
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataPressuresHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the pressure sensor readings of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the pressure sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_pressures = self.scada_data_mgr.get(data_id).get_data_pressures().tolist()
+            self.send_json_response(resp, data_pressures)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataFlowsHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the flow sensor readings of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the flow sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_flows = self.scada_data_mgr.get(data_id).get_data_flows().tolist()
+            self.send_json_response(resp, data_flows)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataDemandsHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the demand sensor readings of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the demand sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_demands = self.scada_data_mgr.get(data_id).get_data_demands().tolist()
+            self.send_json_response(resp, data_demands)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataValveStatesHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the valve state sensor readings
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the valve state sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_demands = self.scada_data_mgr.get(data_id).get_data_valves_state().tolist()
+            self.send_json_response(resp, data_demands)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataPumpStatesHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the pump state sensor readings
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the pump state sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_demands = self.scada_data_mgr.get(data_id).get_data_pumps_state().tolist()
+            self.send_json_response(resp, data_demands)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataTankVolumesHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the tank volume sensor readings
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the tank volume sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_demands = self.scada_data_mgr.get(data_id).get_data_tanks_water_volume().tolist()
+            self.send_json_response(resp, data_demands)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataNodesQualityHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the node quality sensor readings
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the node quality sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_nodes_quality = self.scada_data_mgr.get(data_id).get_data_nodes_quality().tolist()
+            self.send_json_response(resp, data_nodes_quality)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataLinksQualityHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the link quality sensor readings
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the link/pipe quality sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_links_quality = self.scada_data_mgr.get(data_id).get_data_links_quality().tolist()
+            self.send_json_response(resp, data_links_quality)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataNodeBulkSpeciesHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the bulk species node concentration sensor readings
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the bulk species node concentrations sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_conc = self.scada_data_mgr.get(data_id).\
+                get_data_bulk_species_node_concentration().tolist()
+            self.send_json_response(resp, data_conc)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataLinkBulkSpeciesHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the bulk species link/pipe concentration sensor readings
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the bulk species link/pipe concentrations sensor readings of a
+        given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_conc = self.scada_data_mgr.get(data_id).\
+                get_data_bulk_species_link_concentration().tolist()
+            self.send_json_response(resp, data_conc)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR
+
+
+class ScadaDataSurfaceSpeciesHandler(ScadaDataBaseHandler):
+    """
+    Class for handling GET requests for the surface species concentration sensor readings
+    of a given SCADA data instance.
+    """
+    def on_get(self, _, resp: falcon.Response, data_id: str) -> None:
+        """
+        Gets the surface species concentrations sensor readings of a given SCADA data instance.
+
+        Parameters
+        ----------
+        resp : `falcon.Response`
+            Response instance.
+        data_id : `str`
+            UUID of the SCADA data.
+        """
+        try:
+            if self.scada_data_mgr.validate_uuid(data_id) is False:
+                self.send_invalid_resource_id_error(resp)
+                return
+
+            data_links_quality = self.scada_data_mgr.get(data_id).\
+                get_data_surface_species_concentration().tolist()
+            self.send_json_response(resp, data_links_quality)
+        except Exception as ex:
+            warnings.warn(str(ex))
+            resp.status = falcon.HTTP_INTERNAL_SERVER_ERROR