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

fameio/input/validator.py

@@ -1,24 +1,24 @@
-# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
 
 import math
 from collections import Counter
 from typing import Any
 
+from fameio.input import InputError
 from fameio.input.resolver import PathResolver
 from fameio.input.scenario import Agent, Attribute, Contract, Scenario, StringSet
 from fameio.input.schema import Schema, AttributeSpecs, AttributeType, AgentType
-from fameio.logs import log_error_and_raise, log
+from fameio.logs import log, log_error
 from fameio.series import TimeSeriesManager, TimeSeriesError
 from fameio.time import FameTime
 
 
-class ValidationError(Exception):
+class ValidationError(InputError):
     """Indicates an error occurred during validation of any data with a connected schema"""
 
-    pass
-
 
 class SchemaValidator:
     """Handles validation of scenarios based on a connected `schema`"""
@@ -29,8 +29,8 @@ class SchemaValidator:
     _TYPE_NOT_IMPLEMENTED = "Validation not implemented for AttributeType '{}'."
     _INCOMPATIBLE = "Value '{}' incompatible with {} of Attribute '{}'."
     _DISALLOWED = "Value '{}' not in list of allowed values of Attribute '{}'"
-    _AGENT_MISSING = "Contract mentions Agent with ID '{}' but Agent was not declared."
-    _PRODUCT_MISSING = "Product '{}' not declared in Schema for AgentType '{}'."
+    _AGENT_MISSING = "Agent with ID '{}' was not declared in Scenario but used in Contract: '{}'"
+    _PRODUCT_MISSING = "'{}' is no product of AgentType '{}'. Contract invalid: '{}'"
     _KEY_MISSING = "Required key '{}' missing in dictionary '{}'."
     _ATTRIBUTE_MISSING = "Mandatory attribute '{}' is missing."
     _DEFAULT_IGNORED = "Optional Attribute: '{}': not specified - provided Default ignored for optional Attributes."
@@ -56,7 +56,7 @@ class SchemaValidator:
         Returns:
             a new TimeSeriesManager initialised with validated time series from scenario
         Raises:
-            ValidationException: if an error in the scenario or in timeseries is spotted
+            ValidationError: if an error in the scenario or in timeseries is spotted
         """
         schema = scenario.schema
         agents = scenario.agents
@@ -79,27 +79,29 @@ class SchemaValidator:
         list_of_ids = [agent.id for agent in agents]
         non_unique_ids = [agent_id for agent_id, count in Counter(list_of_ids).items() if count > 1]
         if non_unique_ids:
-            log_error_and_raise(ValidationError(SchemaValidator._AGENT_ID_NOT_UNIQUE.format(non_unique_ids)))
+            raise log_error(ValidationError(SchemaValidator._AGENT_ID_NOT_UNIQUE.format(non_unique_ids)))
 
     @staticmethod
     def ensure_agent_and_timeseries_are_valid(agent: Agent, schema: Schema, timeseries_manager: TimeSeriesManager):
         """Validates given `agent` against `schema` plus loads and validates its timeseries"""
         SchemaValidator.ensure_agent_type_in_schema(agent, schema)
-        SchemaValidator.ensure_is_valid_agent(agent, schema)
+        SchemaValidator.ensure_is_valid_agent(agent, schema, timeseries_manager)
         SchemaValidator.load_and_validate_timeseries(agent, schema, timeseries_manager)
 
     @staticmethod
     def ensure_agent_type_in_schema(agent: Agent, schema: Schema) -> None:
         """Raises exception if type for given `agent` is not specified in given `schema`"""
         if agent.type_name not in schema.agent_types:
-            log_error_and_raise(ValidationError(SchemaValidator._AGENT_TYPE_UNKNOWN.format(agent.type_name)))
+            raise log_error(ValidationError(SchemaValidator._AGENT_TYPE_UNKNOWN.format(agent.type_name)))
 
     @staticmethod
-    def ensure_is_valid_agent(agent: Agent, schema: Schema) -> None:
+    def ensure_is_valid_agent(agent: Agent, schema: Schema, timeseries_manager: TimeSeriesManager) -> None:
         """Raises an exception if given `agent` does not meet the specified `schema` requirements"""
         scenario_attributes = agent.attributes
         schema_attributes = SchemaValidator._get_agent(schema, agent.type_name).attributes
-        SchemaValidator._ensure_mandatory_present(scenario_attributes, schema_attributes)
+        missing_default_series = SchemaValidator._check_mandatory_or_default(scenario_attributes, schema_attributes)
+        for missing_series in missing_default_series:
+            timeseries_manager.register_and_validate(missing_series)
         SchemaValidator._ensure_attributes_exist(scenario_attributes, schema_attributes)
         SchemaValidator._ensure_value_and_type_match(scenario_attributes, schema_attributes)
 
@@ -108,22 +110,30 @@ class SchemaValidator:
         """Returns agent specified by `name` or raises Exception if this agent is not present in given `schema`"""
         if name in schema.agent_types:
             return schema.agent_types[name]
-        else:
-            log_error_and_raise(ValidationError(SchemaValidator._AGENT_TYPE_UNKNOWN.format(name)))
+        raise log_error(ValidationError(SchemaValidator._AGENT_TYPE_UNKNOWN.format(name)))
 
     @staticmethod
-    def _ensure_mandatory_present(attributes: dict[str, Attribute], specifications: dict[str, AttributeSpecs]) -> None:
+    def _check_mandatory_or_default(
+        attributes: dict[str, Attribute],
+        specifications: dict[str, AttributeSpecs],
+    ) -> list[str | float]:
         """
         Raises Exception if in given list of `specifications` at least one item is mandatory,
         provides no defaults and is not contained in given `attributes` dictionary
