zepben.ewb 1.0.0b1__py3-none-any.whl

zepben/ewb/database/sqlite/extensions/prepared_statement.py

@@ -0,0 +1,112 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+from logging import Logger
+from sqlite3 import Cursor
+from typing import Dict, Any, Optional, Callable
+
+from zepben.ewb.model.cim.iec61968.infiec61968.infcommon.ratio import Ratio
+
+
+class SqlException(Exception):
+    pass
+
+
+class PreparedStatement(object):
+    """
+    A class giving the same functionality as the JVM PreparedStatement with the JVM SDK extensions added.
+    """
+
+    def __init__(self, sql: str, cursor: Cursor):
+        self.sql: str = sql
+        self._cursor: Cursor = cursor
+
+        self._num_cols: int = self.sql.count('?')
+        self._values: Dict[int, Any] = dict()
+
+    def __str__(self):
+        return f"PreparedStatement[sql={self.sql}, values={self._values}]"
+
+    @property
+    def num_columns(self):
+        return self._num_cols
+
+    @property
+    def parameters(self):
+        """
+        Get the string representation of the current parameters set on this PreparedStatement.
+        '(unset)' means this index has not yet been set.
+        This function should be used for error handling and debugging only.
+
+        Returns the string representation of all parameters that have been set on this PreparedStatement, separated by commas.
+        """
+        pm = []
+        for i in range(1, self.num_columns + 1):
+            try:
+                pm.append(str(self._values[i]))
+            except KeyError:
+                pm.append("(unset)")
+        return ", ".join(pm)
+
+    def execute(self):
+        """
+        Execute this PreparedStatement using the given `cursor`.
+
+        Throws any exception possible from `cursor.execute`, typically `sqlite3.DatabaseError`
+        """
+        parameters = []
+        missing = []
+        for i in range(1, self.num_columns + 1):
+            try:
+                parameters.append(self._values[i])
+            except KeyError:
+                missing.append(str(i))
+
+        if missing:
+            raise SqlException(f"Missing values for indices {', '.join(missing)}. Ensure all ?'s have a corresponding value in the prepared statement.")
+
+        self._cursor.execute(self.sql, parameters)
+
+    def add_value(self, index: int, value: Any):
+        if 0 < index <= self._num_cols:
+            self._values[index] = value
+        else:
+            raise SqlException(f"index must be between 1 and {self.num_columns} for this statement, got {index}")
+
+    def add_ratio(self, numerator_index: int, denominator_index: int, value: Optional[Ratio]):
+        if value is None:
+            self.add_value(numerator_index, None)
+            self.add_value(denominator_index, None)
+        else:
+            self.add_value(numerator_index, value.numerator)
+            self.add_value(denominator_index, value.denominator)
+
+    def try_execute_single_update(self, on_error: Optional[Callable[[Exception], None]] = None) -> bool:
+        """
+        Execute an update on the database with the given `query`.
+        Failures will be logged as warnings.
+        `query` The PreparedStatement to execute.
+        `id` The mRID of the relevant object that is being saved
+        `description` A description of the type of object (e.g. AcLineSegment)
+        Returns True if the `execute` was successful, False otherwise.
+        """
+        try:
+            self.execute()
+            return True
+        except Exception as ex:
+            if on_error:
+                on_error(ex)
+            return False
+
+    def log_failure(self, logger: Logger, description: str, ex: Exception):
+        logger.warning(
+            f"Failed to save {description}.\n" +
+            f"SQL: {self}\n" +
+            f"Fields: {self.parameters}\n"
+            f"Additional Info: {str(ex)}"
+        )
+
+    def close(self):
+        """Unused function on the Python side. Kept for compatibility with JVM side."""
+        pass

zepben/ewb/database/sqlite/extensions/result_set.py

@@ -0,0 +1,153 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+__all__ = ["ResultSet"]
+
+from datetime import datetime
+from typing import Any, Optional, Union, Type, TypeVar, List
+
+from zepben.ewb.model.cim.iec61968.infiec61968.infcommon.ratio import Ratio
+
+T = TypeVar("T")
+
+
+class ResultSet:
+    """
+    Wrapper class for records read from a database.
+    """
+    # The values of this row
+    _rows: List[List[Any]]
+
+    # The index of the next row to process
+    _next_row_index: int = 0
+
+    # The current row being processed
+    _current_row: Optional[List[Any]] = None
+
+    def __init__(self, rows: List[List[Any]]):
+        self._rows = rows
+
+    def next(self) -> bool:
+        """
+        Move to the next row.
+        :return: True if a new row was available, otherwise False.
+        """
+        if self._next_row_index >= len(self._rows):
+            self._current_row = None
+            return False
+
+        self._current_row = self._rows[self._next_row_index]
+        self._next_row_index = self._next_row_index + 1
+        return True
+
+    def get_string(self, column_index: int, on_none: Union[Optional[str], Type[Exception]] = ValueError) -> Optional[str]:
+        """
+        Get the value in the specified `column_index` as a string.
+        :param column_index: The column to read the value from. This uses 1 based indexes.
+        :param on_none: The value to use if a null is read from the database, or an exception to raise if a null value is not supported.
+        :return: The string read from the column, or the `on_none` value if there was no value.
+        """
+        if (column_index <= 0) or (column_index > len(self._current_row)):
+            raise IndexError
+
+        value = self._current_row[column_index - 1]
+        if value is None:
+            return self._value_or_raise(on_none)
+        elif isinstance(value, str):
+            return value
+        else:
+            raise ValueError
+
+    def get_int(self, column_index: int, on_none: Union[Optional[int], Type[Exception]] = ValueError) -> Optional[int]:
+        """
+        Get the value in the specified `column_index` as an integer.
+        :param column_index: The column to read the value from. This uses 1 based indexes.
+        :param on_none: The value to use if a null is read from the database, or an exception to raise if a null value is not supported.
+        :return: The integer read from the column, or the `on_none` value if there was no value.
+        """
+        if (column_index <= 0) or (column_index > len(self._current_row)):
+            raise IndexError
+
+        value = self._current_row[column_index - 1]
+        if value is None:
+            return self._value_or_raise(on_none)
+        elif isinstance(value, int):
+            return value
+        else:
+            raise ValueError
+
+    def get_float(self, column_index: int, on_none: Union[Optional[float], Type[Exception]] = ValueError) -> Optional[float]:
+        """
+        Get the value in the specified `column_index` as a float.
+        :param column_index: The column to read the value from. This uses 1 based indexes.
+        :param on_none: The value to use if a null is read from the database, or an exception to raise if a null value is not supported.
+        :return: The float read from the column, or the `on_none` value if there was no value.
+        """
+        if (column_index <= 0) or (column_index > len(self._current_row)):
+            raise IndexError
+
+        value = self._current_row[column_index - 1]
+        if value is None:
+            return self._value_or_raise(on_none)
+        elif isinstance(value, float) or isinstance(value, int):
+            return value
+        else:
+            raise ValueError
+
+    def get_boolean(self, column_index: int, on_none: Union[Optional[bool], Type[Exception]] = ValueError) -> Optional[bool]:
+        """
+        Get the value in the specified `column_index` as a bool.
+        :param column_index: The column to read the value from. This uses 1 based indexes.
+        :param on_none: The value to use if a null is read from the database, or an exception to raise if a null value is not supported.
+        :return: The bool read from the column, or the `on_none` value if there was no value.
+        """
+        if (column_index <= 0) or (column_index > len(self._current_row)):
+            raise IndexError
+
+        value = self._current_row[column_index - 1]
+        if value is None:
+            return self._value_or_raise(on_none)
+        else:
+            return bool(value)
+
+    def get_instant(self, column_index: int, on_none: Union[Optional[datetime], Type[Exception]] = ValueError) -> Optional[datetime]:
+        """
+        Get the value in the specified `column_index` as a datetime.
+        :param column_index: The column to read the value from. This uses 1 based indexes.
+        :param on_none: The value to use if a null is read from the database, or an exception to raise if a null value is not supported.
+        :return: The datetime read from the column, or the `on_none` value if there was no value.
+        """
+        value = self.get_string(column_index, None)
+        if value is None:
+            return self._value_or_raise(on_none)
+        else:
+            # The timestamp in the database uses Z for UTC while python uses +HH:mm format, and potentially has more than 6 decimals for the fractions
+            # of seconds field, so only use the first 26 characters (yyyy-mm-ddThh:mm:ss.zzzzzz).
+            return datetime.fromisoformat(value.rstrip('Z')[:26])
+
+    def get_ratio(self, numerator_column_index: int, denominator_column_index: int, on_none: Union[Optional[bool], Type[Exception]] = ValueError):
+        """
+        Get a :class:`Ratio` using two columns: a numerator column and denominator column.
+
+        :param numerator_column_index: The column to read the numerator from. This uses 1 based indexes.
+        :param denominator_column_index: The column to read the denominator from. This uses 1 based indexes.
+        :param on_none: The value to use if a null is read from the database, or an exception to raise if a null value is not supported.
+        :return: The Ratio read from the column, or the `on_none` value if there was no value.
+        """
+        numerator = self.get_float(numerator_column_index, None)
+        denominator = self.get_float(denominator_column_index, None)
+
+        if numerator is None or denominator is None:
+            return self._value_or_raise(on_none)
+        else:
+            # noinspection PyArgumentList
+            return Ratio(numerator, denominator)
+
+    @staticmethod
+    def _value_or_raise(on_none: Union[Optional[T], Type[Exception]]) -> T:
+        if type(on_none) is type and issubclass(on_none, Exception):
+            raise on_none
+        else:
+            return on_none

zepben/ewb/database/sqlite/network/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.