fameio 3.1.1__py3-none-any.whl → 3.3.0__py3-none-any.whl

fameio/series.py

@@ -1,26 +1,30 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 import math
 import os
 from enum import Enum, auto
 from pathlib import Path
-from typing import Union, Any
+from typing import Any
 
 import pandas as pd
 from fameprotobuf.input_file_pb2 import InputData
 from google.protobuf.internal.wire_format import INT64_MIN, INT64_MAX
 
+from fameio.input import InputError
 from fameio.input.resolver import PathResolver
 from fameio.logs import log, log_error
+from fameio.output import OutputError
 from fameio.time import ConversionError, FameTime
-from fameio.tools import clean_up_file_name
+from fameio.tools import clean_up_file_name, CSV_FILE_SUFFIX
 
 
-CSV_FILE_SUFFIX = ".csv"
+FILE_LENGTH_WARN_LIMIT = int(50e3)
 
 
-class TimeSeriesError(Exception):
+class TimeSeriesError(InputError, OutputError):
     """Indicates that an error occurred during management of time series"""
 
 
@@ -31,7 +35,7 @@ class Entry(Enum):
 
 
 class TimeSeriesManager:
-    """Manages matching of files to time series ids and their protobuf representation"""
+    """Manages matching of files to time series ids and their protobuf representation."""
 
     _TIMESERIES_RECONSTRUCTION_PATH = "./timeseries/"
     _CONSTANT_IDENTIFIER = "Constant value: {}"
@@ -40,87 +44,177 @@ class TimeSeriesManager:
 
     _ERR_FILE_NOT_FOUND = "Cannot find Timeseries file '{}'."
     _ERR_NUMERIC_STRING = " Remove quotes to use a constant numeric value instead of a timeseries file."
-    _ERR_CORRUPT_TIME_SERIES_KEY = "TimeSeries file '{}' corrupt: At least one entry in first column isn't a timestamp."
-    _ERR_CORRUPT_TIME_SERIES_VALUE = "TimeSeries file '{}' corrupt: At least one entry in value column isn't numeric."
+    _ERR_CORRUPT_KEYS = "TimeSeries file '{}' corrupt: At least one entry in first column isn't a timestamp."
+    _ERR_CORRUPT_VALUES = "TimeSeries file '{}' corrupt: At least one entry in second column isn't numeric."
     _ERR_NON_NUMERIC = "Values in TimeSeries must be numeric but was: '{}'"
     _ERR_NAN_VALUE = "Values in TimeSeries must not be missing or NaN."
     _ERR_UNREGISTERED_SERIES = "No timeseries registered with identifier '{}' - was the Scenario validated?"
+    _ERR_UNREGISTERED_SERIES_RE = "No timeseries registered with identifier '{}' - were the timeseries reconstructed?"
     _WARN_NO_DATA = "No timeseries stored in timeseries manager. Double check if you expected timeseries."
-    _WARN_DATA_IGNORED = "Timeseries contains additional columns with data which will be ignored."
+    _WARN_DATA_IGNORED = "Timeseries '{}' contains additional columns with data which will be ignored."
+    _WARN_LARGE_CONVERSION = (
+        "Timeseries file '{}' is large and needs conversion of time stamps. If performance "
+        "issues occur and the file is reused, convert the time stamp column once with "
+        "`fameio.time.FameTime.convert_datetime_to_fame_time_step(datetime_string)`."
+    )
 
     def __init__(self, path_resolver: PathResolver = PathResolver()) -> None:
         self._path_resolver = path_resolver
         self._id_count = -1
-        self._series_by_id: dict[Union[str, int, float], dict[Entry, Any]] = {}
+        self._series_by_id: dict[str | int | float, dict[Entry, Any]] = {}
 