+
+        Returns:
+            list of time series defaults used in scenario
         """
+        missing_series_defaults: list[str | float] = []
         for name, specification in specifications.items():
             if name not in attributes:
                 if specification.is_mandatory:
                     if not specification.has_default_value:
-                        log_error_and_raise(
+                        raise log_error(
                             ValidationError(SchemaValidator._ATTRIBUTE_MISSING.format(specification.full_name))
                         )
+                    if specification.attr_type == AttributeType.TIME_SERIES:
+                        missing_series_defaults.append(specification.default_value)  # type: ignore[arg-type]
                 else:
                     if specification.has_default_value:
                         log().warning(SchemaValidator._DEFAULT_IGNORED.format(specification.full_name))
@@ -133,16 +143,21 @@ class SchemaValidator:
                 attribute = attributes[name]
                 if specification.is_list:
                     for entry in attribute.nested_list:
-                        SchemaValidator._ensure_mandatory_present(entry, specification.nested_attributes)
+                        missing_series_defaults.extend(
+                            SchemaValidator._check_mandatory_or_default(entry, specification.nested_attributes)
+                        )
                 else:
-                    SchemaValidator._ensure_mandatory_present(attribute.nested, specification.nested_attributes)
+                    missing_series_defaults.extend(
+                        SchemaValidator._check_mandatory_or_default(attribute.nested, specification.nested_attributes)
+                    )
+        return missing_series_defaults
 
     @staticmethod
     def _ensure_attributes_exist(attributes: dict[str, Attribute], specifications: dict[str, AttributeSpecs]) -> None:
         """Raises exception any entry of given `attributes` has no corresponding type `specification`"""
         for name, attribute in attributes.items():
             if name not in specifications:
-                log_error_and_raise(ValidationError(SchemaValidator._ATTRIBUTE_UNKNOWN.format(attribute)))
+                raise log_error(ValidationError(SchemaValidator._ATTRIBUTE_UNKNOWN.format(attribute)))
             if attribute.has_nested:
                 specification = specifications[name]
                 SchemaValidator._ensure_attributes_exist(attribute.nested, specification.nested_attributes)
@@ -163,10 +178,10 @@ class SchemaValidator:
                 type_spec = specification.attr_type
                 if not SchemaValidator._is_compatible(specification, value):
                     message = SchemaValidator._INCOMPATIBLE.format(value, type_spec, specification.full_name)
-                    log_error_and_raise(ValidationError(message))
+                    raise log_error(ValidationError(message))
                 if not SchemaValidator._is_allowed_value(specification, value):
                     message = SchemaValidator._DISALLOWED.format(value, specification.full_name)
-                    log_error_and_raise(ValidationError(message))
+                    raise log_error(ValidationError(message))
             if attribute.has_nested:
                 SchemaValidator._ensure_value_and_type_match(attribute.nested, specification.nested_attributes)
             if attribute.has_nested_list:
@@ -186,8 +201,7 @@ class SchemaValidator:
                 if not SchemaValidator._is_compatible_value(attribute_type, value):
                     return False
             return True
-        else:
-            return (not is_list) and SchemaValidator._is_compatible_value(attribute_type, value_or_values)
+        return (not is_list) and SchemaValidator._is_compatible_value(attribute_type, value_or_values)
 
     @staticmethod
     def _is_compatible_value(attribute_type: AttributeType, value) -> bool:
@@ -198,24 +212,22 @@ class SchemaValidator:
             return False
         if attribute_type is AttributeType.LONG:
             return isinstance(value, int)
-        elif attribute_type is AttributeType.DOUBLE:
+        if attribute_type is AttributeType.DOUBLE:
             return isinstance(value, (int, float)) and not math.isnan(value)
-        elif attribute_type in (AttributeType.ENUM, AttributeType.STRING, AttributeType.STRING_SET):
+        if attribute_type in (AttributeType.ENUM, AttributeType.STRING, AttributeType.STRING_SET):
             return isinstance(value, str)
-        elif attribute_type is AttributeType.TIME_STAMP:
+        if attribute_type is AttributeType.TIME_STAMP:
             return FameTime.is_fame_time_compatible(value)
-        elif attribute_type is AttributeType.TIME_SERIES:
+        if attribute_type is AttributeType.TIME_SERIES:
             return isinstance(value, (str, int)) or (isinstance(value, float) and not math.isnan(value))
-        else:
-            log_error_and_raise(ValidationError(SchemaValidator._TYPE_NOT_IMPLEMENTED.format(attribute_type)))
+        raise log_error(ValidationError(SchemaValidator._TYPE_NOT_IMPLEMENTED.format(attribute_type)))
 
     @staticmethod
     def _is_allowed_value(attribute: AttributeSpecs, value) -> bool:
         """Returns True if `value` matches an entry of given `Attribute`'s value list or if this list is empty"""
         if not attribute.values:
             return True
-        else:
-            return value in attribute.values
+        return value in attribute.values
 
     @staticmethod
     def load_and_validate_timeseries(agent: Agent, schema: Schema, timeseries_manager: TimeSeriesManager) -> None:
@@ -228,7 +240,7 @@ class SchemaValidator:
             timeseries_manager: to be filled with timeseries
 
         Raises:
-            ValidationException: if timeseries is not found, ill-formatted or invalid
+            ValidationError: if timeseries is not found, ill-formatted or invalid
         """
         scenario_attributes = agent.attributes
         schema_attributes = SchemaValidator._get_agent(schema, agent.type_name).attributes
@@ -245,10 +257,10 @@ class SchemaValidator:
                 attribute_type = specification.attr_type
                 if attribute_type is AttributeType.TIME_SERIES:
                     try:
-                        manager.register_and_validate(attribute.value)
+                        manager.register_and_validate(attribute.value)  # type: ignore[arg-type]
                     except TimeSeriesError as e:
                         message = SchemaValidator._TIME_SERIES_INVALID.format(specification.full_name)
-                        log_error_and_raise(ValidationError(message, e))
+                        raise log_error(ValidationError(message)) from e
             if attribute.has_nested:
                 SchemaValidator._ensure_valid_timeseries(attribute.nested, specification.nested_attributes, manager)
             if attribute.has_nested_list:
@@ -273,7 +285,7 @@ class SchemaValidator:
         """
         Recursively iterates through all attributes of an agent, applying tests if attribute type is `StringSet`
         Raises:
