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

fameio/input/schema/attribute.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 
 from enum import Enum, auto
 from pathlib import Path
-from typing import Any, Optional, Final, Union
+from typing import Any, Final
 
 from fameio.input import SchemaError
 from fameio.input.metadata import Metadata, ValueContainer
@@ -16,7 +16,7 @@ from fameio.tools import keys_to_lower
 
 
 class AttributeType(Enum):
-    """Data types that Attributes can take"""
+    """Data types that Attributes can take."""
 
     INTEGER = auto()
     DOUBLE = auto()
@@ -28,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
 
@@ -57,7 +57,7 @@ class AttributeType(Enum):
 
 
 class AttributeSpecs(Metadata):
-    """Schema Definition of a single Attribute (with possible inner Attributes) of an agent"""
+    """Schema Definition of a single Attribute (with possible inner Attributes) of an agent."""
 
     _DISALLOWED_NAMES = ["value", "values", "metadata"]
     _SEPARATOR = "."
@@ -75,6 +75,7 @@ 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."
     _SERIES_LIST_DISALLOWED = "Attribute '{}' of type TIME_SERIES cannot be a list."
@@ -82,13 +83,21 @@ class AttributeSpecs(Metadata):
     _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`"""
+        """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)
 
         self._is_mandatory = self._get_is_mandatory(definition, name)
@@ -96,7 +105,7 @@ class AttributeSpecs(Metadata):
         self._attr_type = self._get_type(definition, name)
 
         if self._attr_type == AttributeType.TIME_SERIES and self._is_list:
-            raise SchemaError(AttributeSpecs._SERIES_LIST_DISALLOWED.format(name))
+            raise log_error(SchemaError(AttributeSpecs._SERIES_LIST_DISALLOWED.format(name)))
 
         self._allowed_values = self._get_allowed_values(definition)
         self._default_value = self._get_default_value(definition)
@@ -105,18 +114,25 @@ class AttributeSpecs(Metadata):
 
     @staticmethod
     def _assert_is_allowed_name(full_name: str) -> None:
-        """Raises SchemaError if provided name is not allowed for Attributes"""
+        """Raises SchemaError if provided name is not allowed for Attributes.
+
+        Args:
+            full_name: to be checked if it can serve as name for an attribute
+
+        Raises:
+            SchemaError: if name is not allowed, logged with level "ERROR"
+        """
         if full_name is None:
-            raise SchemaError(AttributeSpecs._NAME_DISALLOWED)
+            raise log_error(SchemaError(AttributeSpecs._NAME_DISALLOWED))
         short_name = full_name.split(AttributeSpecs._SEPARATOR)[-1]
         if len(short_name) == 0 or short_name.isspace():
-            raise SchemaError(AttributeSpecs._NAME_DISALLOWED)
+            raise log_error(SchemaError(AttributeSpecs._NAME_DISALLOWED))
         if short_name.lower() in AttributeSpecs._DISALLOWED_NAMES:
-            raise SchemaError(AttributeSpecs._NAME_DISALLOWED)
+            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"""
+        """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))
@@ -124,7 +140,7 @@ class AttributeSpecs(Metadata):
 
     @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"""
+        """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))
@@ -132,17 +148,28 @@ class AttributeSpecs(Metadata):
 
     @staticmethod
     def _get_type(definition: dict, name: str) -> AttributeType:
-        """Returns `AttributeType` from given definition; Raises an exception if no proper type can be extracted"""
+        """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 SchemaError(AttributeSpecs._INVALID_TYPE.format(type_name)) from 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"""
+        """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]
@@ -150,16 +177,19 @@ class AttributeSpecs(Metadata):
                 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
+    def _read_values(self, definition: dict | list) -> ValueContainer:
+        """Returns acceptable values mapped to their optional metadata specifications extracted from given `definition`.
+
+        Accepts lists of values or dictionaries with (optional) metadata assigned to each value
 
         Args:
             definition: list of acceptable values or dict with acceptable values as keys and (optional) metadata content
 
         Returns:
             Mapping of acceptable values to their associated Metadata
+
+        Raises:
+            SchemaError: if values could not be parsed or do not match the attribute type, logged with level "ERROR"
         """
         try:
             value_container = ValueContainer(definition)
@@ -167,17 +197,28 @@ class AttributeSpecs(Metadata):
                 self._convert_to_data_type(value, self.KEY_VALUES)
             return value_container
         except ValueContainer.ParseError as e:
-            raise SchemaError(AttributeSpecs._VALUES_ILL_FORMAT.format(definition)) from e
+            raise log_error(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"""
+    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
+
+        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 as e:
-            raise SchemaError(AttributeSpecs._INCOMPATIBLE.format(value, section, self._attr_type)) from e
+            raise log_error(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"""
+    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:
@@ -186,20 +227,42 @@ class AttributeSpecs(Metadata):
         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]
-        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"""
+        """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():
@@ -209,67 +272,67 @@ class AttributeSpecs(Metadata):
 
     @staticmethod
     def _get_help(definition) -> str:
-        """Returns (possible empty) help text if provided in definition; None otherwise"""
+        """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"""
+        """Returns AttributeType of this attribute."""
         return self._attr_type
 
     @property
     def values(self) -> list:
-        """Returns the list of allowed values for this attribute"""
+        """Returns the list of allowed values for this attribute."""
         return self._allowed_values.as_list()
 
     @property
     def has_value_restrictions(self) -> bool:
-        """Returns True if the attribute can only take a set of certain values"""
+        """Returns True if the attribute can only take a set of certain values."""
         return not self._allowed_values.is_empty()
 
     @property
     def is_list(self) -> bool:
-        """Return True if this attribute type is a list"""
+        """Return True if this attribute type is a list."""
         return self._is_list
 
     @property
     def has_nested_attributes(self) -> bool:
-        """Returns True if nested attributes are defined"""
+        """Returns True if nested attributes are defined."""
         return bool(self._nested_attributes)
 
     @property
     def nested_attributes(self) -> dict[str, AttributeSpecs]:
-        """Returns list of nested Attributes of this Attribute or an empty dict if no nested attributes are defined"""
+        """Returns list of nested Attributes of this Attribute or an empty dict if no nested attributes are defined."""
         return self._nested_attributes
 
     @property
     def has_default_value(self) -> bool:
-        """Return True if a default value is available"""
+        """Return True if a default value is available."""
         return self._default_value is not None
 
     @property
-    def default_value(self) -> Optional[Any]:
-        """Return the default value of this attribute, or None if no default is specified"""
+    def default_value(self) -> Any | None:
+        """Return the default value of this attribute, or None if no default is specified."""
         return self._default_value
 
     @property
     def is_mandatory(self) -> bool:
-        """Return True if this attribute is mandatory"""
+        """Return True if this attribute is mandatory."""
         return self._is_mandatory
 
     @property
     def full_name(self) -> str:
-        """Returns name including name of enclosing parent attributes"""
+        """Returns name including name of enclosing parent attributes."""
         return self._full_name
 
     @property
     def has_help_text(self) -> bool:
-        """Return True if a help_text is available"""
+        """Return True if a help_text is available."""
         return bool(self._help)
 
     @property
     def help_text(self) -> str:
-        """Return the help_text of this attribute, if any"""
+        """Return the help_text of this attribute, if any."""
         return self._help
 
     def _to_dict(self) -> dict[str, Any]:

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,12 +6,12 @@ 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
 
 
 class JavaPackages:
-    """Schema definitions for Java package names in which model classes reside"""
+    """Schema definitions for Java package names in which model classes reside."""
 
     KEY_AGENT: Final[str] = "Agents".lower()
     KEY_DATA_ITEM: Final[str] = "DataItems".lower()
@@ -21,21 +21,23 @@ 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] = []
 
     @classmethod
     def from_dict(cls, definitions: dict[str, list[str]]) -> JavaPackages:
-        """
-        Creates JavaPackages from a dictionary representation
+        """Creates JavaPackages from a dictionary representation.
 
         Args:
             definitions: dictionary representation of 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,29 +47,29 @@ 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
 
     @property
     def agents(self) -> list[str]:
-        """Return list of java package names that contain the model's Agents"""
+        """Return list of java package names that contain the model's Agents."""
         return self._agents
 
     @property
     def data_items(self) -> list[str]:
-        """Return list of java package names that contain the model's DataItems"""
+        """Return list of java package names that contain the model's DataItems."""
         return self._data_items
 
     @property
     def portables(self) -> list[str]:
-        """Return list of java package names that contain the model's Portables"""
+        """Return list of java package names that contain the model's Portables."""
         return self._portables
 
     def to_dict(self) -> dict[str, list[str]]:
-        """Return dictionary representation of this JavaPackages object"""
+        """Return dictionary representation of this JavaPackages object."""
         return {self.KEY_AGENT: self.agents, self.KEY_DATA_ITEM: self.data_items, self.KEY_PORTABLE: self.portables}

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,14 +7,14 @@ 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
 
 
 class Schema:
-    """Definition of a schema"""
+    """Definition of a schema."""
 
     KEY_AGENT_TYPE: Final[str] = "AgentTypes".lower()
     KEY_PACKAGES: Final[str] = "JavaPackages".lower()
@@ -23,20 +23,30 @@ 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"""
+        """Convert given `definitions` into a new schema.
+
+        Args:
+            definitions: dictionary representation of schema
+
+        Returns:
+            schema created from given definitions
+
+        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,30 +58,44 @@ 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
     def from_string(cls, definitions: str) -> Schema:
-        """Load given string `definitions` into a new Schema"""
+        """Load given string `definitions` into a new Schema."""
         return cls.from_dict(ast.literal_eval(definitions))
 
     def to_dict(self) -> dict:
-        """Serializes the schema content to a dict"""
+        """Serializes the schema content to a dict."""
         return self._original_input_dict
 
     def to_string(self) -> str:
-        """Returns a string representation of the Schema of which the class can be rebuilt"""
+        """Returns a string representation of the Schema of which the class can be rebuilt."""
         return repr(self.to_dict())
 
     @property
     def agent_types(self) -> dict[str, AgentType]:
-        """Returns all the agent types by their name"""
+        """Returns all the agent types by their name."""
         return self._agent_types
 
     @property
     def packages(self) -> JavaPackages:
-        """Returns JavaPackages, i.e. names where model classes are defined in"""
+        """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