zepben.ewb 1.1.0b6__py3-none-any.whl → 1.1.0b7__py3-none-any.whl

zepben/ewb/__init__.py

@@ -352,6 +352,7 @@ from zepben.ewb.services.diagram.diagram_service_comparator import DiagramServic
 
 from zepben.ewb.database.paths.database_type import *
 from zepben.ewb.database.paths.ewb_data_file_paths import *
+from zepben.ewb.database.paths.local_ewb_data_file_paths import *
 
 from zepben.ewb.database.sql.column import *
 from zepben.ewb.database.sqlite.tables.sqlite_table import *

zepben/ewb/database/paths/ewb_data_file_paths.py

@@ -1,202 +1,89 @@
-#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  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__ = ['EwbDataFilePaths']
 
+from abc import ABC, abstractmethod
 from datetime import date, timedelta
 from pathlib import Path
-from typing import Callable, Iterator, Optional, List
+from typing import Optional, List, Generator
 
 from zepben.ewb import require
 from zepben.ewb.database.paths.database_type import DatabaseType
 
 
-class EwbDataFilePaths:
+class EwbDataFilePaths(ABC):
     """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")
+    VARIANTS_PATH: str = "variants"
+    """
+    The folder containing the variants. Will be placed under the dated folder alongside the network model database.
+    """
 
-    def load_aggregator_meters_by_date(self) -> Path:
+    def resolve(self, database_type: DatabaseType, database_date: Optional[date] = None, variant: Optional[str] = None) -> Path:
         """
-        Determine the path to the "load aggregator meters-by-date" database.
+        Resolves the :class:`Path` to the database file for the specified :class:`DatabaseType`, within the specified `database_date`
+        and optional `variant` when `DatabaseType.per_date` is set to true.
 
-        :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.
+        :param database_type: The :class:`DatabaseType` to use for the database :class:`Path`.
+        :param database_date: The :class:`date` to use for the database :class:`Path`. Required when `database_type.per_date` is true, otherwise must be `None`.
+        :param variant: The optional name of the variant containing the database.
 
-        :return: The :class:`path` to the "weather readings" database.
+        :return: The :class:`Path` to the :class:`DatabaseType` database file.
         """
-        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")
+        if database_date is not None:
+            require(database_type.per_date, lambda: "database_type must have its per_date set to True to use this method with a database_date.")
+            if variant is not None:
+                return self.resolve_database(self._to_dated_variant_path(database_type, database_date, variant))
+            else:
+                return self.resolve_database(self._to_dated_path(database_type, database_date))
+        else:
+            require(not database_type.per_date, lambda: "database_type must have its per_date set to False to use this method without a database_date.")
+            return self.resolve_database(Path(self._database_name(database_type)))
 
+    @abstractmethod
     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:
+        :return: The :class:`Path` to the directory for the `database_date`.
         """
-        Check if a database of the specified type and date exists.
+        raise NotImplemented
 