-            ValidationException: if
+            ValidationError: if
                 a) StringSet mentioned in schema is not defined in the scenario
                 b) the value assigned to an attribute of type StringSet is not contained in the corresponding StringSet
         """
@@ -287,10 +299,10 @@ class SchemaValidator:
                             msg = SchemaValidator._MISSING_STRING_SET_ENTRY.format(
                                 attribute.value, str(attribute), name
                             )
-                            log_error_and_raise(ValidationError(msg))
+                            raise log_error(ValidationError(msg))
                     else:
                         msg = SchemaValidator._MISSING_STRING_SET.format(specification.full_name)
-                        log_error_and_raise(ValidationError(msg))
+                        raise log_error(ValidationError(msg))
             if attribute.has_nested:
                 SchemaValidator._ensure_string_set_consistency(
                     attribute.nested, specification.nested_attributes, string_sets
@@ -304,16 +316,20 @@ class SchemaValidator:
         """Raises exception if given `contract` does not meet the `schema`'s requirements, using `agent_types_by_id`"""
         sender_id = contract.sender_id
         if sender_id not in agent_types_by_id:
-            log_error_and_raise(ValidationError(SchemaValidator._AGENT_MISSING.format(sender_id)))
+            raise log_error(ValidationError(SchemaValidator._AGENT_MISSING.format(sender_id, contract.to_dict())))
         if contract.receiver_id not in agent_types_by_id:
-            log_error_and_raise(ValidationError(SchemaValidator._AGENT_MISSING.format(contract.receiver_id)))
+            raise log_error(
+                ValidationError(SchemaValidator._AGENT_MISSING.format(contract.receiver_id, contract.to_dict()))
+            )
         sender_type_name = agent_types_by_id[sender_id]
         if sender_type_name not in schema.agent_types:
-            log_error_and_raise(ValidationError(SchemaValidator._AGENT_TYPE_UNKNOWN.format(sender_type_name)))
+            raise log_error(ValidationError(SchemaValidator._AGENT_TYPE_UNKNOWN.format(sender_type_name)))
         sender_type = schema.agent_types[sender_type_name]
         product = contract.product_name
         if product not in sender_type.products:
-            log_error_and_raise(ValidationError(SchemaValidator._PRODUCT_MISSING.format(product, sender_type_name)))
+            raise log_error(
+                ValidationError(SchemaValidator._PRODUCT_MISSING.format(product, sender_type_name, contract.to_dict()))
+            )
 
     @staticmethod
     def check_agents_have_contracts(scenario: Scenario) -> None:

fameio/input/writer.py

@@ -1,10 +1,12 @@
-# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
-import importlib.metadata as metadata
+from __future__ import annotations
+
 import sys
+from importlib import metadata
 from pathlib import Path
-from typing import Any, Union
+from typing import Any
 
 from fameprotobuf.contract_pb2 import ProtoContract
 from fameprotobuf.data_storage_pb2 import DataStorage
@@ -12,21 +14,21 @@ from fameprotobuf.execution_data_pb2 import ExecutionData
 from fameprotobuf.field_pb2 import NestedField
 from fameprotobuf.input_file_pb2 import InputData
 from fameprotobuf.model_pb2 import ModelData
+from google.protobuf.message import EncodeError
 
 import fameio
+from fameio.input import InputError
 from fameio.input.scenario import Agent, Attribute, Contract, GeneralProperties, Scenario, StringSet
 from fameio.input.schema import AttributeSpecs, AttributeType, JavaPackages, Schema
-from fameio.logs import log_error_and_raise, log
+from fameio.logs import log, log_error
 from fameio.output.reader import Reader
 from fameio.series import TimeSeriesManager
 from fameio.time import FameTime
 from fameio.tools import ensure_is_list
 
 
-class ProtoWriterError(Exception):
-    """Indicates an error during writing of protobuf file"""
-
-    pass
+class ProtoWriterError(InputError):
+    """Indicates an error during writing of a protobuf file"""
 
 
 class ProtoWriter:
@@ -34,13 +36,15 @@ class ProtoWriter:
 
     _FAME_PROTOBUF_STREAM_HEADER = fameio.FILE_HEADER_V2
 
-    _TYPE_NOT_IMPLEMENTED = "AttributeType '{}' not implemented."
+    _TYPE_NOT_IMPLEMENTED = "Protobuf representation for AttributeType '{}' not implemented."
     _CONTRACT_UNSUPPORTED = (
         "Unsupported value for Contract Attribute '{}'; "
         "Only support `int`, `float`, `enum` or `dict` types are supported here."
     )
     _USING_DEFAULT = "Using provided Default for Attribute: '{}'."
-    _NO_FILE_SPECIFIED = "Could not write to '{}'. Please specify a valid output file."
+    _ERR_FILE_PATH = "Could not open file '{}' for writing. Please specify a valid output file."
+    _ERR_PROTOBUF_ENCODING = "Could not encode to protobuf. Please contact FAME-Io developers: fame@dlr.de"
+    _ERR_FILE_WRITE = "Could not write to file '{}'."
 
     _INFO_WRITING = "Writing scenario to protobuf file `{}`"
     _INFO_WRITING_COMPLETED = "Saved protobuf file `{}` to disk"
@@ -50,12 +54,32 @@ class ProtoWriter:
         self._time_series_manager: TimeSeriesManager = time_series_manager
 
     def write_validated_scenario(self, scenario: Scenario) -> None:
-        """Writes given validated Scenario to file"""
-        pb_data_storage = self._create_protobuf_from_scenario(scenario)
-        self._write_protobuf_to_disk(pb_data_storage)
+        """
+        Writes given validated Scenario to file
+
+        Args:
+            scenario: to be written to file
+
+        Raises:
+            ProtoWriterError: if scenario could not be written to file, logged with level "ERROR"
+        """
+        data_storage = self._create_protobuf_from_scenario(scenario)
+        serialised = self._serialise(data_storage)
+        self._write_data_to_disk(serialised)
 
     def _create_protobuf_from_scenario(self, scenario: Scenario) -> DataStorage:
-        """Returns given `scenario` written to new DataStorage protobuf"""
+        """
+        Returns given `scenario` written to new DataStorage protobuf
+
+        Args:
+            scenario: to be converted to protobuf
+
+        Returns:
+            protobuf container with the scenario
+
+        Raises:
+            ProtoWriterError: if the protobuf representation cannot be constructed, logged with level "ERROR"
+        """
         log().info("Converting scenario to protobuf.")
         pb_data_storage = DataStorage()
         pb_input = pb_data_storage.input
@@ -81,7 +105,17 @@ class ProtoWriter:
         pb_input.simulation.random_seed = general_properties.simulation_random_seed
 
     def _add_agents(self, pb_input: InputData, agents: list[Agent], schema: Schema) -> None:
-        """Triggers setting of `agents` to `pb_input`"""
+        """
+        Triggers setting of `agents` to `pb_input`
+
+        Args:
+            pb_input: parent element to add the agents to
+            agents: to be added to parent input
+            schema: describing the agents' attributes
+
+        Raises:
+            ProtoWriterError: if any agent's attributes cannot be set, logged with level "ERROR"
+        """
         log().info("Adding Agents")
         for agent in agents:
             pb_agent = self._set_agent(pb_input.agents.add(), agent)
