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

fameio/input/scenario/agent.py

@@ -7,9 +7,10 @@ import ast
 from typing import Any, Final
 
 from fameio.input.metadata import Metadata
+from fameio.logs import log
 from fameio.tools import keys_to_lower
 from .attribute import Attribute
-from .exception import assert_or_raise, get_or_default, get_or_raise
+from .exception import assert_or_raise, get_or_raise
 
 
 class Agent(Metadata):
@@ -18,37 +19,70 @@ class Agent(Metadata):
     KEY_TYPE: Final[str] = "Type".lower()
     KEY_ID: Final[str] = "Id".lower()
     KEY_ATTRIBUTES: Final[str] = "Attributes".lower()
+    KEY_EXT: Final[str] = "Ext".lower()
+    RESERVED_KEYS: set[str] = {KEY_TYPE, KEY_ID, KEY_ATTRIBUTES, KEY_EXT, Metadata.KEY_METADATA}
 
-    _ERR_MISSING_KEY = "Agent requires `key` '{}' but is missing it."
-    _ERR_MISSING_TYPE = "Agent requires `type` but is missing it."
-    _ERR_MISSING_ID = "Agent requires a positive integer `id` but was '{}'."
+    _ERR_MISSING_KEY = "Agent definition requires key '{}' but is missing it."
+    _ERR_TYPE_EMPTY = "Agent `type` must not be empty."
+    _ERR_ILLEGAL_ID = "Agent requires a positive integer `id` but was '{}'."
     _ERR_DOUBLE_ATTRIBUTE = "Cannot add attribute '{}' to agent {} because it already exists."
     _ERR_ATTRIBUTE_OVERWRITE = "Agent's attributes are already set and would be overwritten."
+    _WARN_UNEXPECTED_KEY = "Ignoring unexpected key(s) {} in top level of agent with id: {}"
 
-    def __init__(self, agent_id: int, type_name: str, metadata: dict = None) -> None:
+    def __init__(self, agent_id: int, type_name: str, metadata: dict | None = None) -> None:
         """Constructs a new Agent"""
         super().__init__({Agent.KEY_METADATA: metadata} if metadata else None)
-        assert_or_raise(isinstance(agent_id, int) and agent_id >= 0, self._ERR_MISSING_ID.format(agent_id))
-        assert_or_raise(bool(type_name and type_name.strip()), self._ERR_MISSING_TYPE)
+        assert_or_raise(isinstance(agent_id, int) and agent_id >= 0, self._ERR_ILLEGAL_ID.format(agent_id))
+        assert_or_raise(bool(type_name and type_name.strip()), self._ERR_TYPE_EMPTY)
         self._id: int = agent_id
         self._type_name: str = type_name.strip()
         self._attributes: dict[str, Attribute] = {}
 
     @classmethod
     def from_dict(cls, definitions: dict) -> Agent:
-        """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"
+        """
         definitions = keys_to_lower(definitions)
-        agent_type = get_or_raise(definitions, Agent.KEY_TYPE, Agent._ERR_MISSING_TYPE)
-        agent_id = get_or_raise(definitions, Agent.KEY_ID, Agent._ERR_MISSING_ID)
-        agent = cls(agent_id, agent_type)
-        agent._extract_metadata(definitions)
-        attribute_definitions = get_or_default(definitions, Agent.KEY_ATTRIBUTES, {})
-        agent.init_attributes_from_dict(attribute_definitions)
-        agent._meta_data = get_or_default(definitions, Agent.KEY_METADATA, {})
+        agent_type = get_or_raise(definitions, Agent.KEY_TYPE, Agent._ERR_MISSING_KEY)
+        agent_id = get_or_raise(definitions, Agent.KEY_ID, Agent._ERR_MISSING_KEY)
+        Agent.validate_keys(definitions, agent_id)
+        metadata = definitions.get(Agent.KEY_METADATA, None)
+        agent = cls(agent_id, agent_type, metadata)
+        agent.init_attributes_from_dict(definitions.get(Agent.KEY_ATTRIBUTES, {}))
         return agent
 
