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

fameio/input/schema/attribute.py

@@ -1,14 +1,16 @@
-# 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
 
 from enum import Enum, auto
+from pathlib import Path
 from typing import Any, Optional, Final, Union
 
 from fameio.input import SchemaError
 from fameio.input.metadata import Metadata, ValueContainer
-from fameio.logs import log
+from fameio.logs import log, log_error
+from fameio.series import CSV_FILE_SUFFIX
 from fameio.time import FameTime
 from fameio.tools import keys_to_lower
 
@@ -41,16 +43,17 @@ class AttributeType(Enum):
         """
         if self is AttributeType.INTEGER or self is AttributeType.LONG:
             return int(value)
-        elif self is AttributeType.DOUBLE:
+        if self is AttributeType.DOUBLE:
             return float(value)
-        elif self is AttributeType.TIME_STAMP:
+        if self is AttributeType.TIME_STAMP:
             return FameTime.convert_string_if_is_datetime(value)
-        elif self is AttributeType.ENUM or self is AttributeType.STRING or self is AttributeType.STRING_SET:
+        if self is AttributeType.ENUM or self is AttributeType.STRING or self is AttributeType.STRING_SET:
             return str(value)
-        elif self is AttributeType.TIME_SERIES:
+        if self is AttributeType.TIME_SERIES:
+            if isinstance(value, str) and Path(value).suffix.lower() == CSV_FILE_SUFFIX:
+                return value
             return float(value)
-        else:
-            raise ValueError("String conversion not supported for '{}'.".format(self))
+        raise ValueError(f"String conversion not supported for '{self}'.")
 
 
 class AttributeSpecs(Metadata):
@@ -74,75 +77,78 @@ class AttributeSpecs(Metadata):
     _DEFAULT_NOT_LIST = "Attribute is list, but provided Default '{}' is not a list."
     _INCOMPATIBLE = "Value '{}' in section '{}' can not be converted to AttributeType '{}'."
     _DEFAULT_DISALLOWED = "Default '{}' is not an allowed value."
-    _LIST_DISALLOWED = "Attribute '{}' of type TIME_SERIES cannot be a list."
+    _SERIES_LIST_DISALLOWED = "Attribute '{}' of type TIME_SERIES cannot be a list."
     _VALUES_ILL_FORMAT = "Only List and Dictionary is supported for 'Values' but was: {}"
     _NAME_DISALLOWED = f"Attribute name must not be empty and none of: {_DISALLOWED_NAMES}"
 
     def __init__(self, name: str, definition: dict):
         """Loads Attribute from given `definition`"""
         super().__init__(definition)
-        if self._name_is_disallowed(name):
-            raise SchemaError(AttributeSpecs._NAME_DISALLOWED)
-
+        self._assert_is_allowed_name(name)
         self._full_name = name
+
         if not definition:
             raise SchemaError(AttributeSpecs._EMPTY_DEFINITION.format(name))
         definition = keys_to_lower(definition)
 
-        if AttributeSpecs.KEY_MANDATORY in definition:
-            self._is_mandatory = definition[AttributeSpecs.KEY_MANDATORY]
-        else:
-            self._is_mandatory = True
-            log().warning(AttributeSpecs._MISSING_SPEC_DEFAULT.format(AttributeSpecs.KEY_MANDATORY, name, True))
-
-        if AttributeSpecs.KEY_LIST in definition:
-            self._is_list = definition[AttributeSpecs.KEY_LIST]
-        else:
-            self._is_list = False
-            log().warning(AttributeSpecs._MISSING_SPEC_DEFAULT.format(AttributeSpecs.KEY_LIST, name, False))
-
-        if AttributeSpecs.KEY_TYPE in definition:
-            self._attr_type = AttributeSpecs._get_type_for_name(definition[AttributeSpecs.KEY_TYPE])
-        else:
-            log().error(AttributeSpecs._MISSING_TYPE.format(name))
-            raise SchemaError(AttributeSpecs._MISSING_TYPE.format(name))
+        self._is_mandatory = self._get_is_mandatory(definition, name)
+        self._is_list = self._get_is_list(definition, name)
+        self._attr_type = self._get_type(definition, name)
 
         if self._attr_type == AttributeType.TIME_SERIES and self._is_list:
-            raise SchemaError(AttributeSpecs._LIST_DISALLOWED.format(name))
-
-        self._allowed_values: ValueContainer = ValueContainer()
-        if AttributeSpecs.KEY_VALUES in definition:
-            value_definition = definition[AttributeSpecs.KEY_VALUES]
-            if value_definition:
-                self._allowed_values = self._read_values(value_definition)
+            raise SchemaError(AttributeSpecs._SERIES_LIST_DISALLOWED.format(name))
 
-        self._default_value = None
-        if AttributeSpecs.KEY_DEFAULT in definition:
-            provided_value = definition[AttributeSpecs.KEY_DEFAULT]
-            if self._is_list:
-                self._default_value = self._convert_list(provided_value)
-            else:
-                self._default_value = self._convert_and_test(provided_value)
-
-        self._nested_attributes = {}
-        if AttributeSpecs.KEY_NESTED in definition:
-            for nested_name, nested_details in definition[AttributeSpecs.KEY_NESTED].items():
-                full_name = name + self._SEPARATOR + nested_name
-                self._nested_attributes[nested_name] = AttributeSpecs(full_name, nested_details)
-
-        self._help = None
-        if AttributeSpecs.KEY_HELP in definition:
-            self._help = definition[AttributeSpecs.KEY_HELP].strip()
+        self._allowed_values = self._get_allowed_values(definition)
+        self._default_value = self._get_default_value(definition)
+        self._nested_attributes = self._get_nested_attributes(definition, name)
+        self._help = self._get_help(definition)
 
     @staticmethod
-    def _name_is_disallowed(full_name: str) -> bool:
-        """Returns True if name is not allowed"""
+    def _assert_is_allowed_name(full_name: str) -> None:
+        """Raises SchemaError if provided name is not allowed for Attributes"""
         if full_name is None:
-            return True
+            raise SchemaError(AttributeSpecs._NAME_DISALLOWED)
         short_name = full_name.split(AttributeSpecs._SEPARATOR)[-1]
         if len(short_name) == 0 or short_name.isspace():
-            return True
-        return short_name.lower() in AttributeSpecs._DISALLOWED_NAMES
+            raise SchemaError(AttributeSpecs._NAME_DISALLOWED)
+        if short_name.lower() in AttributeSpecs._DISALLOWED_NAMES:
+            raise SchemaError(AttributeSpecs._NAME_DISALLOWED)
+
+    @staticmethod
+    def _get_is_mandatory(definition: dict, name: str) -> bool:
+        """Returns True if `Mandatory` is set to True or if specification is missing; False otherwise"""
+        if AttributeSpecs.KEY_MANDATORY in definition:
+            return definition[AttributeSpecs.KEY_MANDATORY]
+        log().warning(AttributeSpecs._MISSING_SPEC_DEFAULT.format(AttributeSpecs.KEY_MANDATORY, name, True))
+        return True
+
+    @staticmethod
+    def _get_is_list(definition: dict, name: str) -> bool:
+        """Returns True if `List` is set to True; Returns False otherwise or if specification is missing"""
+        if AttributeSpecs.KEY_LIST in definition:
+            return definition[AttributeSpecs.KEY_LIST]
+        log().warning(AttributeSpecs._MISSING_SPEC_DEFAULT.format(AttributeSpecs.KEY_LIST, name, False))
+        return False
+
+    @staticmethod
+    def _get_type(definition: dict, name: str) -> AttributeType:
+        """Returns `AttributeType` from given definition; Raises an exception if no proper type can be extracted"""
+        if AttributeSpecs.KEY_TYPE in definition:
+            type_name = definition[AttributeSpecs.KEY_TYPE]
+            try:
+                return AttributeType[type_name.upper()]
+            except KeyError as e:
+                raise SchemaError(AttributeSpecs._INVALID_TYPE.format(type_name)) from e
+        raise log_error(SchemaError(AttributeSpecs._MISSING_TYPE.format(name)))
+
+    def _get_allowed_values(self, definition: dict) -> ValueContainer:
+        """Returns ValueContainer with allowed values if defined; otherwise an empty ValueContainer"""
+        allowed_values: ValueContainer = ValueContainer()
+        if AttributeSpecs.KEY_VALUES in definition:
+            value_definition = definition[AttributeSpecs.KEY_VALUES]
+            if value_definition:
+                allowed_values = self._read_values(value_definition)
+        return allowed_values
 
     def _read_values(self, definition: [dict, list]) -> ValueContainer:
         """
@@ -160,22 +166,30 @@ class AttributeSpecs(Metadata):
             for value in value_container.as_list():
                 self._convert_to_data_type(value, self.KEY_VALUES)
             return value_container
-        except ValueContainer.ParseError:
-            raise SchemaError(AttributeSpecs._VALUES_ILL_FORMAT.format(definition))
+        except ValueContainer.ParseError as e:
+            raise SchemaError(AttributeSpecs._VALUES_ILL_FORMAT.format(definition)) from e
 
     def _convert_to_data_type(self, value: str, section: str) -> Union[int, float, str]:
         """Returns a given single `value` in `section` converted to this Attribute's data type"""
         try:
             return self._attr_type.convert_string_to_type(value)
-        except ValueError:
-            raise SchemaError(AttributeSpecs._INCOMPATIBLE.format(value, section, self._attr_type))
+        except ValueError as e:
+            raise SchemaError(AttributeSpecs._INCOMPATIBLE.format(value, section, self._attr_type)) from e
+
+    def _get_default_value(self, definition: dict) -> Optional[Union[int, float, str, list]]:
+        """Returns default value(s) from given definitions, or None if no default is specified"""
+        if AttributeSpecs.KEY_DEFAULT in definition:
+            provided_value = definition[AttributeSpecs.KEY_DEFAULT]
+            if self._is_list:
+                return self._convert_list(provided_value)
+            return self._convert_and_test(provided_value)
+        return None
 
     def _convert_list(self, values) -> list:
         """Converts all entries in given `values` list to this attribute data type and returns this new list"""
         if isinstance(values, list):
             return [self._convert_and_test(item) for item in values]
