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

fameio/input/scenario/exception.py

@@ -1,35 +1,58 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
-from typing import NoReturn, Any, Union
+from __future__ import annotations
+
+from typing import Any
 
 from fameio.input import ScenarioError
-from fameio.logs import log_error, 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`"""
-    raise log_error(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
+
+    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.
 
-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"""
+    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:
-        raise log_error(ScenarioError(message.format(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:
-        raise log_error(ScenarioError(msg))
+def assert_or_raise(assertion: bool, error_message: str) -> None:
+    """Raises exception with given `error_message` 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]
-    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
@@ -10,30 +10,81 @@ from .stringset import StringSet
 
 class FameIOFactory:
     """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`"""
+        """Loads 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`"""
+        """Parses 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,11 +8,11 @@ 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:
-    """Hosts general properties of a scenario"""
+    """Hosts general properties of a scenario."""
 
     KEY_RUN: Final[str] = "RunId".lower()
     KEY_SIMULATION = "Simulation".lower()
@@ -39,9 +39,19 @@ class GeneralProperties:
 
     @classmethod
     def from_dict(cls, definitions: dict) -> GeneralProperties:
-        """Parse general properties from provided `definitions`"""
+        """Parses 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 +74,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}
+        """Serializes the general properties to a dict."""
+        result: dict = {self.KEY_RUN: self._run_id}
         simulation_dict = {
             self.KEY_START: self.simulation_start_time,
             self.KEY_STOP: self.simulation_stop_time,
@@ -80,20 +90,20 @@ class GeneralProperties:
 
     @property
     def run_id(self) -> int:
-        """Returns the run ID"""
+        """Returns the run ID."""
         return self._run_id
 
     @property
     def simulation_start_time(self) -> int:
-        """Returns the simulation start time"""
+        """Returns the simulation start time."""
         return self._simulation_start_time
 
     @property
     def simulation_stop_time(self) -> int:
-        """Returns the simulation stop time"""
+        """Returns the simulation stop time."""
         return self._simulation_stop_time
 
     @property
     def simulation_random_seed(self) -> int:
-        """Returns the simulation random seed"""
+        """Returns the simulation random seed."""
         return self._simulation_random_seed

fameio/input/scenario/scenario.py

@@ -1,23 +1,24 @@
-# 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):
-    """Definition of a scenario"""
+    """Definition of a scenario."""
 
     KEY_SCHEMA: Final[str] = "Schema".lower()
     KEY_GENERAL: Final[str] = "GeneralProperties".lower()
@@ -26,42 +27,120 @@ 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:
+        """Parses 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:
+        """Extracts schema from given definitions and creates 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]:
+        """Extracts string sets from given definitions and creates 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]:
+        """Extracts 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 = {
+        """Serializes the scenario content to a dict."""
+        result: dict[str, Any] = {
             Scenario.KEY_GENERAL: self.general_properties.to_dict(),
             Scenario.KEY_SCHEMA: self.schema.to_dict(),
         }
@@ -81,37 +160,37 @@ class Scenario(Metadata):
 
     @property
     def agents(self) -> list[Agent]:
-        """Returns all the agents of this scenario as a list"""
+        """Returns all the agents of this scenario as a list."""
         return self._agents
 
     def add_agent(self, agent: Agent) -> None:
-        """Adds a new agent to this scenario"""
+        """Adds a new agent to this scenario."""
         self._agents.append(agent)
 
     @property
     def contracts(self) -> list[Contract]:
-        """Returns all the contracts of this scenario as a list"""
+        """Returns all the contracts of this scenario as a list."""
         return self._contracts
 
     def add_contract(self, contract: Contract) -> None:
-        """Adds a new contract to this scenario"""
+        """Adds a new contract to this scenario."""
         self._contracts.append(contract)
 
     @property
     def schema(self) -> Schema:
-        """Returns Schema associated with this scenario"""
+        """Returns Schema associated with this scenario."""
         return self._schema
 
     @property
     def general_properties(self) -> GeneralProperties:
-        """Returns General properties of this scenario"""
+        """Returns General properties of this scenario."""
         return self._general_props
 
     @property
     def string_sets(self) -> dict[str, StringSet]:
-        """Returns StringSets of this scenario"""
+        """Returns StringSets of this scenario."""
         return self._string_sets
 
     def add_string_set(self, name: str, string_set: StringSet) -> None:
-        """Adds `string_set` with `name`"""
+        """Adds `string_set` with `name`."""
         self._string_sets[name] = string_set

fameio/input/scenario/stringset.py

@@ -1,17 +1,21 @@
-# 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"""
+    """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()
 
@@ -19,20 +23,34 @@ class StringSet(Metadata):
     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]]]]:
@@ -40,9 +58,9 @@ class StringSet(Metadata):
 
     @property
     def values(self) -> dict[str, MetadataComponent]:
-        """Returns values and their associated MetadataComponent"""
+        """Returns values and their associated MetadataComponent."""
         return self._value_container.values
 
-    def is_in_set(self, key: str) -> bool:
-        """Returns True if `key` is a valid name in this StringSet"""
+    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/agenttype.py

@@ -13,7 +13,7 @@ from .attribute import AttributeSpecs
 
 
 class AgentType(Metadata):
-    """Schema definitions for an Agent type"""
+    """Schema definitions for an Agent type."""
 
     KEY_ATTRIBUTES: Final[str] = "Attributes".lower()
     KEY_PRODUCTS: Final[str] = "Products".lower()
@@ -32,7 +32,10 @@ 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():
@@ -44,8 +47,7 @@ class AgentType(Metadata):
 
     @classmethod
     def from_dict(cls, name: str, definitions: dict) -> AgentType:
-        """
-        Creates AgentType with given `name` from specified dictionary
+        """Creates AgentType with given `name` from specified dictionary.
 
         Args:
             name: of the agent type
@@ -53,6 +55,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,7 +88,19 @@ 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` 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 as e:
@@ -94,26 +111,26 @@ class AgentType(Metadata):
 
     @property
     def name(self) -> str:
-        """Returns the agent type name"""
+        """Returns the agent type name."""
         return self._name
 
     @property
     def products(self) -> dict[str, MetadataComponent]:
-        """Returns dict of products or an empty dict if no products are defined"""
+        """Returns dict of products or an empty dict if no products are defined."""
         return self._products.values
 
     def get_product_names(self) -> list[str]:
-        """Returns list of product names or an empty list if no products are defined"""
+        """Returns list of product names or an empty list if no products are defined."""
         return self._products.as_list()
 
     @property
     def attributes(self) -> dict[str, AttributeSpecs]:
-        """Returns list of Attributes of this agent or an empty list if no attributes are defined"""
+        """Returns list of Attributes of this agent or an empty list if no attributes are defined."""
         return self._attributes
 
     @property
     def outputs(self) -> dict[str, MetadataComponent]:
-        """Returns list of outputs or an empty list if no outputs are defined"""
+        """Returns list of outputs or an empty list if no outputs are defined."""
         return self._outputs.values
 
     def _to_dict(self) -> dict: