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

fameio/input/scenario/exception.py

@@ -1,38 +1,61 @@
-# 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 typing import NoReturn, Any, Union
+from typing import Any
 
 from fameio.input import ScenarioError
-from fameio.logs import log_error_and_raise, log
+from fameio.logs import log_error
 
 _DEFAULT_USED = "Using default value '{}' for missing key '{}'"
 
 
-def log_and_raise(message: str) -> NoReturn:
-    """Raises ScenarioError with given `message`"""
-    log_error_and_raise(ScenarioError(message))
+def log_scenario_error(message: str) -> ScenarioError:
+    """
+    Creates exception with given `message`, logs it on level "Error" and returns it
 
+    Args:
+        message: to be logged and included in the exception if key is missing
 
-def get_or_raise(dictionary: dict, key: str, message: str) -> Union[Any, NoReturn]:
-    """Returns value associated with `key` in given `dictionary`, or raises ScenarioException if key is missing"""
+    Returns:
+        created ScenarioError, logged on level "ERROR"
+    """
+    error = ScenarioError(message)
+    log_error(error)
+    return error
+
+
+def get_or_raise(dictionary: dict, key: str, error_message: str) -> Any:
+    """
+    Returns value associated with `key` in given `dictionary`, or raises exception if key or value is missing
+
+    Args:
+        dictionary: 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 dictionary
+
+     Raises:
+         ScenarioError: if given key is not in given dictionary or value is None, logged on level "ERROR"
+    """
     if key not in dictionary or dictionary[key] is None:
-        log_error_and_raise(ScenarioError(message.format(key)))
-    else:
-        return dictionary[key]
+        raise log_scenario_error(error_message.format(key))
+    return dictionary[key]
 
 
-def assert_or_raise(assertion: bool, msg: str) -> None:
-    """Raises new ScenarioError with given `msg` if `assertion` is False"""
-    if not assertion:
-        log_error_and_raise(ScenarioError(msg))
+def assert_or_raise(assertion: bool, error_message: str) -> None:
+    """
+    Raises exception with given `msg` if `assertion` is False
 
+    Args:
+        assertion: expression that must be True, else an exception is raised
+        error_message: to be logged and included in the raised exception if key is missing
 
-def get_or_default(dictionary: dict, key: str, default_value) -> Any:
-    """Returns value associated with `key` in given `dictionary`, or the given `default_value` if key is missing"""
-    if key in dictionary and dictionary[key] is not None:
-        return dictionary[key]
-    else:
-        log().debug(_DEFAULT_USED.format(default_value, key))
-        return default_value
+    Raises:
+        ScenarioError: if assertion is False, logged on level "ERROR"
+    """
+    if not assertion:
+        raise log_scenario_error(error_message)

fameio/input/scenario/fameiofactory.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 fameio.input.schema import Schema
@@ -9,31 +9,87 @@ from .stringset import StringSet
 
 
 class FameIOFactory:
