fram-core 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

framcore/loaders/loaders.py

@@ -0,0 +1,405 @@
+"""Classes defining APIs for Loaders."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import ClassVar
+
+from numpy.typing import NDArray
+
+from framcore import Base
+from framcore.fingerprints import Fingerprint
+from framcore.timeindexes import TimeIndex
+from framcore.timevectors import ReferencePeriod
+
+
+class Loader(Base, ABC):
+    """Base Loader class defining common API and functionality for all Loaders."""
+
+    def __init__(self) -> None:
+        """Set up cache of ids contained in the source of the Loader."""
+        self._content_ids: list[str] = None
+
+    def __repr__(self) -> str:
+        """
+        Overwrite string representation.
+
+        Returns:
+            str: Object represented as string.
+
+        """
+        return f"{type(self).__name__}({vars(self)})"
+
+    def __getstate__(self) -> dict:
+        """
+        Return current object state, clearing any cached data.
+
+        Returns:
+            dict: The object's state dictionary.
+
+        """
+        self.clear_cache()
+        return self.__dict__
+
+    @abstractmethod
+    def clear_cache(self) -> None:
+        """Clear cached data from the loader."""
+        pass
+
+    def __deepcopy__(self, memo: dict) -> Loader:
+        """
+        Overwrite deepcopy.
+
+        This is done to enable sharing of loaders. Since a loader is connected to one source, caching can thus be shared
+        between Models.
+
+        Args:
+            memo (dict): Required argument.
+
+        Returns:
+            Loader: Returns itself.
+
+        """
+        return self
+
+    @abstractmethod
+    def get_source(self) -> object:
+        """
+        Return Loader source.
+
+        Returns:
+            object: Whatever the Loader interacts with to retrieve data.
+
+        """
+        pass
+
+    @abstractmethod
+    def set_source(self, new_source: object) -> None:
+        """
+        Set the Loader source.
+
+        Args:
+            new_source (object): Whatever the Loader should interact with to retrieve data.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_metadata(self, content_id: str) -> object:
+        """
+        Get metadata from the Loader source.
+
+        The metadata could describe behavior of the data in source.
+
+        Args:
+            content_id (str): Id of some content.
+
+        Returns:
+            object: Metadata in some format only the specific Loader knows.
+
+        """
+        pass
+
+    @abstractmethod
+    def _get_ids(self) -> list[str]:
+        """
+        Return list of names which can be used to access specific data structures whithin source.
+
+        Most likely the names of all time vectors or curves in The Loader's source.
+
+        Returns:
+            list[str]
+
+        """
+        pass
+
+    def get_ids(self) -> list[str]:
+        """
+        Handle caching of ids existing in the loaders source.
+
+        Returns:
+            list[str]: List containing ids in Loader source.
+
+        """
+        if self._content_ids is None:
+            self._content_ids = self._get_ids()
+            seen = set()
+            duplicates = []
+            for content_id in self._content_ids:
+                if content_id in seen:
+                    duplicates.append(content_id)
+                else:
+                    seen.add(content_id)
+            if duplicates:
+                msg = f"Duplicate ID's found in {self.get_source()}: {duplicates}"
+                raise ValueError(msg)
+
+        return self._content_ids
+
+    def _id_exsists(self, content_id: str) -> None:
+        """
+        Check if a given id exists in source.
+
+        Args:
+            content_id (str): Id of some content.
+
+        Raises:
+            KeyError: If content id does not exist.
+
+        """
+        existing_ids = self.get_ids()
+        if content_id not in existing_ids:
+            # __repr__ should be overwritten in subclasses to produce enough info in error message.
+            msg = f"Could not find ID {content_id} in {self}. Existing IDs: {existing_ids}"
+            raise KeyError(msg)
+
+
+class TimeVectorLoader(Loader, ABC):
+    """Loader API for retrieving time vector data from some source."""
+
+    @abstractmethod
+    def get_values(self, vector_id: str) -> NDArray:
+        """
+        Return the values of a time vector in the Loader source.
+
+        Args:
+            vector_id (str): ID of the vector.
+
+        Returns:
+            NDArray: Numpy array of all values.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_index(self, vector_id: str) -> TimeIndex:
+        """
+        Return the index a time vector in the Loader source.
+
+        Args:
+            vector_id (str): ID of the vector.
+
+        Returns:
+            NDArray: TimeIndex object.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_unit(self, vector_id: str) -> str:
+        """
+        Return unit of the values within a time vector in the loader source.
+
+        Args:
+            vector_id (str): ID of the vector.
+
+        Returns:
+            str: String with unit.
+
+        """
+        pass
+
+    @abstractmethod
+    def is_max_level(self, vector_id: str) -> bool | None:
+        """
+        Check if the given TimeVector is a level representing max Volume/Capacity/Price.
+
+        Args:
+            vector_id (str): ID of the vector.
+
+        Returns:
+            True - vector is a level representing max Volume/Capacity.
+            False - vector is a level representing average Volume/Capacity over a given reference period.
+            None - vector is not a level.
+
+        """
+        pass
+
+    @abstractmethod
+    def is_zero_one_profile(self, vector_id: str) -> bool | None:
+        """
+        Check if the given TimeVector is a profile with values between zero and one.
+
+        Args:
+            vector_id (str): ID of the vector.
+
+        Returns:
+            True - vector is a profile with values between zero and one.
+            False - vector is a profile where the mean value is 1 given a reference period.
+            None - vector is not a profile.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_reference_period(self, vector_id: str) -> ReferencePeriod | None:
+        """
+        Get the reference period of a given vector.
+
+        Args:
+            vector_id (str): ID of the vector.
+
+        Returns:
+            ReferencePeriod - if the vector is a mean one profile or average level, a reference period must exist.
+            None - No reference period if vector is max level, zero one profile or not a level or profile.
+
+        """
+        pass
+
+    def get_fingerprint(self, vector_id: str) -> Fingerprint:
+        """Return Loader Fingerprint for given vector id."""
+        f = Fingerprint(self)
+        f.add("unit", self.get_unit(vector_id))
+        f.add("index", self.get_index(vector_id))
+        f.add("values", self.get_values(vector_id))
+        return f
+
+
+class CurveLoader(Loader, ABC):
+    """Loader API for retrieving curve data from some source."""
+
+    @abstractmethod
+    def get_y_axis(self, curve_id: str) -> NDArray:
+        """
+        Return the values of a Curves y axis in the Loader source.
+
+        Args:
+            curve_id (str): ID of the curve.
+
+        Returns:
+            NDArray: Numpy array of all values in the y axis.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_x_axis(self, curve_id: str) -> NDArray:
+        """
+        Return the values of a Curves x axis in the Loader source.
+
+        Args:
+            curve_id (str): ID of the curve.
+
+        Returns:
+            NDArray: Numpy array of all values in the x axis.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_x_unit(self, curve_id: str) -> str:
+        """
+        Return the unit of the x axis of a specific curve.
+
+        Args:
+            curve_id (str): ID of the curve.
+
+        Returns:
+            str: Unit of the curve's x axis.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_y_unit(self, curve_id: str) -> str:
+        """
+        Return the unit of the y axis of a specific curve.
+
+        Args:
+            curve_id (str): ID of the curve.
+
+        Returns:
+            str: Unit of the curve's y axis.
+
+        """
+        pass
+
+
+class FileLoader(Loader, ABC):
+    """Define common functionality and API for Loaders connected to a file as source."""
+
+    _SUPPORTED_SUFFIXES: ClassVar[list[str]] = []
+
+    def __init__(self, source: Path | str, relative_loc: Path | str | None = None) -> None:
+        """
+        Check validity of input parameters.
+
+        Args:
+            source (Path | str): Full file path or the absolute part of a file path
+            relative_loc (Optional[Union[Path, str]], optional): The relative part of a file path. Defaults to None.
+
+        """
+        super().__init__()
+        self._source = source
+        self._relative_loc = relative_loc
+
+        self._check_type(source, (Path, str))
+        if self._relative_loc is not None:
+            self._check_type(self._relative_loc, (Path, str))
+        self._check_path_exists(self.get_source())
+        self._check_path_supported(self.get_source())
+
+    def __repr__(self) -> str:
+        """Overwrite __repr__ to get better info."""
+        return f"{type(self).__name__}(source={self._source}, relative_loc={self._relative_loc})"
+
+    def get_source(self) -> Path:
+        """Combine absolute and relative file path (if relative is defined) to get full source."""
+        if self._relative_loc is None:
+            return Path(self._source)
+        return Path(self._source) / self._relative_loc
+
+    def set_source(self, new_source: Path, relative_loc: Path | str | None = None) -> None:
+        """
+        Set absolute and relative parts of filepath.
+
+        Args:
+            new_source (Path): New absolute part.
+            relative_loc (Optional[Union[Path, str]], optional): New relative part. Defaults to None.
+
+        """
+        self._source = new_source
+        self._relative_loc = relative_loc
+
+    @classmethod
+    def get_supported_suffixes(cls) -> list[str]:
+        """
+        Return list of supported file types.
+
+        Returns:
+            list: List of filetypes.
+
+        """
+        return cls._SUPPORTED_SUFFIXES
+
+    def _check_path_exists(self, path: Path) -> None:
+        """
+        Check if a file path exists.
+
+        Args:
+            path (Path): Path to check.
+
+        Raises:
+            FileNotFoundError
+
+        """
+        if not path.exists():
+            msg = f"""File {path} does not exist. Could not create {type(self)}."""
+            raise FileNotFoundError(msg)
+
+    def _check_path_supported(self, path: Path) -> None:
+        """
+        Check if a file is supported/readable by this FileLoader instance.
+
+        Args:
+            path (Path): Path to check.
+
+        Raises:
+            ValueError: If the file type is not defined as supported.
+
+        """
+        filetype = path.suffix
+        if filetype not in self._SUPPORTED_SUFFIXES:
+            msg = f"File type of {path}, {filetype} is not supported by {type(self)}. Supported filetypes: {self._SUPPORTED_SUFFIXES}"
+            raise ValueError(msg)

