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

fameio/input/schema/schema.py

@@ -1,4 +1,4 @@
-# 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
@@ -7,7 +7,7 @@ import ast
 from typing import Any, Final
 
 from fameio.input import SchemaError
-from fameio.logs import log_error_and_raise
+from fameio.logs import log_error
 from fameio.tools import keys_to_lower
 from .agenttype import AgentType
 from .java_packages import JavaPackages
@@ -23,20 +23,31 @@ class Schema:
     _ERR_AGENT_TYPES_EMPTY = "`AgentTypes` must not be empty - at least one type of agent is required."
     _ERR_MISSING_PACKAGES = "Missing required section `JavaPackages` in Schema."
 
-    def __init__(self, definitions: dict):
+    def __init__(self, definitions: dict) -> None:
         self._original_input_dict = definitions
-        self._agent_types = {}
-        self._packages = None
+        self._agent_types: dict[str, AgentType] = {}
+        self._packages: JavaPackages | None = None
 
     @classmethod
     def from_dict(cls, definitions: dict) -> Schema:
-        """Load given dictionary `definitions` into a new Schema"""
+        """
+        Load given dictionary `definitions` into a new schema
+
+        Args:
+            definitions: dictionary representation of schema
+
+        Returns:
+            new Schema
+
+        Raises:
+            SchemaError: if definitions are incomplete or erroneous, logged on level "ERROR"
+        """
         definitions = keys_to_lower(definitions)
         schema = cls(definitions)
 
         agent_types = cls._get_or_raise(definitions, Schema.KEY_AGENT_TYPE, Schema._ERR_AGENT_TYPES_MISSING)
         if len(agent_types) == 0:
-            log_error_and_raise(SchemaError(Schema._ERR_AGENT_TYPES_EMPTY))
+            raise log_error(SchemaError(Schema._ERR_AGENT_TYPES_EMPTY))
         for agent_type_name, agent_definition in agent_types.items():
             agent_type = AgentType.from_dict(agent_type_name, agent_definition)
             schema._agent_types[agent_type_name] = agent_type
@@ -48,9 +59,22 @@ class Schema:
 
     @staticmethod
     def _get_or_raise(definitions: dict[str, Any], key: str, error_message: str) -> Any:
-        """Get given `key` from given `definitions` - raise error with given `error_message` if not present"""
+        """
+        Get given `key` from given `definitions` - raise error with given `error_message` if not present
+
+        Args:
+            definitions: to search the key in
+            key: to be searched
+            error_message: to be logged and included in the raised exception if key is missing
+
+        Returns:
+            value associated with given key in given definitions
+
+        Raises:
+            SchemaError: if given key is not in given definitions, logged on level "ERROR"
+        """
         if key not in definitions:
-            log_error_and_raise(SchemaError(error_message))
+            raise log_error(SchemaError(error_message))
         return definitions[key]
 
     @classmethod
@@ -74,4 +98,6 @@ class Schema:
     @property
     def packages(self) -> JavaPackages:
         """Returns JavaPackages, i.e. names where model classes are defined in"""
+        if self._packages is None:
+            raise log_error(SchemaError(self._ERR_MISSING_PACKAGES))
         return self._packages

fameio/input/validator.py

@@ -1,10 +1,13 @@
 # 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, Union
+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
@@ -13,7 +16,7 @@ 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"""
 
 
@@ -26,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."
@@ -53,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
@@ -113,7 +116,7 @@ class SchemaValidator:
     def _check_mandatory_or_default(
         attributes: dict[str, Attribute],
         specifications: dict[str, AttributeSpecs],
-    ) -> list[Union[str, float]]:
+    ) -> 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
@@ -121,7 +124,7 @@ class SchemaValidator:
         Returns:
             list of time series defaults used in scenario
         """
-        missing_series_defaults = []
+        missing_series_defaults: list[str | float] = []
         for name, specification in specifications.items():
             if name not in attributes:
                 if specification.is_mandatory:
@@ -130,7 +133,7 @@ class SchemaValidator:
                             ValidationError(SchemaValidator._ATTRIBUTE_MISSING.format(specification.full_name))
                         )
                     if specification.attr_type == AttributeType.TIME_SERIES:
-                        missing_series_defaults.append(specification.default_value)
+                        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))
@@ -237,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
@@ -254,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)
-                        raise log_error(ValidationError(message, e)) from 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:
@@ -282,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
         """
@@ -313,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:
-            raise log_error(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:
-            raise log_error(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:
             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:
-            raise log_error(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: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
-from importlib import 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,19 +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"""
+class ProtoWriterError(InputError):
+    """Indicates an error during writing of a protobuf file"""
 
 
 class ProtoWriter:
@@ -32,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"
@@ -48,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
@@ -79,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)
@@ -96,11 +132,21 @@ 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"""
+        """
+        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)
@@ -124,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:
@@ -145,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)
@@ -169,10 +234,17 @@ 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(f"Assigning contract attribute `{name}`.")
             pb_field = ProtoWriter._add_field(pb_parent, name)
@@ -186,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)
 
@@ -228,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: 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):
@@ -42,20 +42,6 @@ def log() -> pylog.Logger:
     return _loggers[0]
 
 
-def log_critical_and_raise(exception: Exception) -> None:
-    """
-    Raises the specified `exception` and logs a critical error with the exception's message
-
-    Args:
-        exception: to be raised and logged at level `critical`
-
-    Raises:
-        Exception: the given exception
-    """
-    log().critical(str(exception))
-    raise exception
-
-
 def log_critical(exception: Exception) -> Exception:
     """
     Logs a critical error with the exception's message and returns the exception for raising it.
@@ -73,20 +59,6 @@ def log_critical(exception: Exception) -> Exception:
     return exception
 
 
-def log_error_and_raise(exception: Exception) -> None:
-    """
-    Raises the specified `exception` and logs a critical error with the exception's message
-
-    Args:
-        exception: to be raised and logged at level `error`
-
-    Raises:
-        Exception: the given exception
-    """
-    log().error(str(exception))
-    raise exception
-
-
 def log_error(exception: Exception) -> Exception:
     """
     Logs an error with the exception's message and returns the exception for raising.
@@ -98,13 +70,13 @@ def log_error(exception: Exception) -> Exception:
         exception: to extract the error message from
 
     Returns:
-      the given exception
+        the given exception
     """
     log().error(str(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
 

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"""