-    """Factory used to instantiate the types defined in a scenario file.
+    """
+    Factory used to instantiate the types defined in a scenario file.
     This allows a client to subclass some types in order to extend what a scenario can contain.
     """
 
     @staticmethod
     def new_schema_from_dict(definitions: dict) -> Schema:
-        """Constructs a new Schema from provided `definitions`"""
+        """
+        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"
+        """
         return Schema.from_dict(definitions)
 
     @staticmethod
     def new_general_properties_from_dict(definitions: dict) -> GeneralProperties:
-        """Constructs a new GeneralProperties instance from provided `definitions`"""
+        """
+        Parse general properties from provided `definitions`
+
+        Args:
+            definitions: dictionary representation of general properties
+
+        Returns:
+            new GeneralProperties
+
+        Raises:
+            ScenarioError: if definitions are incomplete or erroneous, logged on level "ERROR"
+        """
         return GeneralProperties.from_dict(definitions)
 
     @staticmethod
     def new_agent_from_dict(definitions: dict) -> Agent:
-        """Constructs a new Agent from provided `definitions`"""
+        """
+        Parses an agent from provided `definitions`
+
+        Args:
+            definitions: dictionary representation of an agent
+
+        Returns:
+            new agent
+
+        Raises:
+            ScenarioError: if definitions are incomplete or erroneous, logged on level "ERROR"
+        """
         return Agent.from_dict(definitions)
 
     @staticmethod
     def new_contract_from_dict(definitions: dict) -> Contract:
-        """Constructs a new Contract from provided `definitions`"""
+        """
+        Parses contract from given `definitions`
+
+        Args:
+            definitions: dictionary representation of a contract
+
+        Returns:
+            new contract
+
+        Raises:
+            ContractError: if definitions are incomplete or erroneous, logged on level "ERROR"
+        """
         return Contract.from_dict(definitions)
 
     @staticmethod
     def new_string_set_from_dict(definition: StringSet.StringSetType) -> StringSet:
-        """Constructs a new StringSet from provided `definitions`"""
+        """
+        Returns string set initialised from `definition`
+
+        Args:
+            definition: dictionary representation of string set
+
+        Returns:
+            new string set
+
+        Raises:
+            StringSetError: if definitions are incomplete or erroneous, logged on level "ERROR"
+        """
         return StringSet.from_dict(definition)

fameio/input/scenario/generalproperties.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
@@ -8,7 +8,7 @@ from typing import Final
 from fameio.logs import log
 from fameio.time import FameTime
 from fameio.tools import keys_to_lower
-from .exception import get_or_default, get_or_raise
+from .exception import get_or_raise
 
 
 class GeneralProperties:
@@ -39,9 +39,20 @@ class GeneralProperties:
 
     @classmethod
     def from_dict(cls, definitions: dict) -> GeneralProperties:
-        """Parse general properties from provided `definitions`"""
+        """
+        Parse general properties from provided `definitions`
+
+        Args:
+            definitions: dictionary representation of general properties
+
+        Returns:
+            new GeneralProperties
+
+        Raises:
+            ScenarioError: if definitions are incomplete or erroneous, logged on level "ERROR"
+        """
         definitions = keys_to_lower(definitions)
-        run_id = get_or_default(definitions, GeneralProperties.KEY_RUN, 1)
+        run_id = definitions.get(GeneralProperties.KEY_RUN, 1)
 
         simulation_definition = keys_to_lower(
             get_or_raise(
@@ -64,12 +75,12 @@ class GeneralProperties:
                 GeneralProperties._ERR_MISSING_KEY,
             )
         )
-        random_seed = get_or_default(simulation_definition, GeneralProperties.KEY_SEED, 1)
+        random_seed = simulation_definition.get(GeneralProperties.KEY_SEED, 1)
         return cls(run_id, start_time, stop_time, random_seed)
 
     def to_dict(self) -> dict:
         """Serializes the general properties to a dict"""
-        result = {self.KEY_RUN: self._run_id}
+        result: dict = {self.KEY_RUN: self._run_id}
         simulation_dict = {
             self.KEY_START: self.simulation_start_time,
             self.KEY_STOP: self.simulation_stop_time,

fameio/input/scenario/scenario.py

@@ -1,19 +1,20 @@
-# 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 typing import Final
+from typing import Final, Any
 
+from fameio.input import SchemaError
 from fameio.input.metadata import Metadata
+from fameio.input.scenario.agent import Agent
+from fameio.input.scenario.contract import Contract
+from fameio.input.scenario.exception import get_or_raise, log_scenario_error
+from fameio.input.scenario.fameiofactory import FameIOFactory
+from fameio.input.scenario.generalproperties import GeneralProperties
+from fameio.input.scenario.stringset import StringSet
 from fameio.input.schema import Schema
 from fameio.tools import keys_to_lower
-from .agent import Agent
-from .contract import Contract
-from .exception import get_or_default, get_or_raise
-from .fameiofactory import FameIOFactory
-from .generalproperties import GeneralProperties
-from .stringset import StringSet
 
 
 class Scenario(Metadata):
@@ -26,42 +27,124 @@ class Scenario(Metadata):
     KEY_STRING_SETS: Final[str] = "StringSets".lower()
 
     _MISSING_KEY = "Scenario definition misses required key '{}'."
+    _ERR_SCHEMA = "Could not create scenario: Definition of Schema has errors."
+    _ERR_STRING_SET = "Could not create scenario: Definition of StringSet '{}' has errors."
+    _ERR_MULTI_CONTRACT = "Could not create scenario: Definition of Contracts has errors: {}"
+    _ERR_CONTRACT = "Could not create scenario: Definition of Contract has errors: {}"
 
     def __init__(self, schema: Schema, general_props: GeneralProperties) -> None:
         super().__init__()
         self._schema = schema
         self._general_props = general_props
-        self._string_sets = {}
-        self._agents = []
-        self._contracts = []
+        self._string_sets: dict[str, StringSet] = {}
+        self._agents: list[Agent] = []
+        self._contracts: list[Contract] = []
 
     @classmethod
-    def from_dict(cls, definitions: dict, factory=FameIOFactory()) -> Scenario:
-        """Parse scenario from provided `definitions` using given `factory`"""
-        definitions = keys_to_lower(definitions)
+    def from_dict(cls, definitions: dict, factory: FameIOFactory = FameIOFactory()) -> Scenario:
+        """
+        Parse scenario from provided `definitions` using given `factory`
 
