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

fameio/input/loader/controller.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 from fnmatch import fnmatch
 from pathlib import Path
 from typing import Callable, IO, Any, Final
@@ -8,20 +10,22 @@ from typing import Callable, IO, Any, Final
 import yaml
 
 from fameio.input import YamlLoaderError
-from fameio.input.resolver import PathResolver
 from fameio.input.loader.loader import FameYamlLoader
+from fameio.input.resolver import PathResolver
 from fameio.logs import log, log_critical
 
 
 class LoaderController:
-    """
-    Controls loading of YAML files by spawning one FameYamlLoader per file.
-    Uses same PathResolver and encoding for all files
+    """Controls loading of YAML files by spawning one FameYamlLoader per file.
+
+    Uses same PathResolver and encoding for all files.
     """
 
     DISABLING_YAML_FILE_PREFIX: Final[str] = "IGNORE_"
     NODE_SPLIT_STRING: Final[str] = ":"
 
+    _ERR_FILE_OPEN_ERROR = "Could not open file: '{}'"
+    _ERR_FILE_LOAD_ERROR = "Could not parse YAML file due to errors in (line:column): ({}:{})"
     _ERR_NODE_MISSING = "'!include_node [{}, {}]': Cannot find '{}'"
     _ERR_NOT_LIST = "!include can only combine list-like elements from multiple files!"
     _WARN_NOTHING_TO_INCLUDE = "Could not find any files matching this '!include' directive '{}'"
@@ -31,23 +35,67 @@ class LoaderController:
     _DEBUG_LOAD_FILE = "Loaded included YAML file '{}'"
     _DEBUG_FILES_INCLUDED = "!include directive '{}' yielded these files: '{}'"
 
-    def __init__(self, path_resolver: PathResolver = PathResolver(), encoding: str = None) -> None:
+    def __init__(self, path_resolver: PathResolver = PathResolver(), encoding: str | None = None) -> None:
         self._path_resolver = path_resolver
-        self._encoding: str = encoding
+        self._encoding: str | None = encoding
 
     def load(self, yaml_file_path: Path) -> dict:
-        """Spawns a new FameYamlLoader, loads the given `yaml_file_path` and returns its content"""
-        with open(yaml_file_path, "r", encoding=self._encoding) as configfile:
-            data = yaml.load(configfile, self._spawn_loader_builder())
+        """Spawns a new FameYamlLoader, loads the given `yaml_file_path` and returns its content.
+
+        Args:
+            yaml_file_path: path to YAML file that is to be loaded
+
+        Returns:
+            dictionary representation of loaded file
+
+        Raises:
+            YamlLoaderError: if file could not be read, logged with level "CRITICAL"
+        """
+        try:
+            with open(yaml_file_path, "r", encoding=self._encoding) as configfile:
+                try:
+                    data = yaml.load(configfile, self._spawn_loader_builder())  # type: ignore[arg-type]
+                except yaml.YAMLError as e:
+                    line, column = self._get_problem_position(e)
+                    raise log_critical(YamlLoaderError(self._ERR_FILE_LOAD_ERROR.format(line, column))) from e
+        except OSError as e:
+            raise log_critical(YamlLoaderError(self._ERR_FILE_OPEN_ERROR.format(yaml_file_path))) from e
         return data
 
     @staticmethod
     def _spawn_loader_builder() -> Callable[[IO], FameYamlLoader]:
-        """Returns a new Callable that instantiates a new FameYamlLoader with an IO-stream"""
+        """Returns a new Callable that instantiates a new FameYamlLoader with an IO-stream."""
         return lambda stream: FameYamlLoader(stream)  # pylint: disable=unnecessary-lambda
 
+    @staticmethod
+    def _get_problem_position(exception: yaml.YAMLError) -> tuple[str, str]:
+        """Returns problematic line and column from given error (if available).
+
+        Args:
+            exception: error thrown by yaml.load()
+
+        Returns:
+            Line and Column of error (if available), else a tuple of questions marks
+        """
+        if hasattr(exception, "problem_mark"):
+            mark = exception.problem_mark
+            return str(mark.line + 1), str(mark.column + 1)
+        return "?", "?"
+
     def include(self, loader: FameYamlLoader, include_args: yaml.Node) -> Any:
-        """Returns content loaded from the specified `include_args`"""
+        """Returns content loaded from the specified `include_args`.
+
+        Args:
+            loader: the YAML loader to be used to load the file(s) that are to be included
+            include_args: arguments of include statement
+
+        Returns:
+            content of file as specified by include
+
+        Raises:
+            YamlLoaderError: If !include statement could not be interpreted, included files could not be read,
+                or multiple included files could not be joined - logged with level "CRITICAL"
+        """
         root_path, file_pattern, node_pattern = loader.digest_include(include_args)
         files = self._resolve_imported_path(root_path, file_pattern)
         nodes = node_pattern.split(self.NODE_SPLIT_STRING)
@@ -62,8 +110,8 @@ class LoaderController:
         return joined_data
 
     def _resolve_imported_path(self, root_path: str, include_pattern: str) -> list[str]:
-        """
-        Returns a list of file paths matching the given `include_pattern` relative to the `root_path`.
+        """Returns a list of file paths matching the given `include_pattern` relative to the `root_path`.
+
         Ignores files starting with the `DISABLING_YAML_FILE_PREFIX`
         """
         file_list = self._path_resolver.resolve_file_pattern(root_path, include_pattern)
@@ -82,8 +130,7 @@ class LoaderController:
 
     @staticmethod
     def _extract_node(file_name: str, data: dict, node_address: list[str]) -> Any:
-        """
-        Returns only the part of the data that is at the specified node address
+        """Returns only the part of the data that is at the specified node address.
 
         Args:
             file_name: name of the file from which the data were read - used to enrich logging messages
@@ -106,9 +153,8 @@ class LoaderController:
         return data
 
     @staticmethod
-    def _join_data(new_data: list, previous_data: list) -> list:
-        """
-        Joins two lists with data to a larger list
+    def _join_data(new_data: list, previous_data: list | None) -> list:
+        """Joins two lists with data to a larger list.
 
         Args:
             new_data: list of any data

fameio/input/loader/loader.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 os import path
@@ -7,11 +7,11 @@ from typing import IO, Final
 import yaml
 
 from fameio.input import YamlLoaderError
-from fameio.logs import log_critical_and_raise, log
+from fameio.logs import log, log_critical
 
 
 class FameYamlLoader(yaml.SafeLoader):
-    """Custom YAML Loader for `!include` constructor"""
+    """Custom YAML Loader for `!include` constructor."""
 
     INCLUDE_COMMAND: Final[str] = "!include"
 
@@ -29,8 +29,7 @@ class FameYamlLoader(yaml.SafeLoader):
         super().__init__(stream)
 
     def digest_include(self, node: yaml.Node) -> tuple[str, str, str]:
-        """
-        Reads arguments in an !include statement and returns information which files to include
+        """Reads arguments in an !include statement and returns information which files to include.
 
         Args:
             node: the current node that is to be deconstructed; could be a file-pattern to load;
@@ -43,9 +42,10 @@ class FameYamlLoader(yaml.SafeLoader):
               `root` is a path to the current file that was read by this FameYamlLoader,
               `files` is a file pattern,
               and nodes is an optional address (list of nodes) for name for the node that is to be returned
+
+        Raises:
+            YamlLoaderError: If !include statement could not be interpreted, logged with level "CRITICAL"
         """
-        node_string = ""
-        file_pattern = None
         if isinstance(node, yaml.nodes.ScalarNode):
             file_pattern, node_string = self._read_scalar_node(node)
         elif isinstance(node, yaml.nodes.SequenceNode):
@@ -53,12 +53,13 @@ class FameYamlLoader(yaml.SafeLoader):
         elif isinstance(node, yaml.nodes.MappingNode):
             file_pattern, node_string = self._read_mapping_node(node)
         else:
-            log_critical_and_raise(YamlLoaderError(self._ERR_NODE_TYPE.format(node)))
+            raise log_critical(YamlLoaderError(self._ERR_NODE_TYPE.format(node)))
         return self._root_path, file_pattern, node_string
 
     def _read_scalar_node(self, args: yaml.nodes.ScalarNode) -> tuple[str, str]:
-        """
-        Reads and returns content of a scalar !include statement; Example: !include "file"
+        """Reads and returns content of a scalar !include statement.
+
+        Example: !include "file".
 
         Args:
             args: argument assigned to the !include statement
@@ -71,18 +72,22 @@ class FameYamlLoader(yaml.SafeLoader):
         return str(file_pattern), ""
 
     def _read_sequence_node(self, args: yaml.nodes.SequenceNode) -> tuple[str, str]:
-        """
-        Reads and returns content of a sequence !include statement; Example: !include ["file", Path:to:Node]
+        """Reads and returns content of a sequence !include statement.
+
+        Example: !include ["file", Path:to:Node].
 
         Args:
             args: argument assigned to the !include statement
 
         Returns:
             first part of argument as file path, the second part of argument as node-address
+
+        Raises:
+            YamlLoaderError: if argument count is not 1 or 2, logged with level "CRITICAL"
         """
         argument_list = self.construct_sequence(args)
         if len(argument_list) not in [1, 2]:
-            log_critical_and_raise(YamlLoaderError(self._ERR_ARGUMENT_COUNT.format(str(args))))
+            raise log_critical(YamlLoaderError(self._ERR_ARGUMENT_COUNT.format(str(args))))
 
         file_pattern = argument_list[0]
         node_string = argument_list[1] if len(argument_list) == 2 else ""
@@ -90,18 +95,22 @@ class FameYamlLoader(yaml.SafeLoader):
         return file_pattern, node_string
 
     def _read_mapping_node(self, args: yaml.nodes.MappingNode) -> tuple[str, str]:
-        """
-        Reads and returns content of a mapping !include statement; Example: !include {file="file", node="Path:to:Node"}
+        """Reads and returns content of a mapping !include statement.
+
+        Example: !include {file="file", node="Path:to:Node"}
 
         Args:
             args: argument assigned to the !include statement
 
         Returns:
             file argument as file path, node argument as node-address
+
+        Raises:
+            YamlLoaderError: if "file" key is missing, logged with level "CRITICAL"
         """
         argument_map = {str(k).lower(): v for k, v in self.construct_mapping(args).items()}
         if "file" not in argument_map.keys():
-            log_critical_and_raise(YamlLoaderError(self._ERR_FILE_KEY_MISSING.format(str(args))))
+            raise log_critical(YamlLoaderError(self._ERR_FILE_KEY_MISSING.format(str(args))))
 
         file_pattern = argument_map["file"]
         node_string = argument_map.get("node", "")

fameio/input/metadata.py

@@ -1,30 +1,35 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
-from typing import Any, Optional, final, Union, Final
+from typing import Any, final, Final
 
 from fameio.input import InputError
+from fameio.logs import log_error
 
 
 class Metadata(ABC):
-    """Hosts metadata of any kind - extend this class to optionally add metadata capability to the extending class"""
+    """Hosts metadata of any kind - extend this class to optionally add metadata capability to the extending class."""
 
     KEY_METADATA: Final[str] = "Metadata".lower()
 
-    def __init__(self, definitions: Optional[Union[Any, dict[str, Any]]] = None):
-        """
-        Initialises the metadata by searching the given definitions' top level for metadata.
+    def __init__(self, definitions: Any | dict[str, Any] | None = None):
+        """Initialises the metadata.
+
+        Search the given definitions' top level for metadata.
         Alternatively, call `_extract_metadata()` to add metadata later on.
         If metadata are found on the definitions, they get removed.
         """
         self._metadata = self.__extract_metadata(definitions)
 
     @staticmethod
-    def __extract_metadata(definitions: Optional[dict[str, Any]]) -> dict:
-        """
+    def __extract_metadata(definitions: dict[str, Any] | None) -> dict:
+        """Extract metadata from `definitions` - if present.
+
         If keyword `metadata` is found on the highest level of given `definitions`, metadata are extracted (removed) and
-        returned, otherwise, an empty dict is returned and definitions are not changed
+        returned, otherwise, an empty dict is returned and definitions are not changed.
         """
         if definitions and isinstance(definitions, dict):
             matching_key = [key for key in definitions.keys() if key.lower() == Metadata.KEY_METADATA]
@@ -33,50 +38,50 @@ class Metadata(ABC):
 
     @property
     def metadata(self) -> dict:
-        """Returns metadata dictionary or an empty dict if no metadata are defined"""
+        """Returns metadata dictionary or an empty dict if no metadata are defined."""
         return self._metadata
 
     @final
-    def _extract_metadata(self, definitions: Optional[dict[str, Any]]) -> None:
-        """If keyword `metadata` is found on the highest level of given `definitions`, metadata are removed and set"""
+    def _extract_metadata(self, definitions: dict[str, Any] | None) -> None:
+        """If keyword `metadata` is found on the highest level of given `definitions`, metadata are removed and set."""
         self._metadata = self.__extract_metadata(definitions)
 
     @final
     def get_metadata_string(self) -> str:
-        """Returns string representation of metadata dictionary or empty string if no metadata are present"""
+        """Returns string representation of metadata dictionary or empty string if no metadata are present."""
         return str(self._metadata) if self.has_metadata() else ""
 
     @final
     def has_metadata(self) -> bool:
-        """Returns True if metadata are available"""
+        """Returns True if metadata are available."""
         return bool(self._metadata)
 
     @final
     def to_dict(self) -> dict:
-        """Returns a dictionary representation of this item (using its _to_dict method) and adding its metadata"""
+        """Returns a dictionary representation of this item (using its _to_dict method) and adding its metadata."""
         child_data = self._to_dict()
         self.__enrich_with_metadata(child_data)
         return child_data
 
     @abstractmethod
     def _to_dict(self) -> dict:
-        """Returns a dictionary representation of this item excluding its metadata"""
+        """Returns a dictionary representation of this item excluding its metadata."""
 
     @final
     def __enrich_with_metadata(self, data: dict) -> dict:
-        """Returns data enriched with metadata field - if any metadata is available"""
+        """Returns data enriched with metadata field - if any metadata is available."""
         if self.has_metadata():
             data[self.KEY_METADATA] = self._metadata
         return data
 
 
 class MetadataComponent(Metadata):
-    """
-    A component that can contain metadata and may be associated with Objects that have metadata but do not extend
-    Metadata itself, like, e.g., Strings in a list.
+    """A component that can contain metadata and may be associated with other Objects.
+
+    This can be attached to objects that cannot be derived from the Metadata class themselves.
     """
 