-    def register_and_validate(self, identifier: Union[str, int, float]) -> None:
-        """
-        Registers given timeseries `identifier` and validates associated timeseries
+    def register_and_validate(self, identifier: str | int | float) -> None:
+        """Registers given timeseries `identifier` and validates associated timeseries.
 
         Args:
             identifier: to be registered - either a single numeric value or a string pointing to a timeseries file
 
         Raises:
-            TimeSeriesException: if file was not found, ill-formatted, or value was invalid
+            TimeSeriesError: if the file could not be found or contains improper data, or if identifier is NaN,
+                logged with level "ERROR"
         """
         if not self._time_series_is_registered(identifier):
             self._register_time_series(identifier)
 
-    def _time_series_is_registered(self, identifier: Union[str, int, float]) -> bool:
-        """Returns True if the value was already registered"""
+    def _time_series_is_registered(self, identifier: str | int | float) -> bool:
+        """Returns True if the value was already registered."""
         return identifier in self._series_by_id
 
-    def _register_time_series(self, identifier: Union[str, int, float]) -> None:
-        """Assigns an id to the given `identifier` and loads the time series into a dataframe"""
+    def _register_time_series(self, identifier: str | int | float) -> None:
+        """Assigns an id to the given `identifier` and loads the time series into a dataframe.
+
+        Args:
+            identifier: to be registered - either a single numeric value or a string pointing to a timeseries file
+
+        Raises:
+            TimeSeriesError: if the file could not be found or contains improper data, or if identifier is NaN,
+                logged with level "ERROR"
+        """
         self._id_count += 1
         name, series = self._get_name_and_dataframe(identifier)
         self._series_by_id[identifier] = {Entry.ID: self._id_count, Entry.NAME: name, Entry.DATA: series}
 
-    def _get_name_and_dataframe(self, identifier: Union[str, int, float]) -> tuple[str, pd.DataFrame]:
-        """Returns name and DataFrame containing the series obtained from the given `identifier`"""
+    def _get_name_and_dataframe(self, identifier: str | int | float) -> tuple[str, pd.DataFrame]:
+        """Returns name and DataFrame containing the series obtained from the given `identifier`.
+
+        Args:
+            identifier: to be registered - either a single numeric value or a string pointing to a timeseries file
+
+        Returns:
+            tuple of name & dataframe
+
+        Raises:
+            TimeSeriesError: if the file could not be found or contains improper data, or if identifier is NaN,
+                logged with level "ERROR"
+        """
         if isinstance(identifier, str):
             series_path = self._path_resolver.resolve_series_file_path(Path(identifier).as_posix())
             if series_path and os.path.exists(series_path):
-                data = pd.read_csv(series_path, sep=";", header=None, comment="#")
-                try:
-                    return identifier, self._check_and_convert_series(data)
-                except TypeError as e:
-                    raise log_error(TimeSeriesError(self._ERR_CORRUPT_TIME_SERIES_VALUE.format(identifier), e)) from e
-                except ConversionError as e:
-                    raise log_error(TimeSeriesError(self._ERR_CORRUPT_TIME_SERIES_KEY.format(identifier), e)) from e
-            else:
-                message = self._ERR_FILE_NOT_FOUND.format(identifier)
-                if self._is_number_string(identifier):
-                    message += self._ERR_NUMERIC_STRING
-                raise log_error(TimeSeriesError(message))
-        else:
-            return self._create_timeseries_from_value(identifier)
-
-    def _check_and_convert_series(self, data: pd.DataFrame) -> pd.DataFrame:
-        """Ensures validity of time series and convert to required format for writing to disk"""
-        additional_columns = data.loc[:, 2:]
-        is_empty = additional_columns.dropna(how="all").empty
-        if not is_empty:
-            log().warning(self._WARN_DATA_IGNORED)
+                data = self.read_timeseries_file(series_path)
+                return identifier, self.check_and_convert_series(data, identifier)
+            message = self._ERR_FILE_NOT_FOUND.format(identifier)
+            if self._is_number_string(identifier):
+                message += self._ERR_NUMERIC_STRING
+            raise log_error(TimeSeriesError(message))
+        return self._create_timeseries_from_value(identifier)
+
+    @staticmethod
+    def read_timeseries_file(file: Path | str) -> pd.DataFrame:
+        """Loads a timeseries from file.
+
+        Args:
+            file: to be read
+
+        Returns:
+            data frame obtained from file
+
+        Raises:
+            TimeSeriesError: if file could not be read, logged with level "ERROR"
+        """
+        try:
+            return pd.read_csv(file, sep=";", header=None, comment="#")
+        except OSError as e:
+            raise log_error(TimeSeriesError(e)) from e
+
+    @staticmethod
+    def check_and_convert_series(data: pd.DataFrame, file_name: str, warn: bool = True) -> pd.DataFrame:
+        """Ensures validity of time series and convert to required format for writing to disk.
+
+        Args:
+            data: dataframe to be converted to expected format
+            file_name: used in warnings and errors
+            warn: if True, a warning is raised if large files require conversion (default: True)
+
+        Returns:
+            2-column dataframe, first column: integers, second column: floats (no NaN)
+
+        Raises:
+            TimeSeriesError: if the data do not correspond to a valid time series, logged with level "ERROR"
+        """
+        try:
+            converted, large_conversion = TimeSeriesManager._check_and_convert_series(data, file_name)
+            if large_conversion and warn:
+                log().warning(TimeSeriesManager._WARN_LARGE_CONVERSION.format(file_name))
+            return converted
+        except TypeError as e:
+            raise log_error(TimeSeriesError(TimeSeriesManager._ERR_CORRUPT_VALUES.format(file_name), e)) from e
+        except ConversionError as e:
+            raise log_error(TimeSeriesError(TimeSeriesManager._ERR_CORRUPT_KEYS.format(file_name), e)) from e
+
+    @staticmethod
+    def _check_and_convert_series(data: pd.DataFrame, file_name: str) -> tuple[pd.DataFrame, bool]:
+        """Ensures validity of time series and convert to required format for writing to disk.
+
+        Args:
+            data: dataframe to be converted to expected format
+            file_name: used in warnings
+
+        Returns:
+            tuple of 1) dataframe and 2) large conversion indicator:
+                2-column dataframe first column: integers, second column: floats (no NaN)
+                large conversion indicator: if true, the timeseries was large and required conversion
+
+        Raises:
+            ConversionError: if first data column could not be converted to integer, logged with level "ERROR"
+            TypeError: if second data column in given data could not be converted to float or contained NaN,
+                logged with level "ERROR"
+        """
+        large_file_indicator = False
+        data, additional_columns = data.loc[:, :2], data.loc[:, 2:]
+        if not additional_columns.dropna(how="all").empty:
+            log().warning(TimeSeriesManager._WARN_DATA_IGNORED.format(file_name))
         if data.dtypes[0] != "int64":
+            if len(data[0]) > FILE_LENGTH_WARN_LIMIT:
+                large_file_indicator = True
             data[0] = [FameTime.convert_string_if_is_datetime(time) for time in data[0]]
-        data[1] = [TimeSeriesManager._assert_valid(value) for value in data[1]]
-        return data
+        if data.dtypes[1] != "float64":
+            data[1] = [TimeSeriesManager._assert_float(value) for value in data[1]]
+        if data[1].isna().any():
+            raise log_error(TypeError(TimeSeriesManager._ERR_NAN_VALUE))
+        return data, large_file_indicator
 
     @staticmethod
-    def _assert_valid(value: Any) -> float:
-        """Returns the given `value` if it is a numeric value other than NaN"""
+    def _assert_float(value: Any) -> float:
+        """Converts any given value to a float or raise an Exception.
+
+        Args:
+            value: to be converted to float
+
+        Returns:
+            float representation of value
+
+        Raises:
+            TypeError: if given value cannot be converted to float, logged with level "ERROR"
+        """
         try:
             value = float(value)
         except ValueError as e:
             raise log_error(TypeError(TimeSeriesManager._ERR_NON_NUMERIC.format(value))) from e
-        if math.isnan(value):
-            raise log_error(TypeError(TimeSeriesManager._ERR_NAN_VALUE))
         return value
 
     @staticmethod
     def _is_number_string(identifier: str) -> bool:
-        """Returns True if given identifier can be cast to float"""
+        """Returns True if given identifier can be cast to float."""
         try:
             float(identifier)
             return True
@@ -128,16 +222,25 @@ class TimeSeriesManager:
             return False
 
     @staticmethod
-    def _create_timeseries_from_value(value: Union[int, float]) -> tuple[str, pd.DataFrame]:
-        """Returns name and dataframe for a new static timeseries created from the given `value`"""
+    def _create_timeseries_from_value(value: int | float) -> tuple[str, pd.DataFrame]:
+        """Returns name and dataframe for a new static timeseries created from the given `value`.
+
+        Args:
+            value: the static value of the timeseries to be created
+
+        Returns:
+            tuple of name & dataframe
+
+        Raises:
+            TimeSeriesError: if given value is NaN, logged with level "ERROR"
+        """
         if math.isnan(value):
             raise log_error(TimeSeriesError(TimeSeriesManager._ERR_NAN_VALUE))
         data = pd.DataFrame({0: [INT64_MIN, INT64_MAX], 1: [value, value]})
         return TimeSeriesManager._CONSTANT_IDENTIFIER.format(value), data
 
-    def get_series_id_by_identifier(self, identifier: Union[str, int, float]) -> int:
-        """
-        Returns id for a previously stored time series by given `identifier`
+    def get_series_id_by_identifier(self, identifier: str | int | float) -> int:
+        """Returns id for a previously stored time series by given `identifier`.
 
         Args:
             identifier: to get the unique ID for
@@ -146,20 +249,20 @@ class TimeSeriesManager:
             unique ID for the given identifier
 
         Raises:
-            TimeSeriesException: if identifier was not yet registered
+            TimeSeriesError: if identifier was not yet registered, logged with level "ERROR"
         """
         if not self._time_series_is_registered(identifier):
             raise log_error(TimeSeriesError(self._ERR_UNREGISTERED_SERIES.format(identifier)))