+    @staticmethod
+    def validate_keys(data: dict, agent_id: int) -> None:
+        """
+        Logs a warning if any unexpected keys are presented at top level of `data`
+        Expected keys are defined in `Agent.RESERVED_KEYS`
+
+        Args:
+            data: agent definition to be checked
+            agent_id: id of agent to be checked
+        """
+        unexpected_keys = set(data.keys()) - Agent.RESERVED_KEYS
+        if unexpected_keys:
+            log().warning(Agent._WARN_UNEXPECTED_KEY.format(unexpected_keys, agent_id))
+
     def init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
-        """Initialize Agent `attributes` from dict; Must only be called when creating a new Agent"""
+        """
+        Initialise agent `attributes` from dict; Must only be called when creating a new Agent
+
+        Args:
+            attributes: to be set
+
+        Raises:
+            ScenarioError: if attributes were already initialised
+        """
         assert_or_raise(not self._attributes, self._ERR_ATTRIBUTE_OVERWRITE)
         self._attributes = {}
         for name, value in attributes.items():

fameio/input/scenario/attribute.py

@@ -9,7 +9,7 @@ from typing import Any, NamedTuple, Final
 
 from fameio.input.metadata import Metadata, MetadataComponent
 from fameio.tools import keys_to_lower
-from .exception import log_and_raise
+from .exception import log_scenario_error
 
 
 class Attribute(Metadata):
@@ -49,7 +49,7 @@ class Attribute(Metadata):
         """Parses an Attribute's definition"""
         self._full_name = name
         if definitions is None:
-            log_and_raise(Attribute._ERR_VALUE_MISSING.format(name))
+            raise log_scenario_error(Attribute._ERR_VALUE_MISSING.format(name))
         super().__init__(definitions)
         data_type = Attribute._get_data_type(name, definitions)
 
@@ -59,16 +59,15 @@ class Attribute(Metadata):
         self._nested_list: list[Attribute.__NestedMeta] | None = None
 
         if data_type is Attribute.__DefinitionType.VALUE:
-            value = keys_to_lower(definitions)[Attribute.KEY_VALUE] if isinstance(definitions, dict) else definitions
-            self._value = value
+            self._value = self._extract_value(definitions).value  # type: ignore[arg-type]
         elif data_type is Attribute.__DefinitionType.VALUE_LIST:
-            self._value_list = self._extract_values(definitions)
+            self._value_list = self._extract_values(definitions)  # type: ignore[arg-type]
         elif data_type is Attribute.__DefinitionType.NESTED:
-            self._nested = Attribute._build_attribute_dict(name, definitions)
+            self._nested = Attribute._build_attribute_dict(name, definitions)  # type: ignore[arg-type]
         elif data_type is Attribute.__DefinitionType.NESTED_LIST:
             self._nested_list = []
             values = keys_to_lower(definitions)[Attribute.KEY_VALUES] if isinstance(definitions, dict) else definitions
-            for list_index, definition in enumerate(values):
+            for list_index, definition in enumerate(values):  # type: ignore[arg-type]
                 list_meta = MetadataComponent(definition)
                 list_extended_name = name + Attribute.NAME_STRING_SEPARATOR + str(list_index)
                 nested_items = Attribute._build_attribute_dict(list_extended_name, definition)
@@ -79,11 +78,11 @@ class Attribute(Metadata):
         """Returns type of data derived from given `definitions`"""
         if isinstance(definitions, list):
             if len(definitions) == 0:
-                log_and_raise(Attribute._ERR_LIST_EMPTY.format(name))
+                raise log_scenario_error(Attribute._ERR_LIST_EMPTY.format(name))
             return Attribute._get_data_type_list(definitions)
         if isinstance(definitions, dict):
             if len(definitions) == 0:
-                log_and_raise(Attribute._ERR_DICT_EMPTY.format(name))
+                raise log_scenario_error(Attribute._ERR_DICT_EMPTY.format(name))
             return Attribute._get_data_type_dict(definitions)
         return Attribute.__DefinitionType.VALUE
 
@@ -94,7 +93,7 @@ class Attribute(Metadata):
             return Attribute.__DefinitionType.VALUE_LIST
         if Attribute._is_list_of_dict(definitions):
             return Attribute.__DefinitionType.NESTED_LIST
-        log_and_raise(Attribute._ERR_MIXED_DATA.format(repr(definitions)))
+        raise log_scenario_error(Attribute._ERR_MIXED_DATA.format(repr(definitions)))
 
     @staticmethod
     def _is_list_of_dict(definitions: list) -> bool:
@@ -113,7 +112,7 @@ class Attribute(Metadata):
                 return Attribute.__DefinitionType.VALUE_LIST
             if Attribute._is_list_of_dict(values):
                 return Attribute.__DefinitionType.NESTED_LIST
-            log_and_raise(Attribute._ERR_MIXED_DATA.format(repr(values)))
+            raise log_scenario_error(Attribute._ERR_MIXED_DATA.format(repr(values)))
         return Attribute.__DefinitionType.NESTED
 
     @staticmethod
@@ -168,8 +167,8 @@ class Attribute(Metadata):
 
     @property
     def nested(self) -> dict[str, Attribute]:
-        """Returns dictionary of all nested Attributes if nested Attributes are present, else None"""
-        return self._nested if self.has_nested else None
+        """Returns dictionary of all nested Attributes if nested Attributes are present, else empty dict"""
+        return self._nested if self._nested is not None else {}
 
     @property
     def has_nested_list(self) -> bool:
@@ -178,8 +177,8 @@ class Attribute(Metadata):
 
     @property
     def nested_list(self) -> list[dict[str, Attribute]]:
-        """Return list of all nested Attribute dictionaries if such are present, else None"""
-        return [entry.value for entry in self._nested_list] if self.has_nested_list else None
+        """Return list of all nested Attribute dictionaries if such are present, else an empty list"""
+        return [entry.value for entry in self._nested_list] if self._nested_list is not None else []
 
     def __repr__(self) -> str:
         return self._full_name

fameio/input/scenario/contract.py

@@ -3,19 +3,22 @@
 # SPDX-License-Identifier: Apache-2.0
 from __future__ import annotations
 
-from typing import Any, Optional, Final
+from typing import Any, Final, overload
 
+from fameio.input import InputError
 from fameio.input.metadata import Metadata
-from fameio.logs import log
-from fameio.time import FameTime
+from fameio.input.scenario.attribute import Attribute
+from fameio.logs import log, log_error
+from fameio.time import FameTime, ConversionError
 from fameio.tools import ensure_is_list, keys_to_lower
-from .attribute import Attribute
-from .exception import get_or_default, get_or_raise, log_and_raise
 
 
 class Contract(Metadata):
     """Contract between two Agents of a scenario"""
 
+    class ContractError(InputError):
+        """An error that occurred while parsing Contract definitions"""
+
     KEY_SENDER: Final[str] = "SenderId".lower()
     KEY_RECEIVER: Final[str] = "ReceiverId".lower()
     KEY_PRODUCT: Final[str] = "ProductName".lower()
@@ -26,13 +29,15 @@ class Contract(Metadata):
 
     _ERR_MISSING_KEY = "Contract requires key '{}' but is missing it."
     _ERR_MULTI_CONTRACT_CORRUPT = (
-        "Definition of Contracts is valid only for One-to-One, One-to-many, Many-to-one, "
+        "Definition of Contracts is valid only for One-to-One, One-to-Many, Many-to-One, "
         "or N-to-N sender-to-receiver numbers. Found M-to-N pairing in Contract with "
         "Senders: {} and Receivers: {}."
     )
     _ERR_INTERVAL_NOT_POSITIVE = "Contract delivery interval must be a positive integer but was: {}"
     _ERR_SENDER_IS_RECEIVER = "Contract sender and receiver have the same id: {}"
     _ERR_DOUBLE_ATTRIBUTE = "Cannot add attribute '{}' to contract because it already exists."
+    _ERR_TIME_CONVERSION = "Contract item '{}' is an ill-formatted time: '{}'"
+    _ERR_PRODUCT_EMPTY = f"A Contract's `{KEY_PRODUCT}` must be a non-emtpy string."
 
     # pylint: disable=too-many-arguments, too-many-positional-arguments
     def __init__(
@@ -42,23 +47,41 @@ class Contract(Metadata):
         product_name: str,
         delivery_interval: int,
         first_delivery_time: int,
-        expiration_time: Optional[int] = None,
-        metadata: Optional[dict] = None,
+        expiration_time: int | None = None,
+        metadata: dict | None = None,
     ) -> None:
-        """Constructs a new Contract"""
+        """
+        Constructs a new Contract
+
+        Args:
+            sender_id: unique id of sender
+            receiver_id: unique id of receiver
+            product_name: name of contracted product
+            delivery_interval: time interval in steps between contract deliveries
+            first_delivery_time: absolute time of first contract execution
+            expiration_time: absolute time at which contract execution stops
+            metadata: any metadata associated with the contract
+
+        Returns:
+            new Contract
+
+        Raises:
+            ContractError: if delivery interval is invalid, logged on level "ERROR"
+        """
         super().__init__({self.KEY_METADATA: metadata} if metadata else None)
-        assert product_name != ""
+        if product_name.strip() == "":
+            raise log_error(self.ContractError(self._ERR_PRODUCT_EMPTY))
         if sender_id == receiver_id:
             log().warning(self._ERR_SENDER_IS_RECEIVER.format(sender_id))
         if delivery_interval <= 0:
-            raise ValueError(self._ERR_INTERVAL_NOT_POSITIVE.format(delivery_interval))
+            raise log_error(self.ContractError(self._ERR_INTERVAL_NOT_POSITIVE.format(delivery_interval)))
         self._sender_id = sender_id
         self._receiver_id = receiver_id
         self._product_name = product_name
         self._delivery_interval = delivery_interval
         self._first_delivery_time = first_delivery_time
         self._expiration_time = expiration_time
-        self._attributes = {}
+        self._attributes: dict = {}
 
     def _notify_data_changed(self):
         """Placeholder method used to signal data changes to derived types"""
@@ -99,7 +122,7 @@ class Contract(Metadata):
         return self._first_delivery_time
 
     @property
-    def expiration_time(self) -> Optional[int]:
+    def expiration_time(self) -> int | None:
         """Returns the expiration time of the contract if available, None otherwise"""
         return self._expiration_time
 
@@ -109,43 +132,113 @@ class Contract(Metadata):
         return self._attributes
 
     def add_attribute(self, name: str, value: Attribute) -> None:
-        """Adds a new attribute to the Contract (raise an error if it already exists)"""
+        """
+        Adds a new attribute to the Contract
+
+        Args:
+            name: of the attribute
+            value: of the attribute
+
+        Raises:
+            ContractError: if attribute already exists, logged on level "ERROR"
+        """
         if name in self._attributes:
-            raise ValueError(self._ERR_DOUBLE_ATTRIBUTE.format(name))
+            raise log_error(self.ContractError(self._ERR_DOUBLE_ATTRIBUTE.format(name)))
         self._attributes[name] = value
         self._notify_data_changed()
 
     @classmethod
     def from_dict(cls, definitions: dict) -> Contract:
-        """Parses Contract from given `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"
+        """
         definitions = keys_to_lower(definitions)
-        sender_id = get_or_raise(definitions, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY)
-        receiver_id = get_or_raise(definitions, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY)
-        product_name = get_or_raise(definitions, Contract.KEY_PRODUCT, Contract._ERR_MISSING_KEY)
-        first_delivery_time = FameTime.convert_string_if_is_datetime(
-            get_or_raise(definitions, Contract.KEY_FIRST_DELIVERY, Contract._ERR_MISSING_KEY)
-        )
-        delivery_interval = get_or_raise(definitions, Contract.KEY_INTERVAL, Contract._ERR_MISSING_KEY)
-        expiration_time = get_or_default(definitions, Contract.KEY_EXPIRE, None)
-        expiration_time = FameTime.convert_string_if_is_datetime(expiration_time) if expiration_time else None
-
-        contract = cls(
-            sender_id,
-            receiver_id,
-            product_name,
-            delivery_interval,
-            first_delivery_time,
-            expiration_time,
-        )
+        sender_id = Contract._get_or_raise(definitions, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY)
+        receiver_id = Contract._get_or_raise(definitions, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY)
+        product_name = Contract._get_or_raise(definitions, Contract.KEY_PRODUCT, Contract._ERR_MISSING_KEY)
+
+        first_delivery_time = Contract._get_time(definitions, Contract.KEY_FIRST_DELIVERY)
+        delivery_interval = Contract._get_or_raise(definitions, Contract.KEY_INTERVAL, Contract._ERR_MISSING_KEY)
+        expiration_time = Contract._get_time(definitions, Contract.KEY_EXPIRE, mandatory=False)
+
+        contract = cls(sender_id, receiver_id, product_name, delivery_interval, first_delivery_time, expiration_time)
         contract._extract_metadata(definitions)
-        attribute_definitions = get_or_default(definitions, Contract.KEY_ATTRIBUTES, {})
-        contract._init_attributes_from_dict(attribute_definitions)
+        contract._init_attributes_from_dict(definitions.get(Contract.KEY_ATTRIBUTES, {}))
         return contract
 
+    @staticmethod
+    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:
+             ContractError: 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(Contract.ContractError(error_message.format(key)))
+        return dictionary[key]
+
+    @staticmethod
+    @overload
+    def _get_time(definitions: dict, key: str) -> int: ...  # noqa: E704
+
+    @staticmethod
+    @overload
+    def _get_time(definitions: dict, key: str, mandatory: bool) -> int | None: ...  # noqa: E704
+
+    @staticmethod
+    def _get_time(definitions: dict, key: str, mandatory: bool = True) -> int | None:
+        """
+        Extract time representation value at given key, and, if present, convert to integer, else return None
+
+        Args:
+            definitions: to search given key in
+            key: to check for an associated value
+            mandatory: if true, also raises an error if key is missing
+
+        Returns:
+            None if key is not mandatory/present, else the integer representation of the time value associated with key
+
+        Raises:
+            ContractError: if found value could not be converted or mandatory value is missing, logged on level "ERROR"
+        """
+        if key in definitions:
+            value = definitions[key]
+            try:
+                return FameTime.convert_string_if_is_datetime(value)
+            except ConversionError as e:
+                raise log_error(Contract.ContractError(Contract._ERR_TIME_CONVERSION.format(key, value))) from e
+        if mandatory:
+            raise log_error(Contract.ContractError(Contract._ERR_MISSING_KEY.format(key)))
+        return None
+
     def _init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
-        """Resets Contract `attributes` from dict; Must only be called when creating a new Contract"""
-        assert len(self._attributes) == 0
-        self._attributes = {}
+        """
+        Resets Contract `attributes` from dict
+
+        Args:
+            attributes: key-value pairs of attributes to be set
+
+        Raises:
+            ContractError: if some of provided attributes were already present
+        """
         for name, value in attributes.items():
             full_name = f"{type}.{id}{name}"
             self.add_attribute(name, Attribute(full_name, value))
@@ -169,7 +262,19 @@ class Contract(Metadata):
 
     @staticmethod
     def split_contract_definitions(multi_definition: dict) -> list[dict]:
-        """Splits given `multi_definition` dictionary into list of individual Contract definitions"""
+        """
+        Splits given dictionary of contracts with potentially more than ore sender and/or receiver into a list
+        of individual contract definitions with one sender and one receiver
+
+        Args:
+            multi_definition: contract definitions with potentially more than ore sender and/or receiver
+
+        Returns:
+            list of contract definitions with exactly one sender and receiver
+
+        Raises:
+            ContractError: if multi_definition is incomplete or erroneous, logged on level "ERROR"
+        """
         contracts = []
         base_data = {}
         multi_definition = keys_to_lower(multi_definition)
@@ -183,8 +288,12 @@ class Contract(Metadata):
         ]:
             if key in multi_definition:
                 base_data[key] = multi_definition[key]
-        senders = ensure_is_list(get_or_raise(multi_definition, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY))
-        receivers = ensure_is_list(get_or_raise(multi_definition, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY))
+        senders = ensure_is_list(
+            Contract._get_or_raise(multi_definition, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY)
+        )
+        receivers = ensure_is_list(
+            Contract._get_or_raise(multi_definition, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY)
+        )
         if len(senders) > 1 and len(receivers) == 1:
             for index, sender in enumerate(senders):
                 contracts.append(Contract._copy_contract(sender, receivers[0], base_data))
@@ -195,7 +304,7 @@ class Contract(Metadata):
             for index in range(len(senders)):  # pylint: disable=consider-using-enumerate
                 contracts.append(Contract._copy_contract(senders[index], receivers[index], base_data))
         else:
-            log_and_raise(Contract._ERR_MULTI_CONTRACT_CORRUPT.format(senders, receivers))
+            raise log_error(Contract.ContractError(Contract._ERR_MULTI_CONTRACT_CORRUPT.format(senders, receivers)))
         return contracts
 
     @staticmethod

fameio/input/scenario/exception.py

@@ -1,35 +1,61 @@
 # 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 `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]
-    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)