zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/database/paths/ewb_data_file_paths.py

@@ -0,0 +1,237 @@
+#  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__ = ['EwbDataFilePaths']
+
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Callable, Iterator, Optional, List
+
+from zepben.ewb import require
+from zepben.ewb.database.paths.database_type import DatabaseType
+
+
+class EwbDataFilePaths:
+    """Provides paths to all the various data files / folders used by EWB."""
+
+    def __init__(self, base_dir: Path,
+                 create_path: bool = False,
+                 create_directories_func: Callable[[Path], None] = lambda it: it.mkdir(parents=True),
+                 is_directory: Callable[[Path], bool] = Path.is_dir,
+                 exists: Callable[[Path], bool] = Path.exists,
+                 list_files: Callable[[Path], Iterator[Path]] = Path.iterdir):
+        """
+        :param base_dir: The root directory of the EWB data structure.
+        :param create_path: Create the root directory (and any missing parent folders) if it does not exist.
+        """
+        self.create_directories_func = create_directories_func
+        self.is_directory = is_directory
+        self.exists = exists
+        self.list_files = list_files
+        self._base_dir = base_dir
+
+        if create_path:
+            self.create_directories_func(base_dir)
+
+        require(self.is_directory(base_dir), lambda: f"base_dir must be a directory")
+
+    @property
+    def base_dir(self):
+        """The root directory of the EWB data structure."""
+        return self._base_dir
+
+    def customer(self, database_date: date) -> Path:
+        """
+        Determine the path to the "customers" database for the specified date.
+
+        :param database_date: The :class:`date` to use for the "customers" database.
+        :return: The :class:`path` to the "customers" database for the specified date.
+        """
+        return self._to_dated_path(database_date, DatabaseType.CUSTOMER.file_descriptor)
+
+    def diagram(self, database_date: date) -> Path:
+        """
+        Determine the path to the "diagrams" database for the specified date.
+
+        :param database_date: The :class:`date` to use for the "diagrams" database.
+        :return: The :class:`path` to the "diagrams" database for the specified date.
+        """
+        return self._to_dated_path(database_date, DatabaseType.DIAGRAM.file_descriptor)
+
+    def measurement(self, database_date: date) -> Path:
+        """
+        Determine the path to the "measurements" database for the specified date.
+
+        :param database_date: The :class:`date` to use for the "measurements" database.
+        :return: The :class:`path` to the "measurements" database for the specified date.
+        """
+        return self._to_dated_path(database_date, DatabaseType.MEASUREMENT.file_descriptor)
+
+    def network_model(self, database_date: date) -> Path:
+        """
+        Determine the path to the "network model" database for the specified date.
+
+        :param database_date: The :class:`date` to use for the "network model" database.
+        :return: The :class:`path` to the "network model" database for the specified date.
+        """
+        return self._to_dated_path(database_date, DatabaseType.NETWORK_MODEL.file_descriptor)
+
+    def tile_cache(self, database_date: date) -> Path:
+        """
+        Determine the path to the "tile cache" database for the specified date.
+
+        :param database_date: The :class:`date` to use for the "tile cache" database.
+        :return: The :class:`path` to the "tile cache" database for the specified date.
+        """
+        return self._to_dated_path(database_date, DatabaseType.TILE_CACHE.file_descriptor)
+
+    def energy_reading(self, database_date: date) -> Path:
+        """
+        Determine the path to the "energy readings" database for the specified date.
+
+        :param database_date: The :class:`date` to use for the "energy readings" database.
+        :return: The :class:`path` to the "energy readings" database for the specified date.
+        """
+        return self._to_dated_path(database_date, DatabaseType.ENERGY_READING.file_descriptor)
+
+    def energy_readings_index(self) -> Path:
+        """
+        Determine the path to the "energy readings index" database.
+
+        :return: The :class:`path` to the "energy readings index" database.
+        """
+        return self._base_dir.joinpath(f"{DatabaseType.ENERGY_READINGS_INDEX.file_descriptor}.sqlite")
+
+    def load_aggregator_meters_by_date(self) -> Path:
+        """
+        Determine the path to the "load aggregator meters-by-date" database.
+
+        :return: The :class:`path` to the "load aggregator meters-by-date" database.
+        """
+        return self._base_dir.joinpath(f"{DatabaseType.LOAD_AGGREGATOR_METERS_BY_DATE.file_descriptor}.sqlite")
+
+    def weather_reading(self) -> Path:
+        """
+        Determine the path to the "weather readings" database.
+
+        :return: The :class:`path` to the "weather readings" database.
+        """
+        return self._base_dir.joinpath(f"{DatabaseType.WEATHER_READING.file_descriptor}.sqlite")
+
+    def results_cache(self) -> Path:
+        """
+        Determine the path to the "results cache" database.
+
+        :return: The :class:`path` to the "results cache" database.
+        """
+        return self._base_dir.joinpath(f"{DatabaseType.RESULTS_CACHE.file_descriptor}.sqlite")
+
+    def create_directories(self, database_date: date) -> Path:
+        """
+        Create the directories required to have a valid path for the specified date.
+
+        :param database_date: The :class:`date` required in the path.
+        :return: The :class:`path` to the directory for the `database_date`.
+        """
+        date_path = self._base_dir.joinpath(str(database_date))
+        if self.exists(date_path):
+            return date_path
+        else:
+            self.create_directories_func(date_path)
+            return date_path
+
+    def _to_dated_path(self, database_date: date, file: str) -> Path:
+        return self._base_dir.joinpath(str(database_date), f"{database_date}-{file}.sqlite")
+
+    def _check_exists(self, database_type: DatabaseType, database_date: date) -> bool:
+        """
+        Check if a database of the specified type and date exists.
+
+        :param database_type: The type of database to search for.
+        :param database_date: The date to check.
+        :return: `True` if a database of the specified `database_type` and `database_date` exists in the date path.
+        """
+        if not database_type.per_date:
+            raise ValueError("INTERNAL ERROR: Should only be calling `checkExists` for `perDate` files.")
+
+        if database_type == DatabaseType.CUSTOMER:
+            model_path = self.customer(database_date)
+        elif database_type == DatabaseType.DIAGRAM:
+            model_path = self.diagram(database_date)
+        elif database_type == DatabaseType.MEASUREMENT:
+            model_path = self.measurement(database_date)
+        elif database_type == DatabaseType.NETWORK_MODEL:
+            model_path = self.network_model(database_date)
+        elif database_type == DatabaseType.TILE_CACHE:
+            model_path = self.tile_cache(database_date)
+        elif database_type == DatabaseType.ENERGY_READING:
+            model_path = self.energy_reading(database_date)
+        else:
+            raise ValueError(
+                "INTERNAL ERROR: Should only be calling `check_exists` for `per_date` files, which should all be covered above, so go ahead and add it.")
+        return self.exists(model_path)
+
+    def find_closest(self, database_type: DatabaseType, max_days_to_search: int = 999, target_date: date = date.today(), search_forwards: bool = False) -> \
+        Optional[date]:
+        """
+        Find the closest date with a usable database of the specified type.
+
+        :param database_type: The type of database to search for.
+        :param max_days_to_search: The maximum number of days to search for a valid database.
+        :param target_date: The target :class:`date`. Defaults to today.
+        :param search_forwards: Indicates the search should also look forwards in time from `start_date` for a valid file. Defaults to reverse search only.
+        :return: The closest :class:`date` to `database_date` with a valid database of `database_type` within the search parameters, or `None` if no valid database was found.
+        """
+        if not database_type.per_date:
+            return None
+
+        if self._check_exists(database_type, target_date):
+            return target_date
+
+        offset = 1
+
+        while offset <= max_days_to_search:
+            offset_days = timedelta(offset)
+            try:
+                previous_date = target_date - offset_days
+                if self._check_exists(database_type, previous_date):
+                    return previous_date
+            except OverflowError:
+                pass
+
+            if search_forwards:
+                try:
+                    forward_date = target_date + offset_days
+                    if self._check_exists(database_type, forward_date):
+                        return forward_date
+                except OverflowError:
+                    pass
+            offset += 1
+        return None
+
+    def _get_available_dates_for(self, database_type: DatabaseType) -> List[date]:
+        if not database_type.per_date:
+            raise ValueError(
+                "INTERNAL ERROR: Should only be calling `_get_available_dates_for` for `per_date` files.")
+
+        to_return = list()
+
+        for file in self.list_files(self._base_dir):
+            if self.is_directory(file):
+                try:
+                    database_date = date.fromisoformat(file.name)
+                    if self.exists(self._to_dated_path(database_date, database_type.file_descriptor)):
+                        to_return.append(database_date)
+                except ValueError:
+                    pass
+        return sorted(to_return)
+
+    def get_network_model_databases(self) -> List[date]:
+        """
+        Find available network-model databases in data path.
+
+        :return: A list of :class:`date`'s for which network-model databases exist in the data path.
+        """
+        return self._get_available_dates_for(DatabaseType.NETWORK_MODEL)