-        return self._series_by_id.get(identifier)[Entry.ID]
+        return self._series_by_id.get(identifier)[Entry.ID]  # type: ignore[index]
 
     def get_all_series(self) -> list[tuple[int, str, pd.DataFrame]]:
-        """Returns iterator over id, name and dataframe of all stored series"""
+        """Returns iterator over id, name and dataframe of all stored series."""
         if len(self._series_by_id) == 0:
             log().warning(self._WARN_NO_DATA)
         return [(v[Entry.ID], v[Entry.NAME], v[Entry.DATA]) for v in self._series_by_id.values()]
 
     def reconstruct_time_series(self, timeseries: list[InputData.TimeSeriesDao]) -> None:
-        """Reconstructs and stores time series from given list of `timeseries_dao`"""
+        """Reconstructs and stores time series from given list of `timeseries_dao`."""
         for one_series in timeseries:
             self._id_count += 1
             reconstructed = {Entry.ID: one_series.series_id}
@@ -175,7 +278,8 @@ class TimeSeriesManager:
                 )
             self._series_by_id[one_series.series_id] = reconstructed
 
-    def _get_cleaned_file_name(self, timeseries_name: str):
+    def _get_cleaned_file_name(self, timeseries_name: str) -> str:
+        """Ensure given file name has CSV file ending."""
         if Path(timeseries_name).suffix.lower() == CSV_FILE_SUFFIX:
             filename = Path(timeseries_name).name
         else:
@@ -184,7 +288,18 @@ class TimeSeriesManager:
 
     def get_reconstructed_series_by_id(self, series_id: int) -> str:
         """Return name or path for given `series_id` if series these are identified by their number.
-        Use this only if series were added via `reconstruct_time_series`"""
+
+        Use this only if series were added via `reconstruct_time_series`
+
+        Args:
+            series_id: number of series
+
+        Returns:
+            name or path of time series
+
+        Raises:
+            TimeSeriesError: if series was not registered during `reconstruct_time_series`, logged with level "ERROR"
+        """
         if series_id < 0 or series_id > self._id_count:
-            raise log_error(TimeSeriesError(self._ERR_UNREGISTERED_SERIES.format(series_id)))
+            raise log_error(TimeSeriesError(self._ERR_UNREGISTERED_SERIES_RE.format(series_id)))
         return self._series_by_id[series_id][Entry.NAME]

fameio/time.py

@@ -1,13 +1,17 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 import datetime as dt
 import math
 import re
 from enum import Enum, auto
-from typing import Union
+from typing import Any
 
+from fameio.input import InputError
 from fameio.logs import log_error
+from fameio.output import OutputError
 
 START_IN_REAL_TIME = "2000-01-01_00:00:00"
 DATE_FORMAT = "%Y-%m-%d_%H:%M:%S"
@@ -15,12 +19,12 @@ DATE_REGEX = re.compile("[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]{2}:[0-9]{2}:[0-9]{2}")
 FAME_FIRST_DATETIME = dt.datetime.strptime(START_IN_REAL_TIME, DATE_FORMAT)
 
 
-class ConversionError(Exception):
-    """Indicates that something went wrong during time stamp conversion"""
+class ConversionError(InputError, OutputError):
+    """Indicates that time stamp conversion failed."""
 
 
 class TimeUnit(Enum):
-    """Time units defined in FAME"""
+    """Time units defined in FAME."""
 
     SECONDS = auto()
     MINUTES = auto()
@@ -32,7 +36,7 @@ class TimeUnit(Enum):
 
 
 class Constants:
-    """Time steps in FAME simulations associated with corresponding TimeUnits"""
+    """Time steps in FAME simulations associated with corresponding TimeUnits."""
 
     FIRST_YEAR = 2000
     STEPS_PER_SECOND = 1
@@ -45,9 +49,9 @@ class Constants:
     STEPS_PER_DAY = STEPS_PER_HOUR * HOURS_PER_DAY
     STEPS_PER_YEAR = STEPS_PER_DAY * DAYS_PER_YEAR
     STEPS_PER_WEEK = STEPS_PER_DAY * 7
-    STEPS_PER_MONTH = STEPS_PER_YEAR / 12
+    STEPS_PER_MONTH = int(STEPS_PER_YEAR / 12)
 
-    steps_per_unit = {
+    steps_per_unit: dict[TimeUnit, int] = {
         TimeUnit.SECONDS: STEPS_PER_SECOND,
         TimeUnit.MINUTES: STEPS_PER_MINUTE,
         TimeUnit.HOURS: STEPS_PER_HOUR,
@@ -59,7 +63,7 @@ class Constants:
 
 
 class FameTime:
-    """Handles conversion of TimeSteps and TimeDurations into TimeStamps and vice versa"""
+    """Handles conversion of TimeSteps and TimeDurations into TimeStamps and vice versa."""
 
     _TIME_UNIT_UNKNOWN = "TimeUnit conversion of '{}' not implemented."
     _FORMAT_INVALID = "'{}' is not recognised as time stamp string - check its format."
@@ -70,7 +74,18 @@ class FameTime:
 
     @staticmethod
     def convert_datetime_to_fame_time_step(datetime_string: str) -> int:
-        """Converts real Datetime string to FAME time step"""
+        """Converts Datetime string to FAME time step.
+
+        Args:
+            datetime_string: a datetime in FAME formatting
+
+        Returns:
+            corresponding FAME time step
+
+        Raises:
+            ConversionError: if string could not be interpreted or does not represent a valid FAME time step,
+                logged with level "ERROR"
+        """
         if not FameTime.is_datetime(datetime_string):
             raise log_error(ConversionError(FameTime._FORMAT_INVALID.format(datetime_string)))
         datetime = FameTime._convert_to_datetime(datetime_string)
@@ -85,7 +100,17 @@ class FameTime:
 
     @staticmethod
     def _convert_to_datetime(datetime_string: str) -> dt.datetime:
-        """Converts given `datetime_string` to real-world datetime"""
+        """Converts given `datetime_string` in FAME formatting to real-world datetime.
+
+        Args:
+            datetime_string: to be converted to datetime
+
+        Returns:
+            datetime representation of provided string
+
+        Raises:
+            ConversionError: if provided string could not be converted, logged with level "ERROR"
+        """
         try:
             return dt.datetime.strptime(datetime_string, DATE_FORMAT)
         except ValueError as e:
@@ -93,9 +118,17 @@ class FameTime:
 
     @staticmethod
     def convert_fame_time_step_to_datetime(fame_time_steps: int, date_format: str = DATE_FORMAT) -> str:
-        """
-        Converts given `fame_time_steps` to corresponding real-world datetime string in `date_format`,
-        raises ConversionException if invalid `date_format` received.
+        """Converts given `fame_time_steps` to corresponding real-world datetime string in `date_format`.
+
+        Args:
+            fame_time_steps: an integer representing time in FAME's internal format
+            date_format: to be used for datetime representation
+
+        Returns:
+            string representing the real-world datetime of the provided time steps
+
+        Raises:
+            ConversionError: if `date_format` is invalid, logged with level "ERROR"
         """
         years_since_start_time = math.floor(fame_time_steps / Constants.STEPS_PER_YEAR)
         current_year = years_since_start_time + Constants.FIRST_YEAR
