zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/database/sqlite/diagram/diagram_cim_writer.py

@@ -0,0 +1,81 @@
+#  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__ = ["DiagramCimWriter"]
+
+from zepben.ewb.database.sqlite.common.base_cim_writer import BaseCimWriter
+from zepben.ewb.database.sqlite.diagram.diagram_database_tables import DiagramDatabaseTables
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagram_object_points import TableDiagramObjectPoints
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagram_objects import TableDiagramObjects
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagrams import TableDiagrams
+from zepben.ewb.model.cim.iec61970.base.diagramlayout.diagram import Diagram
+from zepben.ewb.model.cim.iec61970.base.diagramlayout.diagram_object import DiagramObject
+from zepben.ewb.model.cim.iec61970.base.diagramlayout.diagram_object_point import DiagramObjectPoint
+
+
+class DiagramCimWriter(BaseCimWriter):
+    """
+    A class for writing the `DiagramService` tables to the database.
+
+    :param database_tables: The tables available in the database.
+    """
+
+    def __init__(self, database_tables: DiagramDatabaseTables):
+        super().__init__(database_tables)
+
+    ################################
+    # IEC61970 Base Diagram Layout #
+    ################################
+
+    def save_diagram(self, diagram: Diagram) -> bool:
+        """
+        Save the `Diagram` fields to `TableDiagrams`.
+
+        :param diagram: The `Diagram` instance to write to the database.
+
+        :return: True if the `Diagram` was successfully written to the database, otherwise false.
+        :raises SqlException: For any errors encountered writing to the database.
+        """
+        table = self._database_tables.get_table(TableDiagrams)
+        insert = self._database_tables.get_insert(TableDiagrams)
+
+        insert.add_value(table.diagram_style.query_index, diagram.diagram_style.name)
+        insert.add_value(table.orientation_kind.query_index, diagram.orientation_kind.name)
+
+        return self._save_identified_object(table, insert, diagram, "diagram")
+
+    def save_diagram_object(self, diagram_object: DiagramObject) -> bool:
+        """
+        Save the `DiagramObject` fields to `TableDiagramObjects`.
+
+        :param diagram_object: The `DiagramObject` instance to write to the database.
+
+        :return: True if the `DiagramObject` was successfully written to the database, otherwise false.
+        :raises SqlException: For any errors encountered writing to the database.
+        """
+        table = self._database_tables.get_table(TableDiagramObjects)
+        insert = self._database_tables.get_insert(TableDiagramObjects)
+
+        status = True
+        for sequence, point in enumerate(diagram_object.points):
+            status = all([status, self._save_diagram_object_point(diagram_object, point, sequence)])
+
+        insert.add_value(table.identified_object_mrid.query_index, diagram_object.identified_object_mrid)
+        insert.add_value(table.diagram_mrid.query_index, self._mrid_or_none(diagram_object.diagram))
+        insert.add_value(table.style.query_index, diagram_object.style)
+        insert.add_value(table.rotation.query_index, diagram_object.rotation)
+
+        return all([status, self._save_identified_object(table, insert, diagram_object, "diagram object")])
+
+    def _save_diagram_object_point(self, diagram_object: DiagramObject, diagram_object_point: DiagramObjectPoint, sequence_number: int) -> bool:
+        table = self._database_tables.get_table(TableDiagramObjectPoints)
+        insert = self._database_tables.get_insert(TableDiagramObjectPoints)
+
+        insert.add_value(table.diagram_object_mrid.query_index, diagram_object.mrid)
+        insert.add_value(table.sequence_number.query_index, sequence_number)
+        insert.add_value(table.x_position.query_index, diagram_object_point.x_position)
+        insert.add_value(table.y_position.query_index, diagram_object_point.y_position)
+
+        return self._try_execute_single_update(insert, "diagram object point")

zepben/ewb/database/sqlite/diagram/diagram_database_reader.py