@@ -98,12 +132,22 @@ class ProtoWriter:
 
     def _set_attributes(
         self,
-        pb_parent: Union[InputData.AgentDao, NestedField],
+        pb_parent: InputData.AgentDao | NestedField,
         attributes: dict[str, Attribute],
         specs: dict[str, AttributeSpecs],
     ) -> None:
-        """Assigns `attributes` to protobuf fields of given `pb_parent` - cascades for nested Attributes"""
-        values_not_set = [key for key in specs.keys()]
+        """
+        Assigns `attributes` to protobuf fields of given `pb_parent` - cascades for nested Attributes
+
+        Args:
+            pb_parent: to store the attributes in
+            attributes: to be stored
+            specs: attribute specifications associated with attributes
+
+        Raises:
+            ProtoWriterError: if any attribute cannot be set, logged with level "ERROR"
+        """
+        values_not_set = list(specs.keys())
         for name, attribute in attributes.items():
             pb_field = self._add_field(pb_parent, name)
             attribute_specs = specs[name]
@@ -126,14 +170,24 @@ class ProtoWriter:
                 log().info(self._USING_DEFAULT.format(name))
 
     @staticmethod
-    def _add_field(pb_parent: Union[InputData.AgentDao, NestedField], name: str) -> NestedField:
+    def _add_field(pb_parent: InputData.AgentDao | NestedField, name: str) -> NestedField:
         """Returns new field with given `name` that is added to given `pb_parent`"""
         pb_field = pb_parent.fields.add()
         pb_field.field_name = name
         return pb_field
 
     def _set_attribute(self, pb_field: NestedField, value: Any, attribute_type: AttributeType) -> None:
-        """Sets given `value` to given protobuf `pb_field` depending on specified `attribute_type`"""
+        """
+        Sets given `value` to given protobuf `pb_field` depending on specified `attribute_type`
+
+        Args:
+            pb_field: parent element to contain the attribute value therein
+            value: of the attribute
+            attribute_type: type of the attribute
+
+        Raises:
+            ProtoWriterError: if the attribute type has no serialisation implementation, logged with level "ERROR"
+        """
         if attribute_type is AttributeType.INTEGER:
             pb_field.int_values.extend(ensure_is_list(value))
         elif attribute_type is AttributeType.DOUBLE:
@@ -147,11 +201,20 @@ class ProtoWriter:
         elif attribute_type is AttributeType.TIME_SERIES:
             pb_field.series_id = self._time_series_manager.get_series_id_by_identifier(value)
         else:
-            log_error_and_raise(ProtoWriterError(self._TYPE_NOT_IMPLEMENTED.format(attribute_type)))
+            raise log_error(ProtoWriterError(self._TYPE_NOT_IMPLEMENTED.format(attribute_type)))
 
     @staticmethod
     def _add_contracts(pb_input: InputData, contracts: list[Contract]) -> None:
-        """Triggers setting of `contracts` to `pb_input`"""
+        """
+        Adds given contracts to input data
+
+        Args:
+            pb_input: parent element to have the contracts added to
+            contracts: to be added
+
+        Raises:
+            ProtoWriterError: if any contract cannot be added, logged with level "ERROR"
+        """
         log().info("Adding Contracts")
         for contract in contracts:
             pb_contract = ProtoWriter._set_contract(pb_input.contracts.add(), contract)
@@ -171,12 +234,19 @@ class ProtoWriter:
         return pb_contract
 
     @staticmethod
-    def _set_contract_attributes(
-        pb_parent: Union[ProtoContract, NestedField], attributes: dict[str, Attribute]
-    ) -> None:
-        """Assign (nested) Attributes to given protobuf container `pb_parent`"""
+    def _set_contract_attributes(pb_parent: ProtoContract | NestedField, attributes: dict[str, Attribute]) -> None:
+        """
+        Assign (nested) Attributes to given protobuf container `pb_parent`
+
+        Args:
+            pb_parent: parent element, either a contract or an attribute
+            attributes: to be set as child elements of parent
+
+        Raises:
+            ProtoWriterError: if a type unsupported for contract attributes is found, logged with level "ERROR"
+        """
         for name, attribute in attributes.items():
-            log().debug("Assigning contract attribute `{}`.".format(name))
+            log().debug(f"Assigning contract attribute `{name}`.")
             pb_field = ProtoWriter._add_field(pb_parent, name)
 
             if attribute.has_value:
@@ -188,7 +258,7 @@ class ProtoWriter:
                 elif isinstance(value, str):
                     pb_field.string_values.extend([value])
                 else:
-                    log_error_and_raise(ProtoWriterError(ProtoWriter._CONTRACT_UNSUPPORTED.format(str(attribute))))
+                    raise log_error(ProtoWriterError(ProtoWriter._CONTRACT_UNSUPPORTED.format(str(attribute))))
             elif attribute.has_nested:
                 ProtoWriter._set_contract_attributes(pb_field, attribute.nested)
 
@@ -230,22 +300,50 @@ class ProtoWriter:
         pb_packages.data_items.extend(java_packages.data_items)
         pb_packages.portables.extend(java_packages.portables)
 
-    def _write_protobuf_to_disk(self, pb_data_storage: DataStorage) -> None:
-        """Writes given `protobuf_input_data` to disk"""
-        log().info(self._INFO_WRITING.format(self.file_path))
-        try:
-            with open(self.file_path, "wb") as file:
-                serialised_data_storage = pb_data_storage.SerializeToString()
-                file.write(self._FAME_PROTOBUF_STREAM_HEADER.encode(Reader.HEADER_ENCODING))
-                file.write(len(serialised_data_storage).to_bytes(Reader.BYTES_DEFINING_MESSAGE_LENGTH, byteorder="big"))
-                file.write(serialised_data_storage)
-        except OSError as e:
-            log_error_and_raise(ProtoWriterError(ProtoWriter._NO_FILE_SPECIFIED.format(self.file_path), e))
-        log().info(self._INFO_WRITING_COMPLETED.format(self.file_path))
-
     @staticmethod
     def _set_execution_versions(pb_version_data: ExecutionData.VersionData) -> None:
         """Adds version strings for fameio, fameprotobuf, and python to the given Versions message"""
         pb_version_data.fame_protobuf = metadata.version("fameprotobuf")
         pb_version_data.fame_io = metadata.version("fameio")
         pb_version_data.python = sys.version
+
+    def _serialise(self, data_storage: DataStorage) -> bytes:
+        """
+        Serialise given data storage to bytes
+
+        Args:
+            data_storage: to be serialised
+
+        Returns:
+            binary string representation of given data storage
+
+        Raises:
+            ProtoWriterError: if given data storage could not be serialised, logged with level "ERROR"
+        """
+        try:
+            return data_storage.SerializeToString()
+        except EncodeError as e:
+            raise log_error(ProtoWriterError(self._ERR_PROTOBUF_ENCODING)) from e
+
+    def _write_data_to_disk(self, serialised_data: bytes) -> None:
+        """
+        Writes given serialised data to file
+
+        Args:
+            serialised_data: to be written to file
+
+        Raises:
+            ProtoWriterError: if file could not be opened or written, logged with level "ERROR"
+        """
+        log().info(self._INFO_WRITING.format(self.file_path))
+        try:
+            with open(self.file_path, "wb") as file:
+                try:
+                    file.write(self._FAME_PROTOBUF_STREAM_HEADER.encode(Reader.HEADER_ENCODING))
+                    file.write(len(serialised_data).to_bytes(Reader.BYTES_DEFINING_MESSAGE_LENGTH, byteorder="big"))
+                    file.write(serialised_data)
+                except IOError as e:
+                    raise log_error(ProtoWriterError(self._ERR_FILE_WRITE.format(self.file_path))) from e
+        except OSError as e:
+            raise log_error(ProtoWriterError(ProtoWriter._ERR_FILE_PATH.format(self.file_path), e)) from e
+        log().info(self._INFO_WRITING_COMPLETED.format(self.file_path))