@@ -110,22 +143,33 @@ class FameTime:
 
     @staticmethod
     def convert_time_span_to_fame_time_steps(value: int, unit: TimeUnit) -> int:
-        """Converts value of `TimeUnit.UNIT` to fame time steps"""
+        """Converts value of `TimeUnit.UNIT` to FAME time steps.
+
+        Args:
+            value: amount of the units to be converted
+            unit: base time unit
+
+        Returns:
+            FAME time steps equivalent of `value x unit`
+
+        Raises:
+            ConversionError: if an unknown time unit is used, logged with level "ERROR"
+        """
         steps = Constants.steps_per_unit.get(unit)
         if steps:
             return steps * value
         raise log_error(ConversionError(FameTime._TIME_UNIT_UNKNOWN.format(unit)))
 
     @staticmethod
-    def is_datetime(string: str) -> bool:
-        """Returns `True` if given `string` matches Datetime string format and can be converted to FAME time step"""
+    def is_datetime(string: Any) -> bool:
+        """Returns `True` if given `string` matches Datetime string format and can be converted to FAME time step."""
         if isinstance(string, str):
             return DATE_REGEX.fullmatch(string.strip()) is not None
         return False
 
     @staticmethod
-    def is_fame_time_compatible(value: Union[int, str]) -> bool:
-        """Returns `True` if given int or string `value` can be converted to a FAME time step"""
+    def is_fame_time_compatible(value: int | str) -> bool:
+        """Returns `True` if given int or string `value` can be converted to a FAME time step."""
         if isinstance(value, int):
             return True
         if isinstance(value, str):