@@ -0,0 +1,45 @@
+#  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__ = ["DiagramDatabaseReader"]
+
+from sqlite3 import Connection
+
+from zepben.ewb.database.sqlite.common.base_database_reader import BaseDatabaseReader
+from zepben.ewb.database.sqlite.common.metadata_collection_reader import MetadataCollectionReader
+from zepben.ewb.database.sqlite.diagram.diagram_database_tables import DiagramDatabaseTables
+from zepben.ewb.database.sqlite.diagram.diagram_service_reader import DiagramServiceReader
+from zepben.ewb.database.sqlite.tables.table_version import TableVersion
+from zepben.ewb.services.diagram.diagrams import DiagramService
+
+
+class DiagramDatabaseReader(BaseDatabaseReader):
+    """
+    A class for reading the `DiagramService` objects and `MetadataCollection` from our diagram database.
+
+    :param connection: The connection to the database.
+    :param service: The `DiagramService` to populate with CIM objects from the database.
+    :param database_description: The description of the database for logging (e.g. filename).
+    """
+
+    def __init__(
+        self,
+        connection: Connection,
+        service: DiagramService,
+        database_description: str,
+        tables: DiagramDatabaseTables = None,
+        metadata_reader: MetadataCollectionReader = None,
+        service_reader: DiagramServiceReader = None,
+        table_version: TableVersion = None
+    ):
+        tables = tables if tables is not None else DiagramDatabaseTables()
+        super().__init__(
+            connection,
+            metadata_reader if metadata_reader is not None else MetadataCollectionReader(service, tables, connection),
+            service_reader if service_reader is not None else DiagramServiceReader(service, tables, connection),
+            service,
+            database_description,
+            table_version if table_version is not None else TableVersion()
+        )

zepben/ewb/database/sqlite/diagram/diagram_database_tables.py

@@ -0,0 +1,29 @@
+#  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__ = ["DiagramDatabaseTables"]
+
+from typing import Generator
+
+from zepben.ewb.database.sqlite.common.base_database_tables import BaseDatabaseTables
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagram_object_points import *
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagram_objects import *
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagrams import *
+from zepben.ewb.database.sqlite.tables.sqlite_table import *
+
+
+class DiagramDatabaseTables(BaseDatabaseTables):
+    """
+    The collection of tables for our customer databases.
+    """
+
+    @property
+    def _included_tables(self) -> Generator[SqliteTable, None, None]:
+        for table in super()._included_tables:
+            yield table
+
+        yield TableDiagramObjectPoints()
+        yield TableDiagramObjects()
+        yield TableDiagrams()

zepben/ewb/database/sqlite/diagram/diagram_database_writer.py

@@ -0,0 +1,44 @@
+#  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__ = ["DiagramDatabaseWriter"]
+
+import sqlite3
+from pathlib import Path
+from sqlite3 import Connection
+from typing import Callable, Union
+
+from zepben.ewb.database.sqlite.common.base_database_writer import BaseDatabaseWriter
+from zepben.ewb.database.sqlite.common.metadata_collection_writer import MetadataCollectionWriter
+from zepben.ewb.database.sqlite.diagram.diagram_database_tables import DiagramDatabaseTables
+from zepben.ewb.database.sqlite.diagram.diagram_service_writer import DiagramServiceWriter
+from zepben.ewb.services.diagram.diagrams import DiagramService
+
+
+class DiagramDatabaseWriter(BaseDatabaseWriter):
+    """
+    A class for writing the `DiagramService` objects and `MetadataCollection` to our diagram database.
+
+    :param database_file: the filename of the database to write.
+    :param service: The `DiagramService` to save to the database.
+    """
+
+    def __init__(
+        self,
+        database_file: Union[Path, str],
+        service: DiagramService,
+        database_tables: DiagramDatabaseTables = None,
+        create_metadata_writer: Callable[[], MetadataCollectionWriter] = None,
+        create_service_writer: Callable[[], DiagramServiceWriter] = None,
+        get_connection: Callable[[str], Connection] = None
+    ):
+        database_tables = database_tables if database_tables is not None else DiagramDatabaseTables()
+        super().__init__(
+            database_file,
+            database_tables,
+            create_metadata_writer if create_metadata_writer is not None else lambda: MetadataCollectionWriter(service, database_tables),
+            create_service_writer if create_service_writer is not None else lambda: DiagramServiceWriter(service, database_tables),
+            get_connection if get_connection is not None else sqlite3.connect
+        )