fameio/logs.py

@@ -1,11 +1,11 @@
-# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
 
 import logging as pylog
 from enum import Enum
 from pathlib import Path
-from typing import Optional
 
 
 class LogLevel(Enum):
@@ -27,7 +27,7 @@ _FORMAT_NORMAL = "%(asctime)s — %(levelname)s — %(message)s"  # noqa
 _FORMAT_DETAILLED = "%(asctime)s.%(msecs)03d — %(levelname)s — %(module)s:%(funcName)s:%(lineno)d — %(message)s"  # noqa
 _TIME_FORMAT = "%H:%M:%S"
 
-_INFO_UPDATING_LOG_LEVEL = "Updating fameio log level to: {}"
+_INFO_UPDATING_LOG_LEVEL = "Updating fameio log level to: %s"
 _WARN_NOT_INITIALIZED = "Logger for fameio not initialised: using default log level `WARNING`"
 
 LOGGER_NAME = "fameio"
@@ -42,35 +42,41 @@ def log() -> pylog.Logger:
     return _loggers[0]
 
 
-def log_critical_and_raise(exception: Exception) -> None:
+def log_critical(exception: Exception) -> Exception:
     """
-    Raises the specified `exception` and logs a critical error with the exception's message
+    Logs a critical error with the exception's message and returns the exception for raising it.
+    Does **not** raise the exception, i.e. the command must be preceded by a `raise`.
+
+    Example: `raise log_critical(MyException("My error message"))`
 
     Args:
-        exception: to be raised and logged at level `critical`
+        exception: to extract the error message from
 
-    Raises:
-        Exception: the given exception
+    Returns:
+      the given exception
     """
     log().critical(str(exception))
-    raise exception
+    return exception
 
 
-def log_error_and_raise(exception: Exception) -> None:
+def log_error(exception: Exception) -> Exception:
     """
-    Raises the specified `exception` and logs a critical error with the exception's message
+    Logs an error with the exception's message and returns the exception for raising.
+    Does **not** raise the exception, i.e. the command must be preceded by a `raise`.
+
+    Example: `raise log_error(MyException("My error message"))`
 
     Args:
-        exception: to be raised and logged at level `error`
+        exception: to extract the error message from
 
-    Raises:
-        Exception: the given exception
+    Returns:
+        the given exception
     """
     log().error(str(exception))
-    raise exception
+    return exception
 
 
-def fameio_logger(log_level_name: str, file_name: Optional[Path] = None) -> None:
+def fameio_logger(log_level_name: str, file_name: Path | None = None) -> None:
     """
     Ensures a logger for fameio is present and uses the specified options
 
@@ -87,7 +93,7 @@ def fameio_logger(log_level_name: str, file_name: Optional[Path] = None) -> None
         _add_handler(logger, pylog.FileHandler(file_name, mode="w"), formatter)
 
     if _loggers:
-        pylog.info(_INFO_UPDATING_LOG_LEVEL.format(log_level_name))
+        pylog.info(_INFO_UPDATING_LOG_LEVEL, log_level_name)
         _loggers[0] = logger
     else:
         _loggers.append(logger)

fameio/output/__init__.py

@@ -1,3 +1,7 @@
-# SPDX-FileCopyrightText: 2023 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: CC0-1.0
+
+
+class OutputError(Exception):
+    """An error that occurred during extracting an output file"""