@@ -134,7 +178,7 @@ class FameTime:
 
     @staticmethod
     def _is_integer(string: str) -> bool:
-        """Returns `True` if given string can be interpreted as integer"""
+        """Returns `True` if given string can be interpreted as integer."""
         try:
             int(string)
         except ValueError:
@@ -142,14 +186,24 @@ class FameTime:
         return True
 
     @staticmethod
-    def convert_string_if_is_datetime(value: Union[int, str]) -> int:
-        """
-        Returns FAME time steps If given `value` is a valid FAME datetime string it is converted to FAME time steps;
-        Or, if given `value` is an integer, it is returned without modification.
-        Raises an Exception if given `value` is neither a valid FAME datetime string nor an integer value
+    def convert_string_if_is_datetime(value: int | str) -> int:
+        """Returns FAME time steps of given `value`.
+
+        If it is a valid FAME datetime string it is converted to FAME time steps.
+        Else if given `value` is an integer, it is returned without modification.
+
+        Args:
+            value: to be converted
+
+        Returns:
+            FAME time steps equivalent of provided value
+
+        Raises:
+            ConversionError: if given `value` is neither a FAME datetime string nor an integer value,
+                logged with level "ERROR"
         """
         if FameTime.is_datetime(value):
-            return int(FameTime.convert_datetime_to_fame_time_step(value))
+            return int(FameTime.convert_datetime_to_fame_time_step(value))  # type: ignore[arg-type]
         try:
             return int(value)
         except ValueError as e:

fameio/tools.py

@@ -1,28 +1,68 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 from pathlib import Path
-from typing import Any, Union
+from typing import Any
+
+from fameio.logs import log_error
+
+CSV_FILE_SUFFIX = ".csv"
+
+_ERR_INVALID_PATTERN = "Pattern '{}' cannot be used here due to: '{}'"
 
 
 def keys_to_lower(dictionary: dict[str, Any]) -> dict[str, Any]:
-    """Returns new dictionary content of given `dictionary` but its top-level `keys` in lower case"""
+    """Returns new dictionary content of given `dictionary` but its top-level `keys` in lower case."""
     return {keys.lower(): value for keys, value in dictionary.items()}
 
 
 def ensure_is_list(value: Any) -> list:
-    """Returns a list: Either the provided `value` if it is a list, or a new list containing the provided value"""
+    """Returns a list: Either the provided `value` if it is a list, or a new list containing the provided value."""
     if isinstance(value, list):
         return value
     return [value]
 
 
-def ensure_path_exists(path: Union[Path, str]):
-    """Creates a specified path if not already existent"""
+def ensure_path_exists(path: Path | str):
+    """Creates a specified path if not already existent."""
     Path(path).mkdir(parents=True, exist_ok=True)
 
 
 def clean_up_file_name(name: str) -> str:
-    """Returns given `name` with replacements defined in `replace_map`"""
-    replace_map = {" ": "_", ":": "_", "/": "-"}
-    return name.translate(str.maketrans(replace_map))
+    """Returns given `name` replacing spaces and colons with underscore, and slashed with a dash."""
+    translation_table = str.maketrans({" ": "_", ":": "_", "/": "-"})
+    return name.translate(translation_table)
+
+
+def get_csv_files_with_pattern(base_path: Path, pattern: str) -> list[Path]:
+    """Find all csv files matching the given `pattern` based on the given `base_path`.
+
+    Args:
+        base_path: to start the search from
+        pattern: to match the files against that are to be found
+
+    Returns:
+        Full file paths for files ending with ".csv" and matching the given pattern
+
+    Raises:
+        ValueError: if pattern cannot be used to search path, logged with level "ERROR"
+    """
+    try:
+        return [file for file in base_path.glob(pattern) if file.suffix.lower() == CSV_FILE_SUFFIX]
+    except NotImplementedError as e:
+        raise log_error(ValueError(_ERR_INVALID_PATTERN.format(pattern, e))) from e
+
+
+def extend_file_name(original_file: Path, appendix: str) -> Path:
+    """Return original file path, but appending `FILE_NAME_APPENDIX` before the suffix.
+
+    Args:
+        original_file: from which to derive the new path
+        appendix: to be added to the end of the file name before the suffix
+
+    Returns:
+        new file path including the appendix in the file name
+    """
+    return Path(original_file.parent, original_file.stem + appendix + original_file.suffix)