framcore/metadata/Div.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from framcore.fingerprints import Fingerprint
+from framcore.fingerprints.fingerprint import _custom_hash  # TODO: is this needed?
+from framcore.metadata.Meta import Meta  # NB! full import path needed for inheritance to work
+
+
+class Div(Meta):
+    """
+    Div class is made for loss-less aggregation of metadata. Subclass of Meta.
+
+    It's combine method is made to keep all unique metadata,
+    so that nothing is thrown away in connection with aggregation.
+    """
+
+    def __init__(self, value: Meta | set[Meta] | None = None) -> None:
+        """Create Div metadata."""
+        self._check_type_meta(value, with_none=True)
+
+        self._value: set[Meta] = set()
+
+        if isinstance(value, set):
+            self._value.update(value)
+
+        elif isinstance(value, Meta):
+            self._value.add(value)
+
+    def _check_type_meta(self, value: Meta | set[Meta], with_none: bool) -> None:
+        if with_none:
+            self._check_type(value, (Meta, set, type(None)))
+        else:
+            self._check_type(value, (Meta, set))
+        if isinstance(value, set):
+            for x in value:
+                self._check_type(x, Meta)
+
+    def get_value(self) -> set[Meta]:
+        """Return str value."""
+        return self._value
+
+    def set_value(self, value: Meta | set[Meta]) -> None:
+        """Set str value. TypeError if not str."""
+        self._check_type_meta(value, with_none=False)
+        if isinstance(value, set):
+            self._value.update(value)
+
+        elif isinstance(value, Meta):
+            self._value.add(value)
+
+    def combine(self, other: Meta | set[Meta]) -> Div:
+        """Just consume other and return self."""
+        self._check_type_meta(other, with_none=True)
+        if isinstance(other, Div):
+            for x in other.get_value():
+                self.combine(x)
+        else:
+            self.set_value(other)
+        return self
+
+    def get_fingerprint(self) -> Fingerprint:
+        """
+        Generate and return a Fingerprint representing the current set of Meta values.
+
+        Returns
+        -------
+        Fingerprint
+            A fingerprint object based on the hashes of the contained Meta values.
+
+        """
+        fingerprint = Fingerprint()
+        hash_list = [value.get_fingerprint().get_hash() for value in self._value]
+        fingerprint.add("_value", _custom_hash(hash_list))
+        return fingerprint

framcore/metadata/ExprMeta.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from framcore.expressions import Expr
+from framcore.fingerprints import Fingerprint
+from framcore.metadata import Div, Meta
+
+
+class ExprMeta(Meta):
+    """
+    ExprMeta represent an Expr. Subclass of Meta.
+
+    When used, all components must have a ExprMeta.
+    """
+
+    def __init__(self, value: Expr) -> None:
+        """Create new ExprMeta with float value."""
+        self._value = value
+        self._check_type(value, Expr)
+
+    def __repr__(self) -> str:
+        """Overwrite __repr__ for better string representation."""
+        if not hasattr(self, "_value"):
+            return f"{type(self).__name__}(uninitialized)"
+        return f"{type(self).__name__}(expr={self._value})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality based on expr."""
+        if not isinstance(other, ExprMeta):
+            return False
+        return self._value == other._value
+
+    def __hash__(self) -> int:
+        """Compute the hash of the ExprMeta."""
+        return hash(self._value)
+
+    def get_value(self) -> Expr:
+        """Return expr."""
+        return self._value
+
+    def set_value(self, value: Expr) -> None:
+        """Set expr value. TypeError if not expr."""
+        self._check_type(value, Expr)
+        self._value = value
+
+    def combine(self, other: Meta) -> Expr | Div:
+        """Sum Expr."""
+        if isinstance(other, ExprMeta):
+            return self._value + other.get_value()
+
+        div = Div(self)
+        div.set_value(other)
+        return div
+
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the fingerprint of the ScalarMeta."""
+        return self.get_fingerprint_default()

framcore/metadata/LevelExprMeta.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from framcore.expressions import Expr, ensure_expr
+from framcore.metadata.ExprMeta import ExprMeta  # NB! full import path needed for inheritance to work
+from framcore.timevectors import TimeVector
+
+
+class LevelExprMeta(ExprMeta):
+    """
+    LevelExprMeta represent an Expr. Subclass of ExprMeta.
+
+    When used, all components must have a ExprMeta.
+    """
+
+    def __init__(self, value: Expr | TimeVector) -> None:
+        """
+        Create new LevelExprMeta with Expr value.
+
+        Args:
+            value (Expr | TimeVector): Accepts Expr with is_level=True or TimeVector with is_max_level=True/False.
+
+        Raises:
+            TypeError: If value is not Expr or TimeVector.
+            ValueError: If value is non-level Expr or TimeVector.
+
+        """
+        self._check_type(value, (Expr, TimeVector))
+
+        if isinstance(value, TimeVector) and value.is_max_level() is None:
+            raise ValueError("Parameter 'value' (TimeVector) must be a level (is_max_level must be True or False).")
+
+        self._value = ensure_expr(value, is_level=True)

framcore/metadata/Member.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from framcore.fingerprints import Fingerprint
+from framcore.metadata import Div
+from framcore.metadata.Meta import Meta  # NB! full import path needed for inheritance to work
+
+
+class Member(Meta):
+    """
+    Member represent membership to a catergory or group using a str. Subclass of Meta.
+
+    Should not have missing values.
+
+    When used, all components must have a membership.
+    """
+
+    def __init__(self, value: str) -> None:
+        """Create new member with str value."""
+        self._value = value
+        self._check_type(value, str)
+
+    def __repr__(self) -> str:
+        """Overwrite __repr__ for better string representation."""
+        return f"{type(self).__name__}(value={self._value})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality based on value."""
+        if not isinstance(other, Member):
+            return False
+        return self._value == other._value
+
+    def __hash__(self) -> int:
+        """Overwrite __hash__ since its added to sets."""
+        return hash(self.__repr__())
+
+    def get_value(self) -> str:
+        """Return str value."""
+        return self._value
+
+    def set_value(self, value: str) -> None:
+        """Set str value. TypeError if not str."""
+        self._check_type(value, str)
+        self._value = value
+
+    def combine(self, other: Meta) -> Member | Div:
+        """Return self if other == self else return Div containing both."""
+        if self == other:
+            return self
+        d = Div(self)
+        d.set_value(other)
+        return d
+
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the fingerprint of the Member."""
+        return self.get_fingerprint_default()

framcore/metadata/Meta.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from framcore import Base
+from framcore.fingerprints import Fingerprint
+
+
+class Meta(Base, ABC):
+    """
+    Metadata-interface class for components.
+
+    The interface is there to support validation and aggregation.
+    - Some types of metadata should not have any missing values
+    - Different types of metadata should be aggregated differently (e.g. ignore, sum, mean, keep all in list, etc.)
+    """
+
+    @abstractmethod
+    def get_value(self) -> Any:  # noqa: ANN401
+        """Return metadata value."""
+        pass
+
+    @abstractmethod
+    def set_value(self, value: Any) -> None:  # noqa: ANN401
+        """
+        Set metadata value.
+
+        Error if incorrect type or value.
+
+        Some Meta types may be immutable and thus error if
+        set_value is called with any value.
+        """
+        pass
+
+    @abstractmethod
+    def combine(self, other: Meta) -> Meta | None:
+        """How should this metadata type be aggregated?."""
+        pass
+
+    @abstractmethod
+    def get_fingerprint(self) -> Fingerprint:
+        """Return fingerprint."""
+        pass

framcore/metadata/__init__.py

@@ -0,0 +1,15 @@
+# framcore/metadata/__init__.py
+
+from framcore.metadata.Meta import Meta
+from framcore.metadata.Div import Div
+from framcore.metadata.ExprMeta import ExprMeta
+from framcore.metadata.LevelExprMeta import LevelExprMeta
+from framcore.metadata.Member import Member
+
+__all__ = [
+    "Div",
+    "ExprMeta",
+    "LevelExprMeta",
+    "Member",
+    "Meta",
+]