zepben/ewb/database/sql/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2025 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/sql/column.py

@@ -0,0 +1,37 @@
+#  Copyright 2025 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__ = ["Nullable", "Column"]
+
+from enum import Enum
+
+from zepben.ewb.dataclassy import dataclass
+from zepben.ewb.util import require
+
+
+class Nullable(Enum):
+    NONE = ""
+    NOT_NULL = "NOT NULL"
+    NULL = "NULL"
+
+    @property
+    def sql(self):
+        return self.value
+
+
+@dataclass(slots=True)
+class Column:
+    query_index: int
+    name: str
+    type: str
+    nullable: Nullable = Nullable.NONE
+
+    def __init__(self):
+        require(self.query_index >= 0, lambda: "You cannot use a negative query index.")
+        require(not self.name.isspace() and self.name, lambda: "Column Name cannot be blank.")
+        require(not self.type.isspace() and self.type, lambda: "Column Type cannot be blank.")
+
+    def __str__(self):
+        return f"{self.name} {self.type} {self.nullable.sql}".rstrip()

zepben/ewb/database/sql/sql_table.py

@@ -0,0 +1,142 @@
+#  Copyright 2025 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 __future__ import annotations
+
+__all__ = ["SqlTable"]
+
+from abc import abstractmethod, ABCMeta
+from operator import attrgetter
+from typing import List, Optional, Type, Any, Generator
+
+from zepben.ewb.database.sql.column import Column, Nullable
+
+
+class SqlTable(metaclass=ABCMeta):
+    """
+    Represents a table in an SQL Database.
+
+    By default, this class doesn't support creating schema creation statements, allowing support for database with external schema management.
+    """
+
+    column_index: int = 0
+    """Used to specify index of the column in the table during initialisation. Always increment BEFORE creating a Column. Indices start from 1."""
+
+    _column_set: Optional[List[Column]] = None
+    _create_table_sql: Optional[str] = None
+    _prepared_insert_sql: Optional[str] = None
+    _prepared_update_sql: Optional[str] = None
+    _create_indexes_sql: Optional[List[str]] = None
+    _select_sql: Optional[str] = None
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        The name of the table in the actual database.
+        """
+        pass
+
+    #
+    # NOTE: This function is called `description` in teh JVM SDK, but in the python SDK this
+    #       conflicts with the `description` column of `TableIdentifiedObjects`.
+    #
+    def describe(self) -> str:
+        """
+        Readable description of the contents of the table for adding to logs.
+        """
+        return self.name.replace("_", " ")
+
+    @property
+    @abstractmethod
+    def create_table_sql(self):
+        """
+        The SQL statement that should be executed to create the table in the database.
+        """
+        raise NotImplemented
+
+    @property
+    def prepared_insert_sql(self):
+        """
+        The SQL statement that should be used with a `PreparedStatement` to insert entries into the table.
+        """
+        if self._prepared_insert_sql is None:
+            self._prepared_insert_sql = (f"INSERT INTO {self.name} ({', '.join([c.name for c in self.column_set])}) "
+                                         f"VALUES ({', '.join(['?' for _ in self.column_set])})")
+        return self._prepared_insert_sql
+
+    @property
+    @abstractmethod
+    def create_indexes_sql(self):
+        """
+        The SQL statement that should be executed to create the indexes for the table in the database. Should be executed after all
+        entries are inserted into the table.
+        """
+        raise NotImplemented
+
+    @property
+    def select_sql(self):
+        """
+        The SQL statement that should be used to read the entries from the table in the database.
+        """
+        if self._select_sql is None:
+            self._select_sql = f"SELECT {', '.join([c.name for c in self.column_set])} FROM {self.name}"
+        return self._select_sql
+
+    @property
+    def prepared_update_sql(self):
+        """
+        The SQL statement that should be used with a `PreparedStatement` to update entries into the table.
+        """
+        if self._prepared_update_sql is None:
+            self._prepared_update_sql = f"UPDATE {self.name} SET {', '.join([f'{c.name} = ?' for c in self.column_set])}"
+        return self._prepared_update_sql
+
+    @property
+    def unique_index_columns(self) -> Generator[List[Column], None, None]:
+        """
+        A list of column groups that require a unique index in the database
+        """
+        yield from []
+
+    @property
+    def non_unique_index_columns(self) -> Generator[List[Column], None, None]:
+        """
+        A list of column groups that require a non-unique index in the database
+        """
+        yield from []
+
+    @property
+    def column_set(self) -> List[Column]:
+        if self._column_set is None:
+            self._column_set = list(self._build_column_set(self.__class__, self))
+        return self._column_set
+
+    @staticmethod
+    def _build_column_set(clazz: Type[Any], instance: SqlTable) -> Generator[Column, None, None]:
+        """
+        Builds the list of columns for use in DDL statements for this table.
+
+        :param clazz: The class of this table.
+        :param instance:
+        """
+        cols = list()
+        for field, x in instance.__dict__.items():
+            if isinstance(x, Column):
+                if x.query_index != len(cols) + 1:
+                    raise ValueError(
+                        f"Field {field} in SQL Table class {clazz.__name__} is using an invalid column index. "
+                        f"Did you forget to increment column_index, or did you skip one?"
+                    )
+                cols.append(x)
+
+        if len(set([c.name for c in cols])) != len(cols):
+            raise ValueError("You have duplicate column names, go fix that.")
+
+        yield from sorted(cols, key=attrgetter('query_index'))
+
+    def _create_column(self, name: str, type_: str, nullable: Nullable = Nullable.NONE) -> Column:
+        self.column_index += 1
+        # noinspection PyArgumentList
+        return Column(self.column_index, name, type_, nullable)

zepben/ewb/database/sqlite/__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/common/__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/common/base_cim_reader.py

@@ -0,0 +1,212 @@
+#  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__ = ["BaseCimReader"]
+
+import logging
+from abc import ABC
+from typing import Callable, Optional, Type
+
+from zepben.ewb.database.sqlite.common.reader_exceptions import DuplicateMRIDException
+from zepben.ewb.database.sqlite.extensions.result_set import ResultSet
+from zepben.ewb.database.sqlite.tables.iec61968.common.table_documents import TableDocuments
+from zepben.ewb.database.sqlite.tables.iec61968.common.table_organisation_roles import TableOrganisationRoles
+from zepben.ewb.database.sqlite.tables.iec61968.common.table_organisations import TableOrganisations
+from zepben.ewb.database.sqlite.tables.iec61970.base.core.table_identified_objects import TableIdentifiedObjects
+from zepben.ewb.database.sqlite.tables.iec61970.base.core.table_name_types import TableNameTypes
+from zepben.ewb.database.sqlite.tables.iec61970.base.core.table_names import TableNames
+from zepben.ewb.model.cim.iec61968.common.document import Document
+from zepben.ewb.model.cim.iec61968.common.organisation import Organisation
+from zepben.ewb.model.cim.iec61968.common.organisation_role import OrganisationRole
+from zepben.ewb.model.cim.iec61970.base.core.identified_object import IdentifiedObject, TIdentifiedObject
+from zepben.ewb.model.cim.iec61970.base.core.name_type import NameType
+from zepben.ewb.services.common.base_service import BaseService
+
+
+class BaseCimReader(ABC):
+    """
+    A base class for reading CIM objects from a database.
+    """
+
+    def __init__(self, service: BaseService):
+        super().__init__()
+        self._logger: logging.Logger = logging.getLogger(self.__class__.__name__)
+        """The `Logger` to use for this reader."""
+
+        self._service = service
+        """The `BaseService` used to store any items read from the database."""
+
+    ###################
+    # IEC61968 Common #
+    ###################
+
+    def _load_document(self, document: Document, table: TableDocuments, result_set: ResultSet) -> bool:
+        """
+        Populate the `Document` fields from `TableDocuments`.
+
+        :param document: The `Document` instance to populate.
+        :param table: The database table to read the `Document` fields from.
+        :param result_set: The record in the database table containing the fields for this `Document`.
+
+        :return: True if the `Document` was successfully read from the database and added to the service.
+        :raises SQLException: For any errors encountered reading from the database.
+        """
+        document.title = result_set.get_string(table.title.query_index, on_none=None)
+        document.created_date_time = result_set.get_instant(table.created_date_time.query_index, on_none=None)
+        document.author_name = result_set.get_string(table.author_name.query_index, on_none=None)
+        document.type = result_set.get_string(table.type.query_index, on_none=None)
+        document.status = result_set.get_string(table.status.query_index, on_none=None)
+        document.comment = result_set.get_string(table.comment.query_index, on_none=None)
+
+        return self._load_identified_object(document, table, result_set)
+
+    def load_organisations(self, table: TableOrganisations, result_set: ResultSet, set_identifier: Callable[[str], str]) -> bool:
+        """
+        Create an `Organisation` and populate its fields from `TableOrganisations`.
+
+        :param table: The database table to read the `Organisation` fields from.
+        :param result_set: The record in the database table containing the fields for this `Organisation`.
+        :param set_identifier: A callback to register the mRID of this `Organisation` for logging purposes.
+
+        :return: True if the `Organisation` was successfully read from the database and added to the service.
+        :raises SQLException: For any errors encountered reading from the database.
+        """
+        organisation = Organisation(mrid=set_identifier(result_set.get_string(table.mrid.query_index)))
+
+        return self._load_identified_object(organisation, table, result_set) and self._add_or_throw(organisation)
+
+    def _load_organisation_role(self, organisation_role: OrganisationRole, table: TableOrganisationRoles, result_set: ResultSet) -> bool:
+        """
+        Populate the `OrganisationRole` fields from `TableOrganisationRoles`.
+
+        :param organisation_role: The `OrganisationRole` instance to populate.
+        :param table: The database table to read the `OrganisationRole` fields from.
+        :param result_set: The record in the database table containing the fields for this `OrganisationRole`.
+
+        :return: True if the `OrganisationRole` was successfully read from the database and added to the service.
+        :raises SQLException: For any errors encountered reading from the database.
+        """
+        organisation_role.organisation = self._ensure_get(
+            result_set.get_string(table.organisation_mrid.query_index, on_none=None),
+            Organisation
+        )
+
+        return self._load_identified_object(organisation_role, table, result_set)
+
+    ######################
+    # IEC61970 Base Core #
+    ######################
+
+    @staticmethod
+    def _load_identified_object(identified_object: IdentifiedObject, table: TableIdentifiedObjects, result_set: ResultSet) -> bool:
+        """
+        Populate the `IdentifiedObject` fields from `TableIdentifiedObjects`.
+
+        :param identified_object: The `IdentifiedObject` instance to populate.
+        :param table: The database table to read the `IdentifiedObject` fields from.
+        :param result_set: The record in the database table containing the fields for this `IdentifiedObject`.
+
+        :return: True if the `IdentifiedObject` was successfully read from the database and added to the service.
+        :raises SQLException: For any errors encountered reading from the database.
+        """
+        identified_object.name = result_set.get_string(table.name_.query_index, on_none=None)
+        identified_object.description = result_set.get_string(table.description.query_index, on_none=None)
+        # Currently unused
+        # identified_object.num_diagram_objects = result_set.get_int(table.num_diagram_objects.query_index)
+
+        return True
+
+    def load_names(self, table: TableNames, result_set: ResultSet, set_last_name: Callable[[str], str]) -> bool:
+        """
+        Create a `Name` and populate its fields from `TableNames`.
+
+        :param table: The database table to read the `Name` fields from.
+        :param result_set: The record in the database table containing the fields for this `Name`.
+        :param set_last_name: A callback to register the name of this `Name` for logging purposes.
+
+        :return: True if the `Name` was successfully read from the database and added to the service.
+        :raises SQLException: For any errors encountered reading from the database.
+        """
+        name_type_name = result_set.get_string(table.name_type_name.query_index)
+        name_name = result_set.get_string(table.name_.query_index)
+        set_last_name(f"{name_type_name}:{name_name}")
+
+        name_type = self._service.get_name_type(name_type_name)
+        self._service.get(
+            result_set.get_string(table.identified_object_mrid.query_index),
+            IdentifiedObject,
+            generate_error=lambda mrid, typ: f"Failed to find {typ} with mRID {mrid} for Name {name_name} [{name_type_name}]"
+        ).add_name(name_type, name_name)
+
+        return True
+
+    def load_name_types(self, table: TableNameTypes, result_set: ResultSet, set_last_name_type: Callable[[str], str]) -> bool:
+        """
+        Create a `NameType` and populate its fields from `TableNameTypes`.
+
+        :param table: The database table to read the `NameType` fields from.
+        :param result_set: The record in the database table containing the fields for this `NameType`.
+        :param set_last_name_type: A callback to register the name of this `NameType` for logging purposes.
+
+        :return: True if the `NameType` was successfully read from the database and added to the service.
+        :raises SQLException: For any errors encountered reading from the database.
+        """
+        # noinspection PyArgumentList
+        name_type = NameType(set_last_name_type(result_set.get_string(table.name_.query_index)))
+        name_type.description = result_set.get_string(table.description.query_index)
+
+        return self._add_or_throw_name_type(name_type)
+
+    def _add_or_throw(self, identified_object: IdentifiedObject) -> bool:
+        """
+        Try and add the `identified_object` to the `service`, and throw an `Exception` if unsuccessful.
+
+        :param identified_object: The `IdentifiedObject` to add to the `service`.
+
+        :return: True in all instances, otherwise it throws.
+        :raises DuplicateMRIDException: If the `IdentifiedObject.mRID` has already been used.
+        :raises UnsupportedIdentifiedObjectException: If the `IdentifiedObject` is not supported by the `service`. This is an indication of an internal coding
+          issue, rather than a problem with the data being read, and in a correctly configured system will never occur.
+        """
+        if self._service.add(identified_object):
+            return True
+        else:
+            duplicate = self._service.get(identified_object.mrid)
+            raise DuplicateMRIDException(
+                f"Failed to load {identified_object}. " +
+                f"Unable to add to service '{self._service.name}': duplicate MRID ({duplicate})"
+            )
+
+    def _add_or_throw_name_type(self, name_type: NameType) -> bool:
+        """
+        Try and add the `name_type` to the `service`, and throw an `Exception` if unsuccessful.
+
+        :param name_type: The `NameType` to add to the `service`.
+
+        :return: True in all instances, otherwise it throws.
+        :raises DuplicateMRIDException: If the `NameType.name` has already been used.
+        """
+        if self._service.add_name_type(name_type):
+            return True
+        else:
+            raise DuplicateMRIDException(
+                f"Failed to load NameType {name_type.name}. " +
+                f"Unable to add to service '{self._service.name}': duplicate NameType)"
+            )
+
+    def _ensure_get(self, mrid: Optional[str], type_: Type[TIdentifiedObject] = IdentifiedObject) -> Optional[TIdentifiedObject]:
+        """
+        Optionally get an object associated with this service and throw if it is not found.
+
+        :param mrid: The mRID of the object to find.
+        :param type_: The type of object to look for. If this is a base class it will search all subclasses.
+
+        :return: The object identified by `mrid` as `type_` if it was found, or null if no `mrid` was supplied.
+        :raises MRIDLookupException: if no objects of type `type_` are found with the specified `mrid`
+        """
+        if (mrid is None) or (len(mrid) == 0):
+            return None
+        else:
+            return self._service.get(mrid, type_)