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

fameio/input/resolver.py

@@ -1,9 +1,10 @@
-# 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
+
 import glob
 from os import path
-from typing import Optional
 
 
 class PathResolver:
@@ -23,7 +24,7 @@ class PathResolver:
         return glob.glob(absolute_path)
 
     # noinspection PyMethodMayBeStatic
-    def resolve_series_file_path(self, file_name: str) -> Optional[str]:
+    def resolve_series_file_path(self, file_name: str) -> str | None:
         """
         Searches for the file in the current working directory and returns its absolute file path
 
@@ -38,7 +39,7 @@ class PathResolver:
         return file_name if path.isabs(file_name) else PathResolver._search_file_in_directory(file_name, path.curdir)
 
     @staticmethod
-    def _search_file_in_directory(file_name: str, directory: str) -> Optional[str]:
+    def _search_file_in_directory(file_name: str, directory: str) -> str | None:
         """Returns path to said `file_name` relative to specified `directory` if file was found there, None otherwise"""
         file_path = path.join(directory, file_name)
         return file_path if path.exists(file_path) else None

fameio/input/scenario/__init__.py

@@ -1,10 +1,9 @@
-# SPDX-FileCopyrightText: 2023 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
-
-from .agent import Agent
-from .attribute import Attribute
-from .contract import Contract
-from .generalproperties import GeneralProperties
-from .scenario import Scenario
-from .stringset import StringSet
+from .agent import Agent  # noqa: F401
+from .attribute import Attribute  # noqa: F401
+from .contract import Contract  # noqa: F401
+from .generalproperties import GeneralProperties  # noqa: F401
+from .scenario import Scenario  # noqa: F401
+from .stringset import StringSet  # noqa: F401

fameio/input/scenario/agent.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,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(type(agent_id) is 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():
@@ -79,7 +113,6 @@ class Agent(Metadata):
 
     def _notify_data_changed(self):
         """Placeholder method used to signal data changes to derived types"""
-        pass
 
     @property
     def id(self) -> int:
@@ -89,7 +122,7 @@ class Agent(Metadata):
     @property
     def display_id(self) -> str:
         """Returns the ID of the Agent as a string for display purposes"""
-        return "#{}".format(self._id)
+        return f"#{self._id}"
 
     @property
     def type_name(self) -> str:

fameio/input/scenario/attribute.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
@@ -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,28 +78,27 @@ 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)
-        elif isinstance(definitions, dict):
+        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)
-        else:
-            return Attribute.__DefinitionType.VALUE
+        return Attribute.__DefinitionType.VALUE
 
     @staticmethod
     def _get_data_type_list(definitions: list[Any]) -> Attribute.__DefinitionType:
         """Returns type of data from a given non-empty list `definitions`"""
-        if all([Attribute._is_value_definition(entry) for entry in definitions]):
+        if all(Attribute._is_value_definition(entry) for entry in definitions):
             return Attribute.__DefinitionType.VALUE_LIST
-        elif Attribute._is_list_of_dict(definitions):
+        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:
         """Returns True if given `definitions` is a list of (only) dict"""
-        return all([isinstance(entry, dict) for entry in definitions])
+        return all(isinstance(entry, dict) for entry in definitions)
 
     @staticmethod
     def _get_data_type_dict(definitions: dict[str, Any]) -> Attribute.__DefinitionType:
@@ -108,13 +106,13 @@ class Attribute(Metadata):
         low_keys = keys_to_lower(definitions)
         if Attribute.KEY_VALUE in low_keys.keys():
             return Attribute.__DefinitionType.VALUE
-        elif Attribute.KEY_VALUES in low_keys.keys():
+        if Attribute.KEY_VALUES in low_keys.keys():
             values = low_keys[Attribute.KEY_VALUES]
-            if all([Attribute._is_value_definition(entry) for entry in values]):
+            if all(Attribute._is_value_definition(entry) for entry in values):
                 return Attribute.__DefinitionType.VALUE_LIST
-            elif Attribute._is_list_of_dict(values):
+            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
@@ -158,7 +156,7 @@ class Attribute(Metadata):
         """Returns value or list of values if available on this Attribute (ignoring any Metadata), else None"""
         if self._value is not None:
             return self._value
-        elif self._value_list is not None:
+        if self._value_list is not None:
             return [item.value for item in self._value_list]
         return None
 
@@ -169,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:
@@ -179,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
@@ -188,16 +186,17 @@ class Attribute(Metadata):
     def _to_dict(self) -> dict[str, Any]:
         if self._value is not None:
             return {self.KEY_VALUE: self._value}
-        elif self._value_list is not None:
+        if self._value_list is not None:
             return {
                 self.KEY_VALUES: [{self.KEY_VALUE: entry.value, **entry.meta.to_dict()} for entry in self._value_list]
             }
-        elif self._nested is not None:
+        if self._nested is not None:
             return {name: attribute.to_dict() for name, attribute in self.nested.items()}
-        elif self._nested_list is not None:
+        if self._nested_list is not None:
             return {
                 self.KEY_VALUES: [
                     {**{name: attribute.to_dict() for name, attribute in entry.value.items()}, **entry.meta.to_dict()}
                     for entry in self._nested_list
                 ]
             }
+        return {}

fameio/input/scenario/contract.py

@@ -1,21 +1,24 @@
-# SPDX-FileCopyrightText: 2023 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 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,14 +29,17 @@ 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__(
         self,
         sender_id: int,
@@ -41,27 +47,44 @@ 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"""
-        pass
 
     @property
     def product_name(self) -> str:
@@ -76,7 +99,7 @@ class Contract(Metadata):
     @property
     def display_sender_id(self) -> str:
         """Returns the sender ID of the contract as a string for display purposes"""
-        return "#{}".format(self._sender_id)
+        return f"#{self._sender_id}"
 
     @property
     def receiver_id(self) -> int:
@@ -86,7 +109,7 @@ class Contract(Metadata):
     @property
     def display_receiver_id(self) -> str:
         """Returns the receiver ID of the contract as a string for display purposes"""
-        return "#{}".format(self._receiver_id)
+        return f"#{self._receiver_id}"
 
     @property
     def delivery_interval(self) -> int:
@@ -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,19 +288,23 @@ 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 in range(len(senders)):
-                contracts.append(Contract._copy_contract(senders[index], receivers[0], base_data))
+            for index, sender in enumerate(senders):
+                contracts.append(Contract._copy_contract(sender, receivers[0], base_data))
         elif len(senders) == 1 and len(receivers) > 1:
-            for index in range(len(receivers)):
-                contracts.append(Contract._copy_contract(senders[0], receivers[index], base_data))
+            for index, receiver in enumerate(receivers):
+                contracts.append(Contract._copy_contract(senders[0], receiver, base_data))
         elif len(senders) == len(receivers):
-            for index in range(len(senders)):
+            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