-        :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]:
+    def find_closest(
+        self,
+        database_type: DatabaseType,
+        max_days_to_search: int = 999999,
+        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.
+        :param target_date: The target date. Defaults to today.
+        :param search_forwards: Indicates the search should also look forwards in time from `target_date` for a valid file. Defaults to reverse search only.
+
+        :return: The closest :class:`date` to `target_date` with a valid database of `database_type` within the search parameters, or null if no valid database
+          was found.
         """
         if not database_type.per_date:
             return None
 
-        if self._check_exists(database_type, target_date):
+        descendants = list(self.enumerate_descendants())
+        if self._check_exists(descendants, 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):
+                if self._check_exists(descendants, database_type, previous_date):
                     return previous_date
             except OverflowError:
                 pass
@@ -204,34 +91,102 @@ class EwbDataFilePaths:
             if search_forwards:
                 try:
                     forward_date = target_date + offset_days
-                    if self._check_exists(database_type, forward_date):
+                    if self._check_exists(descendants, 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]:
+    def get_available_dates_for(self, database_type: DatabaseType) -> List[date]:
+        """
+        Find available databases specified by :class:`DatabaseType` in data path.
+
+        :param database_type: The type of database to search for.
+
+        :return: list of :class:`date`'s for which this specified :class:`DatabaseType` databases exist in the data path.
+        """
         if not database_type.per_date:
             raise ValueError(
-                "INTERNAL ERROR: Should only be calling `_get_available_dates_for` for `per_date` files.")
+                "INTERNAL ERROR: Should only be calling `get_available_dates_for` for `per_date` files, "
+                "which should all be covered above, so go ahead and add it."
+            )
 
         to_return = list()
 
-        for file in self.list_files(self._base_dir):
-            if self.is_directory(file):
+        for it in self.enumerate_descendants():
+            if it.name.endswith(self._database_name(database_type)):
                 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)
+                    to_return.append(date.fromisoformat(it.parent.name))
                 except ValueError:
                     pass
+
+        return sorted(to_return)
+
+    def get_available_variants_for(self, target_date: date = date.today()) -> List[str]:
+        """
+        Find available variants for the specified `target_date` in data path.
+
+        :param target_date: The target date. Defaults to today.
+
+        :return: list of variant names that exist in the data path for the specified `target_date`.
+        """
+        to_return = list()
+
+        for it in self.enumerate_descendants():
+            try:
+                if (str(it.parent.name).lower() == self.VARIANTS_PATH) and (str(it.parent.parent.name) == str(target_date)):
+                    to_return.append(str(it.name))
+            except ValueError:
+                pass
+
         return sorted(to_return)
 
-    def get_network_model_databases(self) -> List[date]:
+    @abstractmethod
+    def enumerate_descendants(self) -> Generator[Path, None, None]:
+        """
+        Lists the child items of source location.
+
+        :return: generator of child items.
+        """
+        raise NotImplemented
+
+    @abstractmethod
+    def resolve_database(self, path: Path) -> Path:
         """
-        Find available network-model databases in data path.
+        Resolves the database in the specified source :class:`Path`.
 
-        :return: A list of :class:`date`'s for which network-model databases exist in the data path.
+        :param path: :class:`Path` to the source database file.
+        :return: :class:`Path` to the local database file.
         """
-        return self._get_available_dates_for(DatabaseType.NETWORK_MODEL)
+        raise NotImplemented
+
+    def _check_exists(self, descendants: List[Path], database_type: DatabaseType, database_date: date) -> bool:
+        """
+        Check if a database :class:`Path` of the specified :class:`DatabaseType` and :class:`date` exists.
+
+        :param descendants: A list of :class:`Path` representing the descendant paths.
+        :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` exits in the date path.
+        """
+        for cp in descendants:
+            if cp.is_relative_to(self._to_dated_path(database_type, database_date)):
+                return True
+
+        return False
+
+    def _to_dated_path(self, database_type: DatabaseType, database_date: date) -> Path:
+        date_str = str(database_date)
+        return Path(date_str).joinpath(f"{date_str}-{self._database_name(database_type)}")
+
+    def _to_dated_variant_path(self, database_type: DatabaseType, database_date: date, variant: str) -> Path:
+        date_str = str(database_date)
+        return Path(date_str).joinpath(self.VARIANTS_PATH, variant, f"{date_str}-{self._database_name(database_type)}")
+
+    @staticmethod
+    def _database_name(database_type: DatabaseType) -> str:
+        return f"{database_type.file_descriptor}.sqlite"

zepben/ewb/database/paths/local_ewb_data_file_paths.py

@@ -0,0 +1,58 @@
+#  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__ = ['LocalEwbDataFilePaths']
+
+from datetime import date
+from pathlib import Path
+from typing import Callable, Generator, Union
+
+from zepben.ewb import require
+from zepben.ewb.database.paths.ewb_data_file_paths import EwbDataFilePaths
+
+
+class LocalEwbDataFilePaths(EwbDataFilePaths):
+    """Provides paths to all the various data files / folders in the local file system used by EWB."""
+
+    def __init__(
+        self,
+        base_dir: Union[Path, str],
+        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], Generator[Path, None, None]] = 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.
+        :param create_directories_func: Function for directory creation.
+        :param is_directory: Function to determine if the supplied path is a directory .
+        :param exists: Function to determine if the supplied path exists.
+        :param list_files: Function for listing directories and files under the supplied path.
+        """
+        self._base_dir = Path(base_dir)
+        self._create_directories_func = create_directories_func
+        self._exists = exists
+        self._list_files = list_files
+
+        if create_path:
+            self._create_directories_func(base_dir)
+
+        require(is_directory(base_dir), lambda: f"base_dir must be a directory")
+
+    def create_directories(self, database_date: date) -> Path:
+        date_path = self._base_dir.joinpath(str(database_date))
+        if not self._exists(date_path):
+            self._create_directories_func(date_path)
+
+        return date_path
+
+    def enumerate_descendants(self) -> Generator[Path, None, None]:
+        for it in self._list_files(self._base_dir):
+            yield it
+
+    def resolve_database(self, path: Path) -> Path:
+        return self._base_dir.joinpath(path)

{zepben_ewb-1.1.0b6.dist-info → zepben_ewb-1.1.0b7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zepben.ewb
-Version: 1.1.0b6
+Version: 1.1.0b7
 Summary: Python SDK for interacting with the Energy Workbench platform
 Author-email: Kurt Greaves <kurt.greaves@zepben.com>, Max Chesterfield <max.chesterfield@zepben.com>
 License-Expression: MPL-2.0

{zepben_ewb-1.1.0b6.dist-info → zepben_ewb-1.1.0b7.dist-info}/RECORD

@@ -1,4 +1,4 @@
-zepben/ewb/__init__.py,sha256=B5sJdP6ozOagFMdAD8AYfcqAqicoHjug28IiRS9FYp8,40514
+zepben/ewb/__init__.py,sha256=nPkN55KJGBRGRk7fLZAFmzaxu9Z7RR7gGAAwFWdy3lY,40580
 zepben/ewb/exceptions.py,sha256=KLR6_5U-K4_VtKQZkKBlbOF7wlKnajQuhSiGeeNAo9U,1384
 zepben/ewb/types.py,sha256=067jjQX6eCbgaEtlQPdSBi_w4_16unbP1f_g5NrVj_w,627
 zepben/ewb/util.py,sha256=lgxqbGEQO8df-Bs88-4bVijB8CY9rY8ox8WjibqZWnM,5728
@@ -12,7 +12,8 @@ zepben/ewb/auth/common/auth_provider_config.py,sha256=-MkmrOXFgp2K-Q9f-oyaNr2Qhe
 zepben/ewb/database/__init__.py,sha256=waADXEvfUG9wAN4STx5uIUHOv0UnpZLH2qU1LXgaDBc,243
 zepben/ewb/database/paths/__init__.py,sha256=waADXEvfUG9wAN4STx5uIUHOv0UnpZLH2qU1LXgaDBc,243
 zepben/ewb/database/paths/database_type.py,sha256=6l43Q87n3pQ4ClG9zfbp7cRSjt-Fxb01Tdrt48ZHMbk,1025
-zepben/ewb/database/paths/ewb_data_file_paths.py,sha256=hoED3sNmnB7tQF9dMPcCH9ozOa5P85u_RewZjqsPMbs,10426
+zepben/ewb/database/paths/ewb_data_file_paths.py,sha256=MchDxklK9atSxOUtq28Yi4hRyilVk2GF8deMrsMdBt4,8063
+zepben/ewb/database/paths/local_ewb_data_file_paths.py,sha256=XeOzoTvuaheD6KAM6EGW56rkiSDHIPE-x7_8iP5vQR0,2390
 zepben/ewb/database/sql/__init__.py,sha256=8-znO960twGtcAGArLGl_ijbCB9BBv0_hUNYf1eF0Lk,243
 zepben/ewb/database/sql/column.py,sha256=migPYL0in18cCWd3H51M-op2uqJeYqGv9KIksSiv75s,1049
 zepben/ewb/database/sql/sql_table.py,sha256=0ADKRb_2uAz0iSz52wbwOjovctvwRte8sHBBfEGj7cU,5235
@@ -634,8 +635,8 @@ zepben/ewb/streaming/mutations/update_network_state_client.py,sha256=e0Oma5PRT8m
 zepben/ewb/streaming/mutations/update_network_state_service.py,sha256=irR-TO67QXRyBmK8PU8SzM31NKSSefZt_nQGHi5IhT8,3260
 zepben/ewb/testing/__init__.py,sha256=waADXEvfUG9wAN4STx5uIUHOv0UnpZLH2qU1LXgaDBc,243
 zepben/ewb/testing/test_network_builder.py,sha256=KG0o2ZHUswx3xClu-JnLs_pYIYbQ5jjtvtyZ7LI6IZ8,38092
-zepben_ewb-1.1.0b6.dist-info/licenses/LICENSE,sha256=aAHD66h6PQIETpkJDvg5yEObyFvXUED8u7S8dlh6K0Y,16725
-zepben_ewb-1.1.0b6.dist-info/METADATA,sha256=UyEQUhwT3LJSz7nRPfnbA8wdmOsiwXjzQoPkbgzLe3Y,3232
-zepben_ewb-1.1.0b6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-zepben_ewb-1.1.0b6.dist-info/top_level.txt,sha256=eVLDJiO6FGjL_Z7KdmFE-R8uf1Q07aaVLGe9Ee4kmBw,7
-zepben_ewb-1.1.0b6.dist-info/RECORD,,
+zepben_ewb-1.1.0b7.dist-info/licenses/LICENSE,sha256=aAHD66h6PQIETpkJDvg5yEObyFvXUED8u7S8dlh6K0Y,16725
+zepben_ewb-1.1.0b7.dist-info/METADATA,sha256=1hwk8UacCWwT38sTK6gL_4SsQa8CXQGNQmoUMBKhz3E,3232
+zepben_ewb-1.1.0b7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+zepben_ewb-1.1.0b7.dist-info/top_level.txt,sha256=eVLDJiO6FGjL_Z7KdmFE-R8uf1Q07aaVLGe9Ee4kmBw,7
+zepben_ewb-1.1.0b7.dist-info/RECORD,,