fameio 3.1.0__py3-none-any.whl → 3.2.0__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 typing import Any, Optional, Final, Union
+from pathlib import Path
+from typing import Any, Final
 
 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
 
@@ -26,7 +28,7 @@ class AttributeType(Enum):
     TIME_SERIES = auto()
     BLOCK = auto()
 
-    def convert_string_to_type(self, value: str) -> Union[int, float, str]:
+    def convert_string_to_type(self, value: str) -> int | float | str:
         """
         Converts a given string to this AttributeType's data format
 
@@ -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):
@@ -72,79 +75,112 @@ class AttributeSpecs(Metadata):
     _MISSING_TYPE = "'AttributeType' not declare for Attribute '{}'."
     _INVALID_TYPE = "'{}' is not a valid type for an Attribute."
     _DEFAULT_NOT_LIST = "Attribute is list, but provided Default '{}' is not a list."
+    _DEFAULT_NOT_SIMPLE = "Only a simple Default value is allowed for non-list attributes, but was '{}'"
     _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)
+        """
+        Loads Attribute from given `definition`
+
+        Args:
+            name: of attribute type
+            definition: of attribute type
 
+        Raises:
+            SchemaError: if attribute type is not properly defined, logged with level "ERROR"
+        """
+        super().__init__(definition)
+        self._assert_is_allowed_name(name)
         self._full_name = name
+
         if not definition:
-            raise SchemaError(AttributeSpecs._EMPTY_DEFINITION.format(name))
+            raise log_error(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))
+            raise log_error(SchemaError(AttributeSpecs._SERIES_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)
+        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)
 
-        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)
+    @staticmethod
+    def _assert_is_allowed_name(full_name: str) -> None:
+        """
+        Raises SchemaError if provided name is not allowed for Attributes
 
-        self._help = None
-        if AttributeSpecs.KEY_HELP in definition:
-            self._help = definition[AttributeSpecs.KEY_HELP].strip()
+        Args:
+            full_name: to be checked if it can serve as name for an attribute
 
-    @staticmethod
-    def _name_is_disallowed(full_name: str) -> bool:
-        """Returns True if name is not allowed"""
+        Raises:
+            SchemaError: if name is not allowed, logged with level "ERROR"
+        """
         if full_name is None:
-            return True
+            raise log_error(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 log_error(SchemaError(AttributeSpecs._NAME_DISALLOWED))
+        if short_name.lower() in AttributeSpecs._DISALLOWED_NAMES:
+            raise log_error(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
 
-    def _read_values(self, definition: [dict, list]) -> ValueContainer:
+    @staticmethod
+    def _get_type(definition: dict, name: str) -> AttributeType:
+        """
+        Returns `AttributeType` from given definition
+
+        Args:
+            definition: of the attribute
+            name: of the attribute
+
+        Returns:
+            type of attribute
+
+        Raises:
+            SchemaError: if no proper type can be extracted, logged with level "ERROR"
+        """
+        if AttributeSpecs.KEY_TYPE in definition:
+            type_name = definition[AttributeSpecs.KEY_TYPE]
+            try:
+                return AttributeType[type_name.upper()]
+            except KeyError as e:
+                raise log_error(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:
         """
         Returns accepted values mapped to their additional metadata specifications extracted from given `definition`
         Accepts lists of accepted values or dictionaries with (optional) metadata assigned to each value
@@ -154,35 +190,97 @@ class AttributeSpecs(Metadata):
 
         Returns:
             Mapping of acceptable values to their associated Metadata
+
+        Raises:
+            SchemaError: if values could not be parsed, logged with level "ERROR"
         """
         try:
             value_container = ValueContainer(definition)
             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 log_error(SchemaError(AttributeSpecs._VALUES_ILL_FORMAT.format(definition))) from e
+
+    def _convert_to_data_type(self, value: str, section: str) -> int | float | str:
+        """
+        Returns a given single `value` in `section` converted to this Attribute's data type
+
+        Args:
+            value: to be converted
+            section: that contains the value
+
+        Returns:
+            value with type matching this attribute type
 
-    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"""
+        Raises:
+            SchemaError: if value does not match this type of attribute, logged with level "ERROR"
+        """
         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 log_error(SchemaError(AttributeSpecs._INCOMPATIBLE.format(value, section, self._attr_type))) from e
+
+    def _get_default_value(self, definition: dict) -> int | float | str | list | None:
+        """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"""
+        """
+        Converts all entries in given `values` list to this attribute data type and returns this new list
+
+        Args:
+            values: to be converted to a list of default values
+
+        Returns:
+            default values
+
+        Raises:
+            SchemaError: if provided default is not a list, logged with level "ERROR"
+        """
         if isinstance(values, list):
             return [self._convert_and_test(item) for item in values]
-        else:
-            raise SchemaError(AttributeSpecs._DEFAULT_NOT_LIST.format(values))
+        raise log_error(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"""
+        """
+        Converts a given single `value` to this Attribute's data type and tests if the value is allowed
+
+        Args:
+            value: to be converted and tested
+
+        Returns:
+            the value converted to the data type matching this attribute type
+
+        Raises:
+            SchemaError: if the provided default could not be converted or is not allowed, logged with level "ERROR"
+        """
+        if isinstance(value, (list, dict)):
+            raise log_error(SchemaError(self._DEFAULT_NOT_SIMPLE.format(value)))
         if self.has_value_restrictions and (not self._allowed_values.has_value(value)):
-            raise SchemaError(AttributeSpecs._DEFAULT_DISALLOWED.format(value))
+            raise log_error(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"""
@@ -219,7 +317,7 @@ class AttributeSpecs(Metadata):
         return self._default_value is not None
 
     @property
-    def default_value(self) -> Optional[Any]:
+    def default_value(self) -> Any | None:
         """Return the default value of this attribute, or None if no default is specified"""
         return self._default_value
 
@@ -233,14 +331,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 +338,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/schema/java_packages.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
@@ -6,7 +6,7 @@ from __future__ import annotations
 from typing import Final
 
 from fameio.input import SchemaError
-from fameio.logs import log_error_and_raise, log
+from fameio.logs import log, log_error
 from fameio.tools import keys_to_lower
 
 
@@ -21,7 +21,7 @@ class JavaPackages:
     _INFO_MISSING_DATA_ITEMS = "`DataItems` not specified: Key was missing or list was empty."
     _ERR_MISSING_PORTABLES = "JavaPackages require non-empty list for `Portables`. Key was missing or list was empty."
 
-    def __init__(self):
+    def __init__(self) -> None:
         self._agents: list[str] = []
         self._data_items: list[str] = []
         self._portables: list[str] = []
@@ -36,6 +36,9 @@ class JavaPackages:
 
         Returns:
             new instance of JavaPackages
+
+        Raises:
+            SchemaError: if definitions are incomplete or erroneous, logged on level "ERROR"
         """
         java_packages = cls()
         definitions = keys_to_lower(definitions)
@@ -45,11 +48,11 @@ class JavaPackages:
         java_packages._portables = definitions.get(JavaPackages.KEY_PORTABLE, [])
 
         if not java_packages._agents:
-            log_error_and_raise(SchemaError(JavaPackages._ERR_MISSING_AGENTS))
+            raise log_error(SchemaError(JavaPackages._ERR_MISSING_AGENTS))
         if not java_packages._data_items:
             log().info(JavaPackages._INFO_MISSING_DATA_ITEMS)
         if not java_packages._portables:
-            log_error_and_raise(SchemaError(JavaPackages._ERR_MISSING_PORTABLES))
+            raise log_error(SchemaError(JavaPackages._ERR_MISSING_PORTABLES))
 
         return java_packages
 

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