zepben/ewb/database/sqlite/diagram/diagram_service_reader.py

@@ -0,0 +1,49 @@
+#  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__ = ["DiagramServiceReader"]
+
+from sqlite3 import Connection
+
+from zepben.ewb.database.sqlite.common.base_service_reader import BaseServiceReader
+from zepben.ewb.database.sqlite.diagram.diagram_cim_reader import DiagramCimReader
+from zepben.ewb.database.sqlite.diagram.diagram_database_tables import DiagramDatabaseTables
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagram_object_points import TableDiagramObjectPoints
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagram_objects import TableDiagramObjects
+from zepben.ewb.database.sqlite.tables.iec61970.base.diagramlayout.table_diagrams import TableDiagrams
+from zepben.ewb.services.diagram.diagrams import DiagramService
+
+
+class DiagramServiceReader(BaseServiceReader):
+    """
+    A class for reading a `DiagramService` from the database.
+
+    :param service: The `DiagramService` to populate from the database.
+    :param database_tables: The tables available in the database.
+    :param connection: A connection to the database.
+
+    :param reader: The `DiagramCimReader` used to load the objects from the database.
+    """
+
+    def __init__(
+        self,
+        service: DiagramService,
+        database_tables: DiagramDatabaseTables,
+        connection: Connection,
+        reader: DiagramCimReader = None
+    ):
+        reader = reader if reader is not None else DiagramCimReader(service)
+        super().__init__(database_tables, connection, reader)
+
+        # This is not strictly necessary, it is just to update the type of the reader. It could be done with a generic
+        # on the base class which looks like it works, but that actually silently breaks code insight and completion
+        self._reader = reader
+
+    def _do_load(self) -> bool:
+        return all([
+            self._load_each(TableDiagrams, self._reader.load_diagrams),
+            self._load_each(TableDiagramObjects, self._reader.load_diagram_objects),
+            self._load_each(TableDiagramObjectPoints, self._reader.load_diagram_object_points)
+        ])

zepben/ewb/database/sqlite/diagram/diagram_service_writer.py

@@ -0,0 +1,41 @@
+#  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__ = ["DiagramServiceWriter"]
+
+from zepben.ewb.database.sqlite.common.base_service_writer import BaseServiceWriter
+from zepben.ewb.database.sqlite.diagram.diagram_cim_writer import DiagramCimWriter
+from zepben.ewb.database.sqlite.diagram.diagram_database_tables import DiagramDatabaseTables
+from zepben.ewb.model.cim.iec61970.base.diagramlayout.diagram import Diagram
+from zepben.ewb.model.cim.iec61970.base.diagramlayout.diagram_object import DiagramObject
+from zepben.ewb.services.diagram.diagrams import DiagramService
+
+
+class DiagramServiceWriter(BaseServiceWriter):
+    """
+    A class for writing a `DiagramService` into the database.
+
+    :param service: The `DiagramService` to save to the database.
+    :param database_tables: The `DiagramDatabaseTables` to add to the database.
+    """
+
+    def __init__(
+        self,
+        service: DiagramService,
+        database_tables: DiagramDatabaseTables,
+        writer: DiagramCimWriter = None
+    ):
+        writer = writer if writer is not None else DiagramCimWriter(database_tables)
+        super().__init__(service, writer)
+
+        # This is not strictly necessary, it is just to update the type of the writer. It could be done with a generic
+        # on the base class which looks like it works, but that actually silently breaks code insight and completion
+        self._writer = writer
+
+    def _do_save(self) -> bool:
+        return all([
+            self._save_each_object(DiagramObject, self._writer.save_diagram_object),
+            self._save_each_object(Diagram, self._writer.save_diagram)
+        ])

zepben/ewb/database/sqlite/extensions/__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/.

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/.