-    def __init__(self, additional_definition: Optional[dict] = None) -> None:
+    def __init__(self, additional_definition: dict | None = None) -> None:
         super().__init__(additional_definition)
 
     def _to_dict(self) -> dict[str, dict]:
@@ -84,49 +89,64 @@ class MetadataComponent(Metadata):
 
 
 class ValueContainer:
-    """A container for values of any type with optional associated metadata"""
+    """A container for values of any type with optional associated metadata."""
 
     class ParseError(InputError):
-        """An error that occurred while parsing content for metadata-annotated simple values"""
+        """An error that occurred while parsing content for metadata-annotated simple values."""
+
+    _ERR_VALUES_ILL_FORMATTED = "Only Lists or Dictionaries are supported for value definitions, but was: {}"
 
-    _ERR_VALUES_ILL_FORMATTED = "Only Lists and Dictionaries are supported here, but was: {}"
+    def __init__(self, definition: dict[str, Any] | list | None = None) -> None:
+        """Sets data (and metadata - if any) from given `definition`.
+
+        Args:
+            definition: dictionary representation of value(s) with potential associated metadata
 
-    def __init__(self, definition: Union[dict[str, Any], list[Any]] = None) -> None:
-        """Sets data (and metadata - if any) from given `definition`"""
-        self._values = self._extract_values(definition)
+        Raises:
+            ParseError: if value definition is ill-formatted
+        """
+        self._values: dict[Any, MetadataComponent] = self._extract_values(definition)
 
     @staticmethod
-    def _extract_values(definition: Union[dict[str, Any], list[Any]]) -> dict[Any, MetadataComponent]:
-        """Returns value data (and optional metadata) extracted from given `definition`"""
+    def _extract_values(definition: dict[str, Any] | list | None) -> dict[Any, MetadataComponent]:
+        """Returns value data (and optional metadata) extracted from given `definition`.
+
+        Args:
+            definition: dictionary representation of value with potential associated metadata
+
+        Returns:
+            value linked with associated metadata (if any)
+
+        Raises:
+            ParseError: if value definition is ill-formatted, logged on level "ERROR"
+        """
         if definition is None:
             return {}
         if isinstance(definition, dict):
             return {key: MetadataComponent(key_definition) for key, key_definition in definition.items()}
         if isinstance(definition, list):
             return {key: MetadataComponent() for key in definition}
-        raise ValueContainer.ParseError(ValueContainer._ERR_VALUES_ILL_FORMATTED.format(repr(definition)))
+        raise log_error(ValueContainer.ParseError(ValueContainer._ERR_VALUES_ILL_FORMATTED.format(repr(definition))))
 
     @property
     def values(self) -> dict[str, MetadataComponent]:
-        """Returns stored values and each associated MetadataComponent"""
+        """Returns stored values and each associated MetadataComponent."""
         return self._values
 
     def as_list(self) -> list[Any]:
-        """Returns all values as list - excluding any metadata"""
+        """Returns all values as list - excluding any metadata."""
         return list(self._values.keys())
 
     def to_dict(self) -> dict[Any, dict[str, dict]]:
-        """
-        Gives all values in dictionary representation
+        """Gives all values in dictionary representation.
 
         Returns:
             If metadata are present they are mapped to each value; values without metadata associate with an empty dict
         """
         return {value: component_metadata.to_dict() for value, component_metadata in self._values.items()}
 
-    def has_value(self, to_search) -> bool:
-        """
-        Returns True if given value `to_search` is a key in this ValueContainer
+    def has_value(self, to_search: Any) -> bool:
+        """Returns True if given value `to_search` is a key in this ValueContainer.
 
         Args:
             to_search: value that is searched for in the keys of this ValueContainer
@@ -137,8 +157,7 @@ class ValueContainer:
         return to_search in self._values.keys()
 
     def is_empty(self) -> bool:
-        """
-        Returns True if no values are stored herein
+        """Returns True if no values are stored herein.
 
         Returns:
             True if no values are stored in this container, False otherwise

fameio/input/resolver.py

@@ -1,14 +1,14 @@
-# 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:
-    """
-    Class responsible for locating files referenced in a scenario.
+    """Class responsible for locating files referenced in a scenario.
 
     Such files can be the ones referenced via the YAML `!include` extension, or simply the data files (time_series)
     referenced in attributes.
@@ -18,14 +18,13 @@ class PathResolver:
 
     # noinspection PyMethodMayBeStatic
     def resolve_file_pattern(self, root_path: str, file_pattern: str) -> list[str]:
-        """Returns a list of file paths matching the given `file_pattern` in the specified `root_path`"""
+        """Returns a list of file paths matching the given `file_pattern` in the specified `root_path`."""
         absolute_path = path.abspath(path.join(root_path, file_pattern))
         return glob.glob(absolute_path)
 
     # noinspection PyMethodMayBeStatic
-    def resolve_series_file_path(self, file_name: str) -> Optional[str]:
-        """
-        Searches for the file in the current working directory and returns its absolute file path
+    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.
 
         Args:
             file_name: name of the file that is to be searched
@@ -38,7 +37,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]:
-        """Returns path to said `file_name` relative to specified `directory` if file was found there, None otherwise"""
+    def _search_file_in_directory(file_name: str, directory: str) -> str | None:
+        """Returns path to `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/agent.py

@@ -7,48 +7,84 @@ 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):
-    """Contains specifications for an agent in a scenario"""
+    """Contains specifications for an agent in a scenario."""
 
     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:
-        """Constructs a new Agent"""
+    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`"""
+        """Create new Agent from given `definitions`
+
+        Args:
+            definitions: dictionary representation of an agent
+
+        Returns:
+            new agent created from `definitions`
+
+        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():
@@ -56,21 +92,21 @@ class Agent(Metadata):
             self.add_attribute(name, Attribute(full_name, value))
 
     def add_attribute(self, name: str, value: Attribute) -> None:
-        """Adds a new attribute to the Agent (raise an error if it already exists)"""
+        """Adds a new attribute to the Agent (raise an error if it already exists)."""
         if name in self._attributes:
             raise ValueError(self._ERR_DOUBLE_ATTRIBUTE.format(name, self.display_id))
         self._attributes[name] = value
         self._notify_data_changed()
 
     def _to_dict(self) -> dict:
-        """Serializes the Agent's content to a dict"""
+        """Serializes the Agent's content to a dict."""
         result = {Agent.KEY_TYPE: self.type_name, Agent.KEY_ID: self.id}
         if self._attributes:
             result[self.KEY_ATTRIBUTES] = {name: value.to_dict() for name, value in self._attributes.items()}
         return result
 
     def to_string(self) -> str:
-        """Serializes this agent to a string"""
+        """Serializes this agent to a string."""
         return repr(self.to_dict())
 
     @classmethod
@@ -78,24 +114,24 @@ class Agent(Metadata):
         return cls.from_dict(ast.literal_eval(definitions))
 
     def _notify_data_changed(self):
-        """Placeholder method used to signal data changes to derived types"""
+        """Placeholder method used to signal data changes to derived types."""
 
     @property
     def id(self) -> int:
-        """Returns the ID of the Agent"""
+        """Returns the ID of the Agent."""
         return self._id
 
     @property
     def display_id(self) -> str:
-        """Returns the ID of the Agent as a string for display purposes"""
+        """Returns the ID of the Agent as a string for display purposes."""
         return f"#{self._id}"
 
     @property
     def type_name(self) -> str:
-        """Returns the name of the Agent type"""
+        """Returns the name of the Agent type."""
         return self._type_name
 
     @property
     def attributes(self) -> dict[str, Attribute]:
-        """Returns dictionary of all Attributes of this agent"""
+        """Returns dictionary of all Attributes of this agent."""
         return self._attributes