-        schema = factory.new_schema_from_dict(get_or_raise(definitions, Scenario.KEY_SCHEMA, Scenario._MISSING_KEY))
-        general_props = factory.new_general_properties_from_dict(
-            get_or_raise(definitions, Scenario.KEY_GENERAL, Scenario._MISSING_KEY)
-        )
-        scenario = cls(schema, general_props)
-        scenario._extract_metadata(definitions)
+        Args:
+            definitions: dictionary representation of scenario
+            factory: helper class with static helpers to instantiate scenario components
 
-        for name, string_set_definition in get_or_default(definitions, Scenario.KEY_STRING_SETS, {}).items():
-            scenario.add_string_set(name, factory.new_string_set_from_dict(string_set_definition))
+        Returns:
+            new Scenario
 
-        for agent_definition in get_or_default(definitions, Scenario.KEY_AGENTS, []):
-            scenario.add_agent(factory.new_agent_from_dict(agent_definition))
+        Raises:
+            ScenarioError: if scenario definitions are incomplete or erroneous, logged with level "ERROR"
+        """
+        definitions = keys_to_lower(definitions)
 
-        for multi_contract_definition in get_or_default(definitions, Scenario.KEY_CONTRACTS, []):
-            for single_contract_definition in Contract.split_contract_definitions(multi_contract_definition):
-                scenario.add_contract(factory.new_contract_from_dict(single_contract_definition))
+        schema = Scenario._extract_schema(definitions, factory)
+        general_properties_definition = get_or_raise(definitions, Scenario.KEY_GENERAL, Scenario._MISSING_KEY)
+        general_properties = factory.new_general_properties_from_dict(general_properties_definition)
+        scenario = cls(schema, general_properties)
+        scenario._extract_metadata(definitions)
 
+        scenario._string_sets = Scenario._extract_string_sets(definitions, factory)
+        scenario._agents = [
+            factory.new_agent_from_dict(agent_definition)
+            for agent_definition in definitions.get(Scenario.KEY_AGENTS, [])
+        ]
+        scenario._contracts = Scenario._extract_contracts(definitions, factory)
         return scenario
 
+    @staticmethod
+    def _extract_schema(definitions: dict, factory: FameIOFactory) -> Schema:
+        """
+        Extract schema from given definitions and create Schema from it
+
+        Args:
+            definitions: dictionary representation of scenario
+            factory: helper class with static helpers to instantiate scenario components
+
+        Returns:
+            new schema
+
+        Raises:
+            ScenarioError: if schema definitions are missing, incomplete, or erroneous; logged on level "ERROR"
+        """
+        schema_definition = get_or_raise(definitions, Scenario.KEY_SCHEMA, Scenario._MISSING_KEY)
+        try:
+            return factory.new_schema_from_dict(schema_definition)
+        except SchemaError as e:
+            raise log_scenario_error(Scenario._ERR_SCHEMA) from e
+
+    @staticmethod
+    def _extract_string_sets(definitions: dict, factory: FameIOFactory) -> dict[str, StringSet]:
+        """
+        Extract string sets from given definitions and create dictionary from it
+
+        Args:
+            definitions: dictionary representation of scenario
+            factory: helper class with static helpers to instantiate scenario components
+
+        Returns:
+            dictionary of string set names associated with their corresponding string set
+
+        Raises:
+            ScenarioError: if string set definitions are incomplete or erroneous; logged on level "ERROR"
+        """
+        string_sets = {}
+        for name, string_set_definition in definitions.get(Scenario.KEY_STRING_SETS, {}).items():
+            try:
+                string_sets[name] = factory.new_string_set_from_dict(string_set_definition)
+            except StringSet.StringSetError as e:
+                raise log_scenario_error(Scenario._ERR_STRING_SET.format(name)) from e
+        return string_sets
+
+    @staticmethod
+    def _extract_contracts(definitions: dict, factory: FameIOFactory) -> list[Contract]:
+        """
+        Extract contracts from given definitions
+
+        Args:
+            definitions: dictionary representation of scenario
+            factory: helper class with static helpers to instantiate scenario components
+
+        Returns:
+            list of all created one-to-one contracts
+
+        Raises:
+            ScenarioError: if contract definitions are incomplete or erroneous; logged on level "ERROR"
+        """
+        contracts = []
+        for multi_contract_definition in definitions.get(Scenario.KEY_CONTRACTS, []):
+            try:
+                for single_contract_definition in Contract.split_contract_definitions(multi_contract_definition):
+                    try:
+                        contracts.append(factory.new_contract_from_dict(single_contract_definition))
+                    except Contract.ContractError as e:
+                        raise log_scenario_error(Scenario._ERR_CONTRACT.format(single_contract_definition)) from e
+            except Contract.ContractError as e:
+                raise log_scenario_error(Scenario._ERR_MULTI_CONTRACT.format(multi_contract_definition)) from e
+        return contracts
+
     def _to_dict(self) -> dict:
         """Serializes the scenario content to a dict"""
-        result = {
+        result: dict[str, Any] = {
             Scenario.KEY_GENERAL: self.general_properties.to_dict(),
             Scenario.KEY_SCHEMA: self.schema.to_dict(),
         }

fameio/input/scenario/stringset.py

@@ -1,38 +1,57 @@
-# 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 typing import Union, Final
+from typing import Final, Any, Union
 
+from fameio.input import InputError
 from fameio.input.metadata import Metadata, MetadataComponent, ValueContainer
+from fameio.logs import log_error
 from fameio.tools import keys_to_lower
-from .exception import log_and_raise
 
 
 class StringSet(Metadata):
     """Hosts a StringSet in the given format"""
 
+    class StringSetError(InputError):
+        """An error that occurred while parsing a StringSet definition"""
+
     KEY_VALUES: Final[str] = "Values".lower()
 
     ValueType = Union[list[str], dict[str, dict]]
     StringSetType = dict[str, Union[dict, ValueType]]
 
     _ERR_KEY_MISSING = "Missing mandatory key '{}' in StringSet definition {}."
+    _ERR_VALUE_DEFINITION = "StringSet could not be parsed."
 
-    def __init__(self, definitions=None):
+    def __init__(self, definitions: dict[str, Any] | list[Any] | None = None):
         super().__init__(definitions)
         self._value_container: ValueContainer = ValueContainer(definitions)
 
     @classmethod
     def from_dict(cls, definition: StringSetType) -> StringSet:
-        """Returns StringSet initialised from `definition`"""
+        """
+        Returns StringSet initialised from `definition`
+
+        Args:
+            definition: dictionary representation of string set
+
+        Returns:
+            new StringSet
+
+        Raises:
+            StringSetError: if definitions are incomplete or erroneous, logged on level "ERROR"
+        """
         string_set = cls(definition)
         definition = keys_to_lower(definition)
         if cls.KEY_VALUES in definition:
-            string_set._value_container = ValueContainer(definition[cls.KEY_VALUES])
+            try:
+                string_set._value_container = ValueContainer(definition[cls.KEY_VALUES])
+            except ValueContainer.ParseError as e:
+                raise log_error(StringSet.StringSetError(StringSet._ERR_VALUE_DEFINITION)) from e
         else:
-            log_and_raise(cls._ERR_KEY_MISSING.format(cls.KEY_VALUES, definition))
+            raise log_error(StringSet.StringSetError(cls._ERR_KEY_MISSING.format(cls.KEY_VALUES, definition)))
         return string_set
 
     def _to_dict(self) -> dict[str, dict[str, dict[str, dict[str, dict]]]]:
@@ -43,6 +62,6 @@ class StringSet(Metadata):
         """Returns values and their associated MetadataComponent"""
         return self._value_container.values
 
-    def is_in_set(self, key: str) -> bool:
+    def is_in_set(self, key: Any) -> bool:
         """Returns True if `key` is a valid name in this StringSet"""
         return self._value_container.has_value(key)

fameio/input/schema/__init__.py

@@ -1,8 +1,8 @@
-# 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 .agenttype import AgentType
-from .attribute import AttributeSpecs, AttributeType
-from .java_packages import JavaPackages
-from .schema import Schema
+from .agenttype import AgentType  # noqa: F401
+from .attribute import AttributeSpecs, AttributeType  # noqa: F401
+from .java_packages import JavaPackages  # noqa: F401
+from .schema import Schema  # noqa: F401

fameio/input/schema/agenttype.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 @@ from typing import Any, Final
 
 from fameio.input import InputError, SchemaError
 from fameio.input.metadata import Metadata, MetadataComponent, ValueContainer
-from fameio.logs import log_error_and_raise, log
+from fameio.logs import log, log_error
 from fameio.tools import keys_to_lower
 from .attribute import AttributeSpecs
 
@@ -32,11 +32,14 @@ class AgentType(Metadata):
         Initialise a new AgentType
 
         Args:
-            name: name of the AgenType - must not be None, empty or only whitespaces
+            name: name of the AgenType
+
+        Raises:
+            SchemaError: if name is None, empty, or only whitespaces, logged with level "ERROR"
         """
         super().__init__()
         if not name or name.isspace():
-            log_error_and_raise(SchemaError(AgentType._ERR_NAME_INVALID.format(name)))
+            raise log_error(SchemaError(AgentType._ERR_NAME_INVALID.format(name)))
         self._name = name
         self._attributes: dict[str, AttributeSpecs] = {}
         self._products: ValueContainer = ValueContainer()
@@ -53,6 +56,9 @@ class AgentType(Metadata):
 
         Returns:
             a new instance of AgentType
+
+        Raises:
+            SchemaError: if definitions are invalid, logged with level "ERROR"
         """
         agent_type = cls(name)
         agent_type._extract_metadata(definitions)
@@ -83,15 +89,27 @@ class AgentType(Metadata):
 
     @staticmethod
     def _read_values(section: str, agent_type: str, values: Any) -> ValueContainer:
-        """Returns ValueContainer for `section` of in specifications of `agent_type` extracted from given `values`"""
+        """
+        Returns ValueContainer for `section` of in specifications of `agent_type` extracted from given `values`
+
+        Args:
+            section: key of the section that contains the values
+            agent_type: name of the agent type that the values are associated with
+            values: list or dict with value definitions
+
+        Returns:
+            container for all the extracted values
+
+        Raises:
+            SchemaError: if the values are ill-formatted, logged with level "ERROR"
+        """
         try:
             data = ValueContainer(values)
-        except InputError:
-            log_error_and_raise(SchemaError(AgentType._ERR_UNKNOWN_STRUCTURE.format(section, agent_type, values)))
-        else:
-            if not all([isinstance(item, str) for item in data.as_list()]):
-                log_error_and_raise(SchemaError(AgentType._ERR_NO_STRING.format(section, agent_type, data.as_list())))
-            return data
+        except InputError as e:
+            raise log_error(SchemaError(AgentType._ERR_UNKNOWN_STRUCTURE.format(section, agent_type, values))) from e
+        if not all(isinstance(item, str) for item in data.as_list()):
+            raise log_error(SchemaError(AgentType._ERR_NO_STRING.format(section, agent_type, data.as_list())))
+        return data
 
     @property
     def name(self) -> str: