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

fameio/output/input_dao.py

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 import ast
-from typing import Any, Optional
+from typing import Any
 
 from fameprotobuf.data_storage_pb2 import DataStorage
 from fameprotobuf.field_pb2 import NestedField
@@ -10,11 +10,12 @@ from fameprotobuf.input_file_pb2 import InputData
 
 from fameio.input.scenario import GeneralProperties, Agent, Contract, Scenario
 from fameio.input.schema import Schema, AttributeSpecs, AttributeType
-from fameio.logs import log
-from fameio.series import TimeSeriesManager
+from fameio.logs import log_error
+from fameio.output import OutputError
+from fameio.series import TimeSeriesManager, TimeSeriesError
 
 
-class InputConversionError(Exception):
+class InputConversionError(OutputError):
     """Indicates an error during reconstruction of input from its protobuf representation"""
 
 
@@ -23,6 +24,8 @@ class InputDao:
 
     _ERR_NO_INPUTS = "No input data found on file."
     _ERR_MULTIPLE_INPUTS = "File corrupt. More than one input section found on file."
+    _ERR_NO_SCHEMA = "No schema found on file - cannot recover inputs."
+    _ERR_SERIES_MISSING = "References time series '{}' was not registered on file."
 
     _FIELD_NAME_MAP: dict = {
         AttributeType.STRING: "string_values",
@@ -39,7 +42,6 @@ class InputDao:
     def __init__(self) -> None:
         self._inputs: list[InputData] = []
         self._timeseries_manager: TimeSeriesManager = TimeSeriesManager()
-        self._schema: Optional[Schema] = None
 
     def store_inputs(self, data_storages: list[DataStorage]) -> None:
         """
@@ -58,16 +60,17 @@ class InputDao:
             recovered timeseries and scenario
 
         Raises:
-            InputConversionException: if inputs could not be recovered
+            InputConversionError: if inputs could not be recovered, logged with level "ERROR"
+            InputError: if scenario in file is incompatible with this version of fameio, logged with level "ERROR"
         """
         input_data = self._get_input_data()
-        self._schema = self._get_schema(input_data)
-        scenario = Scenario(self._schema, self._get_general_properties(input_data))
+        schema = self._get_schema(input_data)
+        scenario = Scenario(schema, self._get_general_properties(input_data))
         for contract in self._get_contracts(input_data):
             scenario.add_contract(contract)
 
         self._init_timeseries(input_data)
-        for agent in self._get_agents(input_data):
+        for agent in self._get_agents(input_data, schema):
             scenario.add_agent(agent)
 
         return self._timeseries_manager, scenario
@@ -77,14 +80,12 @@ class InputDao:
         Check that exactly one previously extracted input data exist, otherwise raises an exception
 
         Raises:
-            InputConversionException: if no or more than one input is present
+            InputConversionException: if no or more than one input is present, logged with level "ERROR"
         """
         if not self._inputs:
-            log().error(self._ERR_NO_INPUTS)
-            raise InputConversionError(self._ERR_NO_INPUTS)
+            raise log_error(InputConversionError(self._ERR_NO_INPUTS))
         if len(self._inputs) > 1:
-            log().error(self._ERR_MULTIPLE_INPUTS)
-            raise InputConversionError(self._ERR_MULTIPLE_INPUTS)
+            raise log_error(InputConversionError(self._ERR_MULTIPLE_INPUTS))
         return self._inputs[0]
 
     @staticmethod
@@ -122,8 +123,21 @@ class InputDao:
         """Read timeseries from given `input_data` and initialise TimeSeriesManager"""
         self._timeseries_manager.reconstruct_time_series(list(input_data.time_series))
 
-    def _get_agents(self, input_data: InputData) -> list[Agent]:
-        """Read and return Agents from given `input_data`"""
+    def _get_agents(self, input_data: InputData, schema: Schema) -> list[Agent]:
+        """
+        Read and return Agents from given `input_data`
+
+        Args:
+            input_data: to read agents from
+            schema: corresponding to the agent definitions
+
+        Returns:
+            all extracted agents
+
+        Raises:
+            InputError: if agents cannot be reconstructed, logged with level "ERROR"
+            InputConversionError: if attributes could not be reconstructed, logged with level "ERROR"
+        """
         agents = []
         for agent_dao in input_data.agents:
             agent = Agent(
@@ -132,29 +146,56 @@ class InputDao:
                 metadata=ast.literal_eval(agent_dao.metadata) if agent_dao.metadata else None,
             )
             attribute_dict = self._get_attributes(
-                list(agent_dao.fields), self._schema.agent_types[agent_dao.class_name].attributes
+                list(agent_dao.fields), schema.agent_types[agent_dao.class_name].attributes
             )
             agent.init_attributes_from_dict(attribute_dict)
             agents.append(agent)
         return agents
 
     def _get_attributes(self, fields: list[NestedField], schematics: dict[str, AttributeSpecs]) -> dict[str, Any]:
-        """Read and return Attributes as Dictionary from given list of fields"""
+        """
+        Read and return all Attributes as Dictionary from given list of fields
+
+        Args:
+            fields: data fields representing attributes
+            schematics: description of the attributes associated by name
+
+        Returns:
+            all recovered attributes and their associated values
+
+        Raises:
+            InputConversionError: if attributes could not be reconstructed, logged with level "ERROR"
+        """
         attributes: dict[str, Any] = {}
         for field in fields:
             attributes[field.field_name] = self._get_field_value(field, schematics[field.field_name])
         return attributes
 
     def _get_field_value(self, field: NestedField, schematic: AttributeSpecs) -> Any:
-        """Extracts and returns value(s) of given `field`"""
+        """
+        Extracts and returns value(s) of given `field`
+
+        Args:
+            field: to extract the value(s) from
+            schematic: describing the data type of this field
+
+        Returns:
+            value(s) of provided field
+
+        Raises:
+            InputConversionError: if TimeSeries could not be found, logged with level "ERROR"
+        """
         attribute_type: AttributeType = schematic.attr_type
-        value = getattr(field, self._FIELD_NAME_MAP[attribute_type])
         if attribute_type is AttributeType.TIME_SERIES:
-            return self._timeseries_manager.get_reconstructed_series_by_id(field.series_id)
+            try:
+                return self._timeseries_manager.get_reconstructed_series_by_id(field.series_id)
+            except TimeSeriesError as e:
+                raise log_error(InputConversionError(self._ERR_SERIES_MISSING.format(field.series_id))) from e
         if attribute_type is AttributeType.BLOCK:
             if schematic.is_list:
                 return [self._get_attributes(list(entry.fields), schematic.nested_attributes) for entry in field.fields]
             return self._get_attributes(list(field.fields), schematic.nested_attributes)
+        value = getattr(field, self._FIELD_NAME_MAP[attribute_type])
         if schematic.is_list:
             return list(value)
         return list(value)[0]

fameio/output/output_dao.py

@@ -1,7 +1,9 @@
-# SPDX-FileCopyrightText: 2023 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
-from typing import Iterable, Optional
+from __future__ import annotations
+
+from typing import Iterable
 
 import pandas as pd
 from fameprotobuf.data_storage_pb2 import DataStorage
@@ -15,6 +17,16 @@ class OutputDAO:
     """Grants convenient access to content of Output protobuf messages for given DataStorages"""
 
     def __init__(self, data_storages: list[DataStorage], agent_type_log: AgentTypeLog) -> None:
+        """
+        Initialise a new OutputDAO
+
+        Args:
+            data_storages: to grant access to by this DAO
+            agent_type_log: new types of agents that might come up in the associated data_storages
+
+        Raises:
+            AgentTypeError: if duplicate agent definitions occur, logged with level "ERROR"
+        """
         self._agent_type_log = agent_type_log
         outputs = self._extract_output_from_data_storages(data_storages)
         self._agent_type_log.update_agents(self._extract_new_agent_types(outputs))
@@ -40,7 +52,7 @@ class OutputDAO:
         list_of_series_lists = [output.series for output in outputs if len(output.series) > 0]
         list_of_series = [series for sublist in list_of_series_lists for series in sublist]
 
-        series_per_class_name = {}
+        series_per_class_name: dict[str, list[Output.Series]] = {}
         for series in list_of_series:
             if series.class_name not in series_per_class_name:
                 series_per_class_name[series.class_name] = []
@@ -59,11 +71,21 @@ class OutputDAO:
         sorted_dict = sorted(length_per_agent_types.items(), key=lambda item: item[1])
         return [agent_name for agent_name, _ in sorted_dict]
 
-    def get_agent_data(self, agent_name: str, data_transformer: DataTransformer) -> dict[Optional[str], pd.DataFrame]:
+    def get_agent_data(self, agent_name: str, data_transformer: DataTransformer) -> dict[str | None, pd.DataFrame]:
         """
         Returns DataFrame(s) containing all data of given `agent` - data is removed after the first call
         Depending on the chosen ResolveOption the dict contains one DataFrame for the simple (and merged columns),
         or, in `SPLIT` mode, additional DataFrames mapped to each complex column's name.
+
+        Args:
+            agent_name: name of agent whose data are to be returned
+            data_transformer: to handle data transformation
+
+        Returns:
+            output data for requested agent: on data frame for all simple columns, any one for each complex column
+
+        Raises:
+            AgentTypeError: if type of agent was not yet registered, logged with level "ERROR"
         """
         agent_series = self._all_series.pop(agent_name) if agent_name in self._all_series else []
         agent_type = self._agent_type_log.get_agent_type(agent_name)

fameio/output/reader.py

@@ -11,21 +11,24 @@ from fameprotobuf.data_storage_pb2 import DataStorage
 from google.protobuf.message import DecodeError
 
 import fameio
-from fameio.logs import log, log_critical_and_raise
+from fameio.logs import log, log_critical, log_error
+from fameio.output import OutputError
 
 
-class ProtobufReaderError(Exception):
+class ProtobufReaderError(OutputError):
     """Indicates an error while reading a protobuf file"""
 
 
 class Reader(ABC):
     """Abstract base class for protobuf file readers"""
 
-    _WARN_NO_HEADER = "No header recognised in file. File might be deprecated or corrupted."  # noqa
+    _ERR_FILE_READ = "Could not read file content."
+    _ERR_HEADER_UNRECOGNISED = ""
     _ERR_FILE_CORRUPT_NEGATIVE_LENGTH = "Corrupt file, message length must be positive."
     _ERR_FILE_CORRUPT_MISSING_DATA = "Trying to read corrupt file caused by inconsistent message length."
     _ERR_UNSUPPORTED_MODE = "Ignoring memory saving mode: not supported for files created with `fame-core<1.4`."
     _ERR_PARSING_FAILED = "File Corrupt. Could not parse file content."
+    _WARN_NO_HEADER = "No header recognised in file. File might be deprecated or corrupted."
     _DEBUG_FILE_END_REACHED = "Reached expected end of file."
 
     _HEADER_LENGTH = 30
@@ -44,7 +47,7 @@ class Reader(ABC):
     @staticmethod
     @final
     def _raise_error(error_message: str) -> NoReturn:
-        log_critical_and_raise(ProtobufReaderError(error_message))
+        raise log_critical(ProtobufReaderError(error_message))
 
     def __init__(self, file: IO, read_single) -> None:
         self._file = file
@@ -52,7 +55,15 @@ class Reader(ABC):
 
     @abstractmethod
     def read(self) -> list[DataStorage]:
-        """Reads associated filestream and returns one or multiple DataStorage(s) or empty list"""
+        """
+        Reads associated filestream and returns one or multiple DataStorage(s) or empty list
+
+        Returns:
+            one or multiple DataStorage protobuf object(s) read from file
+
+        Raises:
+            ProtobufReaderError: if file is corrupted in any way, logged with level "ERROR"
+        """
 
     @staticmethod
     def get_reader(file: IO, read_single: bool = False) -> Reader:
@@ -65,13 +76,26 @@ class Reader(ABC):
 
         Returns:
             Reader that can read the specified file
+
+        Raises:
+            ProtobufReaderError: if file has an unsupported header,logged with level "CRITICAL"
         """
         log().debug("Reading file headers...")
         try:
-            header = file.read(Reader._HEADER_LENGTH).decode(Reader.HEADER_ENCODING)
-            return Reader._READER_HEADERS[header](file, read_single)
-        except (KeyError, UnicodeDecodeError):
-            return Reader._READER_HEADERS[None](file, read_single)
+            header_content = file.read(Reader._HEADER_LENGTH)
+        except ValueError as e:
+            raise log_critical(ProtobufReaderError(Reader._ERR_FILE_READ)) from e
+
+        try:
+            header = header_content.decode(Reader.HEADER_ENCODING)
+        except UnicodeDecodeError:
+            header = None
+            log().warning(Reader._WARN_NO_HEADER)
+
+        if header not in Reader._READER_HEADERS:
+            header = None
+
+        return Reader._READER_HEADERS[header](file, read_single)
 
     @final
     def _read_message_length(self) -> int:
@@ -85,29 +109,50 @@ class Reader(ABC):
         return message_length_int
 
     @final
-    def _read_data_storage_message(self, message_length: int = None) -> DataStorage:
+    def _read_data_storage_message(self, message_length: int | None = None) -> DataStorage:
         """
         Returns given `data_storage` read from current file position and following `message_length` bytes.
         If `message_length` is omitted, the rest of the file is read. If no message is found, None is returned.
+
+        Args:
+            message_length: amounts of bytes to read - must correspond to the next DataStorage message in file
+
+        Returns:
+            Read and de-serialised DataStorage
+
+        Raises:
+            ProtobufReaderError: if message_length is corrupt or file is corrupt, logged with level "ERROR"
         """
         if message_length is None:
             message = self._file.read()
         elif message_length > 0:
             message = self._file.read(message_length)
         else:
-            raise IOError(self._ERR_FILE_CORRUPT_NEGATIVE_LENGTH)
+            raise log_error(ProtobufReaderError(self._ERR_FILE_CORRUPT_NEGATIVE_LENGTH))
         if message_length and len(message) != message_length:
-            log().error(self._ERR_FILE_CORRUPT_MISSING_DATA)
+            raise log_error(ProtobufReaderError(self._ERR_FILE_CORRUPT_MISSING_DATA))
         return self._parse_to_data_storage(message) if message else None
 
     @staticmethod
     @final
     def _parse_to_data_storage(message: bytes) -> DataStorage:
+        """
+        De-serialises a binary message into a DataStorage protobuf object
+
+        Args:
+            message: to be convert
+
+        Returns:
+            DataStorage initialised from the given message
+
+        Raises:
+            ProtobufReaderError: if message could not be converted, logged with level "ERROR"
+        """
         data_storage = DataStorage()
         try:
             data_storage.ParseFromString(message)
         except DecodeError as e:
-            raise IOError(Reader._ERR_PARSING_FAILED) from e
+            raise log_error(ProtobufReaderError(Reader._ERR_PARSING_FAILED)) from e
         return data_storage
 
 

fameio/output/yaml_writer.py

@@ -5,10 +5,16 @@ from pathlib import Path
 
 import yaml
 
-from fameio.logs import log
+from fameio.logs import log, log_error
+from fameio.output import OutputError
 
-ERR_WRITE_EXCEPTION = "Failed to save dictionary to YAML file `{}`"
-INFO_DESTINATION = "Saving scenario to file at {}"
+_ERR_OPEN_FILE = "Could not open file for reading: '{}'"
+
+_INFO_DESTINATION = "Saving scenario to file at {}"
+
+
+class YamlWriterError(OutputError):
+    """An error occurred during writing a YAML file"""
 
 
 def data_to_yaml_file(data: dict, file_path: Path) -> None:
@@ -18,10 +24,13 @@ def data_to_yaml_file(data: dict, file_path: Path) -> None:
     Args:
         data: to be saved to yaml file
         file_path: at which the file will be created
+
+    Raises:
+        YamlWriterError: if file could not be opened or written, logged with level "ERROR"
     """
-    log().info(INFO_DESTINATION.format(file_path))
+    log().info(_INFO_DESTINATION.format(file_path))
     try:
         with open(file_path, "w", encoding="utf-8") as f:
             yaml.dump(data, f, sort_keys=False, encoding="utf-8")
-    except Exception as e:
-        raise RuntimeError(ERR_WRITE_EXCEPTION.format(file_path)) from e
+    except OSError as e:
+        raise log_error(YamlWriterError(_ERR_OPEN_FILE.format(file_path))) from e

fameio/scripts/__init__.py

@@ -3,6 +3,7 @@ import sys
 
 from fameio.scripts.convert_results import DEFAULT_CONFIG as DEFAULT_CONVERT_CONFIG
 from fameio.scripts.convert_results import run as convert_results
+from fameio.scripts.exception import ScriptError
 from fameio.scripts.make_config import run as make_config
 from fameio.cli.convert_results import handle_args as handle_convert_results_args
 from fameio.cli.make_config import handle_args as handle_make_config_args
@@ -11,10 +12,16 @@ from fameio.cli.make_config import handle_args as handle_make_config_args
 # noinspection PyPep8Naming
 def makeFameRunConfig():
     run_config = handle_make_config_args(sys.argv[1:])
-    make_config(run_config)
+    try:
+        make_config(run_config)
+    except ScriptError as e:
+        raise SystemExit(1) from e
 
 
 # noinspection PyPep8Naming
 def convertFameResults():
     run_config = handle_convert_results_args(sys.argv[1:], DEFAULT_CONVERT_CONFIG)
-    convert_results(run_config)
+    try:
+        convert_results(run_config)
+    except ScriptError as e:
+        raise SystemExit(1) from e

fameio/scripts/convert_results.py

@@ -1,13 +1,18 @@
 #!/usr/bin/env python
+from __future__ import annotations
+
 import sys
 from pathlib import Path
+from typing import Any, BinaryIO
 
 import pandas as pd
 
+from fameio.cli import update_default_config
 from fameio.cli.convert_results import handle_args, CLI_DEFAULTS as DEFAULT_CONFIG
 from fameio.cli.options import Options
-from fameio.cli import update_default_config
-from fameio.logs import log_critical_and_raise, fameio_logger, log
+from fameio.input import InputError
+from fameio.logs import fameio_logger, log, log_error, log_critical
+from fameio.output import OutputError
 from fameio.output.agent_type import AgentTypeLog
 from fameio.output.conversion import apply_time_option, apply_time_merging
 from fameio.output.csv_writer import CsvWriter
@@ -16,53 +21,98 @@ from fameio.output.input_dao import InputDao
 from fameio.output.output_dao import OutputDAO
 from fameio.output.reader import Reader
 from fameio.output.yaml_writer import data_to_yaml_file
+from fameio.scripts.exception import ScriptError
 
-ERR_OUT_OF_MEMORY = "Out of memory. Retry result conversion using `-m` or `--memory-saving` option."
-ERR_MEMORY_SEVERE = "Out of memory despite memory-saving mode. Reduce output interval in `FAME-Core` and rerun model."
+_ERR_OUT_OF_MEMORY = "Out of memory. Retry result conversion using `-m` or `--memory-saving` option."
+_ERR_MEMORY_SEVERE = "Out of memory despite memory-saving mode. Reduce output interval in `FAME-Core` and rerun model."
+_ERR_FILE_OPEN_FAIL = "Could not open file: '{}'"
+_ERR_RECOVER_INPUT = "Could not recover inputs due to an incompatibility with this version of fameio."
+_ERR_FAIL = "Results conversion script failed."
 
-WARN_OUTPUT_MISSING = "Provided file did not contain any output data, only input recovery available."
+_WARN_OUTPUT_SUPPRESSED = "All output data suppressed by agent filter, but there is data available for agent types: {}"
+_WARN_OUTPUT_MISSING = "Provided file did not contain any output data, only input recovery available."
+_INFO_MEMORY_SAVING = "Memory saving mode enabled: Disable on conversion of small files for performance improvements."
 
-INFO_MEMORY_SAVING = "Memory saving mode enabled: Disable on conversion of small files for performance improvements."
-INFO_RECOVERY = "Recovering inputs..."
-INFO_CONVERSION = "Applying time conversion and merging options to extracted files..."
 
+def _read_and_extract_data(config: dict[Options, Any]) -> None:
+    """
+    Read protobuf file, extracts, converts, and saves the converted data; Returns false if no result data was found
 
-def _extract_data(config: dict) -> bool:
-    """Extracts, converts, and saves the converted data; Returns false if no result data was found"""
+    Args:
+        config: script configuration options
+
+    Raises:
+        OutputError: if file could not be opened or converted, logged with level "ERROR"
+    """
     file_path = Path(config[Options.FILE])
+    log().info("Opening file for reading...")
+    try:
+        with open(file_path, "rb") as file_stream:
+            _extract_and_convert_data(config, file_stream, file_path)
+    except OSError as ex:
+        raise log_error(OutputError(_ERR_FILE_OPEN_FAIL.format(file_path))) from ex
+
+
+def _extract_and_convert_data(config: dict[Options, Any], file_stream: BinaryIO, file_path: Path) -> None:
+    """
+    Extracts data from provided input file stream, converts it, and writes the result to output files
+
+    Args:
+        config: script configuration options
+        file_stream: opened input file
+        file_path: path to input file
+
+    Raises:
+        OutputError: if file could not be opened or converted, logged with level "ERROR"
+    """
+    log().info("Reading and extracting data...")
     output_writer = CsvWriter(config[Options.OUTPUT], file_path, config[Options.SINGLE_AGENT_EXPORT])
-    agent_type_log = AgentTypeLog(requested_agents=config[Options.AGENT_LIST])
+    agent_type_log = AgentTypeLog(_agent_name_filter_list=config[Options.AGENT_LIST])
     data_transformer = DataTransformer.build(config[Options.RESOLVE_COMPLEX_FIELD])
+    reader = Reader.get_reader(file=file_stream, read_single=config[Options.MEMORY_SAVING])
+    input_dao = InputDao()
+    while data_storages := reader.read():
+        if config[Options.INPUT_RECOVERY]:
+            input_dao.store_inputs(data_storages)
+        output = OutputDAO(data_storages, agent_type_log)
+        for agent_name in output.get_sorted_agents_to_extract():
+            log().debug(f"Extracting data for {agent_name}...")
+            data_frames = output.get_agent_data(agent_name, data_transformer)
+            if not config[Options.MEMORY_SAVING]:
+                apply_time_merging(data_frames, config[Options.TIME_MERGING])
+                apply_time_option(data_frames, config[Options.TIME])
+            log().debug(f"Writing data for {agent_name}...")
+            output_writer.write_to_files(agent_name, data_frames)
+
+    if config[Options.INPUT_RECOVERY]:
+        _recover_inputs(config, input_dao)
+    if config[Options.MEMORY_SAVING]:
+        _memory_saving_apply_conversions(config, output_writer)
 
-    log().info("Reading and extracting data...")
-    with open(file_path, "rb") as file_stream:
-        reader = Reader.get_reader(file=file_stream, read_single=config[Options.MEMORY_SAVING])
-        input_dao = InputDao()
-        while data_storages := reader.read():
-            if config[Options.INPUT_RECOVERY]:
-                input_dao.store_inputs(data_storages)
-            output = OutputDAO(data_storages, agent_type_log)
-            for agent_name in output.get_sorted_agents_to_extract():
-                log().debug(f"Extracting data for {agent_name}...")
-                data_frames = output.get_agent_data(agent_name, data_transformer)
-                if not config[Options.MEMORY_SAVING]:
-                    apply_time_merging(data_frames, config[Options.TIME_MERGING])
-                    apply_time_option(data_frames, config[Options.TIME])
-                log().debug(f"Writing data for {agent_name}...")
-                output_writer.write_to_files(agent_name, data_frames)
+    if not agent_type_log.has_any_agent_type():
+        if len(agent_type_log.get_agents_with_output()) > 0:
+            log().warning(_WARN_OUTPUT_SUPPRESSED.format(agent_type_log.get_agents_with_output()))
+        else:
+            log().warning(_WARN_OUTPUT_MISSING)
+    log().info("Data conversion completed.")
 
-        if config[Options.INPUT_RECOVERY]:
-            _recover_inputs(config, input_dao)
-        if config[Options.MEMORY_SAVING]:
-            _memory_saving_apply_conversions(config, output_writer)
-        log().info("Data conversion completed.")
-    return agent_type_log.has_any_agent_type()
 
+def _recover_inputs(config: dict[Options, Any], input_dao: InputDao) -> None:
+    """
+    Reads scenario configuration from provided input_dao
 
-def _recover_inputs(config: dict, input_dao: InputDao) -> None:
-    """Reads scenario configuration from provided input_dao"""
-    log().info(INFO_RECOVERY)
-    timeseries, scenario = input_dao.recover_inputs()
+    Args:
+        config: script configuration options
+        input_dao: to recover the input data from
+
+    Raises:
+        OutputError: if inputs could not be recovered or saved to files, logged with level "ERROR"
+    """
+    log().info("Recovering inputs...")
+    try:
+        timeseries, scenario = input_dao.recover_inputs()
+    except InputError as ex:
+        raise log_error(OutputError(_ERR_RECOVER_INPUT)) from ex
     base_path = config[Options.OUTPUT] if config[Options.OUTPUT] is not None else "./"
     series_writer = CsvWriter(
         config_output=Path(base_path, "./recovered"), input_file_path=Path("./"), single_export=False
@@ -71,31 +121,54 @@ def _recover_inputs(config: dict, input_dao: InputDao) -> None:
     data_to_yaml_file(scenario.to_dict(), Path(base_path, "./recovered/scenario.yaml"))
 
 
-def _memory_saving_apply_conversions(config: dict, output_writer: CsvWriter) -> None:
-    """Rewrite result files in memory saving mode: apply time-merging and time conversion options on a per-file basis"""
-    log().info(INFO_CONVERSION)
+def _memory_saving_apply_conversions(config: dict[Options, Any], output_writer: CsvWriter) -> None:
+    """
+    Rewrite result files in memory saving mode: apply time-merging and time conversion options on a per-file basis
+
+    Args:
+        config: script configuration options
+        output_writer: to rewrite the previously written files
+
+    Raises:
+        OutputError: in case files could not be read, converted, or re-written, logged with level "ERROR"
+    """
+    log().info("Applying time conversion and merging options to extracted files...")
     written_files = output_writer.pop_all_file_paths()
     for agent_name, file_path in written_files.items():
-        parsed_data = {None: pd.read_csv(file_path, sep=";", index_col=INDEX)}
+        parsed_data: dict[str | None, pd.DataFrame] = {None: pd.read_csv(file_path, sep=";", index_col=INDEX)}
         apply_time_merging(parsed_data, config[Options.TIME_MERGING])
         apply_time_option(parsed_data, config[Options.TIME])
         output_writer.write_to_files(agent_name, parsed_data)
 
 
-def run(config: dict = None) -> None:
-    """Reads configured file in protobuf format and extracts its content to .CSV and .YAML file(s)"""
+def run(config: dict[Options, Any] | None = None) -> None:
+    """
+    Reads configured file in protobuf format and extracts its content to .CSV and .YAML file(s)
+
+    Args:
+        config: script configuration options
+
+    Raises:
+        ScriptError: if any kind of expected error or a memory error occurred, logged with level "CRITICAL"
+    """
     config = update_default_config(config, DEFAULT_CONFIG)
     fameio_logger(log_level_name=config[Options.LOG_LEVEL], file_name=config[Options.LOG_FILE])
     if config[Options.MEMORY_SAVING]:
-        log().info(INFO_MEMORY_SAVING)
+        log().info(_INFO_MEMORY_SAVING)
+
     try:
-        found_result_data = _extract_data(config)
-        if not found_result_data:
-            log().warning(WARN_OUTPUT_MISSING)
-    except MemoryError:
-        log_critical_and_raise(MemoryError(ERR_MEMORY_SEVERE if config[Options.MEMORY_SAVING] else ERR_OUT_OF_MEMORY))
+        try:
+            _read_and_extract_data(config)
+        except MemoryError as ex:
+            error = OutputError(_ERR_MEMORY_SEVERE if config[Options.MEMORY_SAVING] else _ERR_OUT_OF_MEMORY)
+            raise log_critical(error) from ex
+    except OutputError as ex:
+        raise log_critical(ScriptError(_ERR_FAIL)) from ex
 
 
 if __name__ == "__main__":
     run_config = handle_args(sys.argv[1:])
-    run(run_config)
+    try:
+        run(run_config)
+    except ScriptError as e:
+        raise SystemExit(1) from e

fameio/scripts/convert_results.py.license

@@ -1,3 +1,3 @@
-SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 
 SPDX-License-Identifier: Apache-2.0

fameio/scripts/exception.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+class ScriptError(Exception):
+    """Any kind of expected error that occurred during execution of FAME-Io scripts"""