-        else:
-            raise SchemaError(AttributeSpecs._DEFAULT_NOT_LIST.format(values))
+        raise SchemaError(AttributeSpecs._DEFAULT_NOT_LIST.format(values))
 
     def _convert_and_test(self, value: str):
         """Converts a given single `value` to this Attribute's data type and tests if the value is allowed"""
@@ -183,6 +197,21 @@ class AttributeSpecs(Metadata):
             raise SchemaError(AttributeSpecs._DEFAULT_DISALLOWED.format(value))
         return self._convert_to_data_type(value, self.KEY_DEFAULT)
 
+    @staticmethod
+    def _get_nested_attributes(definition: dict, name: str) -> dict[str, AttributeSpecs]:
+        """Returns dict of nested attributes read from given definition; empty dict if no nested attributes exist"""
+        nested_attributes = {}
+        if AttributeSpecs.KEY_NESTED in definition:
+            for nested_name, nested_details in definition[AttributeSpecs.KEY_NESTED].items():
+                full_name = name + AttributeSpecs._SEPARATOR + nested_name
+                nested_attributes[nested_name] = AttributeSpecs(full_name, nested_details)
+        return nested_attributes
+
+    @staticmethod
+    def _get_help(definition) -> str:
+        """Returns (possible empty) help text if provided in definition; None otherwise"""
+        return definition.get(AttributeSpecs.KEY_HELP, "").strip()
+
     @property
     def attr_type(self) -> AttributeType:
         """Returns AttributeType of this attribute"""
@@ -233,14 +262,6 @@ class AttributeSpecs(Metadata):
         """Returns name including name of enclosing parent attributes"""
         return self._full_name
 
-    @staticmethod
-    def _get_type_for_name(name: str) -> AttributeType:
-        """Returns the AttributeType matching the given `name` converted to upper case"""
-        try:
-            return AttributeType[name.upper()]
-        except KeyError:
-            raise SchemaError(AttributeSpecs._INVALID_TYPE.format(name))
-
     @property
     def has_help_text(self) -> bool:
         """Return True if a help_text is available"""
@@ -248,8 +269,8 @@ class AttributeSpecs(Metadata):
 
     @property
     def help_text(self) -> str:
-        """Return the help_text of this attribute, if any, otherwise an empty string"""
-        return self._help if self.has_help_text else ""
+        """Return the help_text of this attribute, if any"""
+        return self._help
 
     def _to_dict(self) -> dict[str, Any]:
         definition = {

fameio/input/validator.py

@@ -1,15 +1,14 @@
-# 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 math
 from collections import Counter
-from typing import Any
+from typing import Any, Union
 
 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
 
@@ -17,8 +16,6 @@ from fameio.time import FameTime
 class ValidationError(Exception):
     """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`"""
@@ -79,27 +76,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 +107,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[Union[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 = []
         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)
                 else:
                     if specification.has_default_value:
                         log().warning(SchemaValidator._DEFAULT_IGNORED.format(specification.full_name))
@@ -133,16 +140,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 +175,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 +198,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 +209,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:
@@ -248,7 +257,7 @@ class SchemaValidator:
                         manager.register_and_validate(attribute.value)
                     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, e)) from e
             if attribute.has_nested:
                 SchemaValidator._ensure_valid_timeseries(attribute.nested, specification.nested_attributes, manager)
             if attribute.has_nested_list:
@@ -287,10 +296,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 +313,16 @@ 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)))
         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)))
         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)))
 
     @staticmethod
     def check_agents_have_contracts(scenario: Scenario) -> None:

fameio/input/writer.py

@@ -1,7 +1,7 @@
-# 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 importlib import metadata
 import sys
 from pathlib import Path
 from typing import Any, Union
@@ -26,8 +26,6 @@ from fameio.tools import ensure_is_list
 class ProtoWriterError(Exception):
     """Indicates an error during writing of protobuf file"""
 
-    pass
-
 
 class ProtoWriter:
     """Writes a given scenario to protobuf file"""
@@ -103,7 +101,7 @@ class ProtoWriter:
         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()]
+        values_not_set = list(specs.keys())
         for name, attribute in attributes.items():
             pb_field = self._add_field(pb_parent, name)
             attribute_specs = specs[name]
@@ -176,7 +174,7 @@ class ProtoWriter:
     ) -> None:
         """Assign (nested) Attributes to given protobuf container `pb_parent`"""
         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:

fameio/logs.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
 
@@ -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"
@@ -56,6 +56,23 @@ def log_critical_and_raise(exception: Exception) -> None:
     raise exception
 
 
+def log_critical(exception: Exception) -> Exception:
+    """
+    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 extract the error message from
+
+    Returns:
+      the given exception
+    """
+    log().critical(str(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
@@ -70,6 +87,23 @@ def log_error_and_raise(exception: Exception) -> None:
     raise exception
 
 
+def log_error(exception: Exception) -> Exception:
+    """
+    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 extract the error message from
+
+    Returns:
+      the given exception
+    """
+    log().error(str(exception))
+    return exception
+
+
 def fameio_logger(log_level_name: str, file_name: Optional[Path] = None) -> None:
     """
     Ensures a logger for fameio is present and uses the specified options
@@ -87,7 +121,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/agent_type.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 typing import Union
@@ -28,18 +28,17 @@ class AgentType:
 
     def get_simple_column_mask(self) -> list[bool]:
         """Returns list of bool - where an entry is True if the output column with the same index is not complex"""
-        return [True if len(field.index_names) == 0 else False for field in self._agent_type.fields]
+        return [len(field.index_names) == 0 for field in self._agent_type.fields]
 
     def get_complex_column_ids(self) -> set[int]:
         """Returns set of IDs for complex columns, ignoring simple columns"""
-        return set([field.field_id for field in self._agent_type.fields if len(field.index_names) > 0])
+        return {field.field_id for field in self._agent_type.fields if len(field.index_names) > 0}
 
     def get_column_name_for_id(self, column_index: int) -> Union[str, None]:
         """Returns name of column by given `column_index` or None, if column is not present"""
         if 0 <= column_index < len(self._agent_type.fields):
             return self._agent_type.fields[column_index].field_name
-        else:
-            return None
+        return None
 
     def get_inner_columns(self, column_index: int) -> tuple[str, ...]:
         """Returns tuple of inner column names for complex column with given `column_index`"""
@@ -50,6 +49,10 @@ class AgentType:
         return self._agent_type.class_name
 
 
+class AgentTypeError(Exception):
+    """Indicates an error with the agent types definitions"""
+
+
 class AgentTypeLog:
     """Stores data about collected agent types"""
 
@@ -69,9 +72,9 @@ class AgentTypeLog:
                     for agent_name, agent_type in new_types.items()
                     if agent_name.upper() in self._requested_agents
                 }
-            for agent_name in self._requested_agent_types.keys():
+            for agent_name in self._requested_agent_types:
                 if agent_name in new_types:
-                    raise Exception(self._ERR_DOUBLE_DEFINITION.format(agent_name))
+                    raise AgentTypeError(self._ERR_DOUBLE_DEFINITION.format(agent_name))
             self._requested_agent_types.update(new_types)
 
     def has_any_agent_type(self) -> bool:
@@ -81,7 +84,7 @@ class AgentTypeLog:
     def get_agent_type(self, agent_name: str) -> AgentType:
         """Returns `AgentType` of given agent `name`"""
         if agent_name not in self._requested_agent_types:
-            raise Exception(self._ERR_AGENT_TYPE_MISSING.format(agent_name))
+            raise AgentTypeError(self._ERR_AGENT_TYPE_MISSING.format(agent_name))
         return AgentType(self._requested_agent_types[agent_name])
 
     def is_requested(self, agent_name: str) -> bool:

fameio/output/conversion.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
 
@@ -19,7 +19,7 @@ def _apply_time_merging(
     dataframes: dict[Optional[str], pd.DataFrame], offset: int, period: int, first_positive_focal_point: int
 ) -> None:
     """Applies time merging to `data` based on given `offset`, `period`, and `first_positive_focal_point`"""
-    log().debug(f"Grouping TimeSteps...")
+    log().debug("Grouping TimeSteps...")
     for key in dataframes.keys():
         df = dataframes[key]
         index_columns = df.index.names