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

fameio/cli/__init__.py

@@ -1,5 +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.cli.parser import update_default_config
+from fameio.cli.parser import update_default_config  # noqa: F401

fameio/cli/convert_results.py

@@ -1,8 +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 argparse
-from typing import Any, Optional
+from typing import Any
 
 from fameio.cli.options import Options, ResolveOptions, TimeOptions
 from fameio.cli.parser import (
@@ -38,7 +40,7 @@ _INFILE_PATH_HELP = "Provide path to protobuf file"
 _OUTFILE_PATH_HELP = "Provide path to folder to store output .csv files"
 
 
-def handle_args(args: list[str], defaults: Optional[dict[Options, Any]] = None) -> dict[Options, Any]:
+def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) -> dict[Options, Any]:
     """
     Handles command line arguments and returns `run_config` for convert_results script
 
@@ -54,7 +56,7 @@ def handle_args(args: list[str], defaults: Optional[dict[Options, Any]] = None)
     return map_namespace_to_options_dict(parsed)
 
 
-def _prepare_parser(defaults: Optional[dict[Options, Any]]) -> argparse.ArgumentParser:
+def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentParser:
     """
     Creates a parser with given defaults to handle `make_config` configuration arguments
 

fameio/cli/make_config.py

@@ -1,9 +1,11 @@
-# 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 argparse
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from fameio.cli.options import Options
 from fameio.cli.parser import (
@@ -31,7 +33,7 @@ _ENCODING_HELP = (
 )
 
 
-def handle_args(args: list[str], defaults: Optional[dict[Options, Any]] = None) -> dict[Options, Any]:
+def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) -> dict[Options, Any]:
     """
     Converts given `arguments` and returns a configuration for the make_config script
 
@@ -47,7 +49,7 @@ def handle_args(args: list[str], defaults: Optional[dict[Options, Any]] = None)
     return map_namespace_to_options_dict(parsed)
 
 
-def _prepare_parser(defaults: Optional[dict[Options, Any]]) -> argparse.ArgumentParser:
+def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentParser:
     """
     Creates a parser with given defaults to handle `make_config` configuration arguments
 

fameio/cli/options.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
 import argparse
@@ -12,8 +12,8 @@ class ParsableEnum(Enum):
     def instantiate(cls, name: str) -> Enum:
         try:
             return cls[name]
-        except KeyError:
-            raise argparse.ArgumentTypeError(f"'{name}' is not a valid option")
+        except KeyError as e:
+            raise argparse.ArgumentTypeError(f"'{name}' is not a valid option") from e
 
     def __str__(self):
         return self.name

fameio/cli/parser.py

@@ -1,18 +1,19 @@
-# 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 copy
 from argparse import ArgumentParser, ArgumentTypeError, BooleanOptionalAction, Namespace
-from enum import Enum
 from pathlib import Path
-from typing import Optional, Any, Union
+from typing import Any
 
 from fameio.cli.options import TimeOptions, ResolveOptions, Options
 from fameio.logs import LogLevel
 
 _ERR_INVALID_MERGING_DEFAULT = "Invalid merge-times default: needs list of 3 integers separated by spaces but was: '{}'"
 
-_OPTION_ARGUMENT_NAME: dict[str, Union[Options, dict]] = {
+_OPTION_ARGUMENT_NAME: dict[str, Options] = {
     "file": Options.FILE,
     "log": Options.LOG_LEVEL,
     "logfile": Options.LOG_FILE,
@@ -28,7 +29,7 @@ _OPTION_ARGUMENT_NAME: dict[str, Union[Options, dict]] = {
 }
 
 
-def add_file_argument(parser: ArgumentParser, default: Optional[Path], help_text: str) -> None:
+def add_file_argument(parser: ArgumentParser, default: Path | None, help_text: str) -> None:
     """
     Adds 'file' argument to the provided `parser` with the provided `help_text`.
     If a default is not specified, the argument is required (optional otherwise)
@@ -44,16 +45,16 @@ def add_file_argument(parser: ArgumentParser, default: Optional[Path], help_text
         parser.add_argument("-f", "--file", type=Path, required=True, help=help_text)
 
 
-def add_select_agents_argument(parser: ArgumentParser, default: list[str]) -> None:
+def add_select_agents_argument(parser: ArgumentParser, default_value: list[str] | None) -> None:
     """Adds optional repeatable string argument 'agent' to given `parser`"""
-    help_text = "Provide list of agents to extract (default=None)"
-    parser.add_argument("-a", "--agents", nargs="*", type=str, default=default, help=help_text)
+    help_text = f"Provide list of agents to extract (default={default_value})"
+    parser.add_argument("-a", "--agents", nargs="*", type=str, default=default_value, help=help_text)
 
 
-def add_logfile_argument(parser: ArgumentParser, default: Path) -> None:
+def add_logfile_argument(parser: ArgumentParser, default_value: Path | None) -> None:
     """Adds optional argument 'logfile' to given `parser`"""
-    help_text = "provide logging file (default=None)"
-    parser.add_argument("-lf", "--logfile", type=Path, default=default, help=help_text)
+    help_text = f"provide logging file (default={default_value})"
+    parser.add_argument("-lf", "--logfile", type=Path, default=default_value, help=help_text)
 
 
 def add_output_argument(parser: ArgumentParser, default_value, help_text: str) -> None:
@@ -63,7 +64,7 @@ def add_output_argument(parser: ArgumentParser, default_value, help_text: str) -
 
 def add_log_level_argument(parser: ArgumentParser, default_value: str) -> None:
     """Adds optional argument 'log' to given `parser`"""
-    help_text = "choose logging level (default: {})".format(default_value)
+    help_text = f"choose logging level (default={default_value})"
     # noinspection PyTypeChecker
     parser.add_argument(
         "-l",
@@ -75,14 +76,14 @@ def add_log_level_argument(parser: ArgumentParser, default_value: str) -> None:
     )
 
 
-def add_encoding_argument(parser: ArgumentParser, default_value: Optional[str], help_text: str) -> None:
+def add_encoding_argument(parser: ArgumentParser, default_value: str | None, help_text: str) -> None:
     """Adds optional argument `enc` to given parser"""
     parser.add_argument("-enc", "--encoding", type=str, default=default_value, help=help_text)
 
 
 def add_single_export_argument(parser: ArgumentParser, default_value: bool) -> None:
     """Adds optional repeatable string argument 'agent' to given `parser`"""
-    help_text = "Enable export of single agents (default=False)"
+    help_text = f"Enable export of single agents (default={default_value})"
     parser.add_argument(
         "-se",
         "--single-export",
@@ -94,7 +95,7 @@ def add_single_export_argument(parser: ArgumentParser, default_value: bool) -> N
 
 def add_memory_saving_argument(parser: ArgumentParser, default_value: bool) -> None:
     """Adds optional bool argument to given `parser` to enable memory saving mode"""
-    help_text = "Reduces memory usage profile at the cost of runtime (default=False)"
+    help_text = f"Reduces memory usage profile at the cost of runtime (default={default_value})"
     parser.add_argument(
         "-m",
         "--memory-saving",
@@ -104,10 +105,10 @@ def add_memory_saving_argument(parser: ArgumentParser, default_value: bool) -> N
     )
 
 
-def add_resolve_complex_argument(parser: ArgumentParser, default_value: Union[ResolveOptions, str]):
+def add_resolve_complex_argument(parser: ArgumentParser, default_value: ResolveOptions | str):
     """Instructs given `parser` how to deal with complex field outputs"""
     default_value = default_value if isinstance(default_value, ResolveOptions) else ResolveOptions[default_value]
-    help_text = f"How to deal with complex index columns? (default={default_value})"
+    help_text = f"How to deal with complex index columns? (default={default_value.name})"
     parser.add_argument(
         "-cc",
         "--complex-column",
@@ -118,10 +119,10 @@ def add_resolve_complex_argument(parser: ArgumentParser, default_value: Union[Re
     )
 
 
-def add_time_argument(parser: ArgumentParser, default_value: Union[TimeOptions, str]) -> None:
+def add_time_argument(parser: ArgumentParser, default_value: TimeOptions | str) -> None:
     """Adds optional argument to given `parser` to define conversion of TimeSteps"""
     default_value = default_value if isinstance(default_value, TimeOptions) else TimeOptions[default_value]
-    help_text = "Apply conversion of time steps to given format (default=UTC)"
+    help_text = f"Apply conversion of time steps to given format (default={default_value.name})"
     parser.add_argument(
         "-t",
         "--time",
@@ -132,14 +133,14 @@ def add_time_argument(parser: ArgumentParser, default_value: Union[TimeOptions,
     )
 
 
-def add_merge_time_argument(parser: ArgumentParser, defaults: Optional[list[int]] = None) -> None:
+def add_merge_time_argument(parser: ArgumentParser, defaults: list[int] | None = None) -> None:
     """Adds optional three-fold argument for merging of TimeSteps to given `parser`"""
     if defaults is None:
         defaults = []
     if (
         not isinstance(defaults, list)
         or len(defaults) not in [0, 3]
-        or not all([isinstance(value, int) for value in defaults])
+        or not all(isinstance(value, int) for value in defaults)
     ):
         raise ArgumentTypeError(_ERR_INVALID_MERGING_DEFAULT.format(repr(defaults)))
 
@@ -150,22 +151,33 @@ def add_merge_time_argument(parser: ArgumentParser, defaults: Optional[list[int]
     parser.add_argument("-mt", "--merge-times", type=int, nargs=3, default=defaults, help=help_text)
 
 
-def add_inputs_recovery_argument(parser: ArgumentParser, default: bool) -> None:
+def add_inputs_recovery_argument(parser: ArgumentParser, default_value: bool) -> None:
     """Adds optional bool argument to given `parser` to recover inputs"""
-    help_text = "If --(no-)input-recovery is specified, (no) inputs will be recovered"
+    arg_name = "input-recovery"
+    default_str = "--" + ("no-" if not default_value else "") + arg_name
+    help_text = f"If --(no-)input-recovery is specified, (no) inputs will be recovered (default={default_str})"
     parser.add_argument(
-        "--input-recovery",
+        f"--{arg_name}",
         action=BooleanOptionalAction,
-        default=default,
+        default=default_value,
         help=help_text,
     )
 
 
-def update_default_config(config: Optional[dict], default: dict) -> dict:
-    """Returns `default` config with updated fields received from `config`"""
-    result = copy.deepcopy(default)
-    if config:
-        for name, option in config.items():
+def update_default_config(overrides: dict[Options, Any] | None, defaults: dict[Options, Any]) -> dict[Options, Any]:
+    """
+    Returns `defaults` with updated fields received from `overrides`
+
+    Args:
+        overrides: updates to be applied to `defaults`
+        defaults: base values, possibly replaced by options specified in `config`
+
+    Returns:
+        Deep copy of given `defaults` with updates values as specified in `overrides`
+    """
+    result = copy.deepcopy(defaults)
+    if overrides:
+        for name, option in overrides.items():
             result[name] = option
     return result
 
@@ -183,7 +195,7 @@ def map_namespace_to_options_dict(parsed: Namespace) -> dict[Options, Any]:
     return _map_namespace_to_options(parsed, _OPTION_ARGUMENT_NAME)
 
 
-def _map_namespace_to_options(parsed: Namespace, names_to_options: dict[str, Enum]) -> dict[Options, Any]:
+def _map_namespace_to_options(parsed: Namespace, names_to_options: dict[str, Options]) -> dict[Options, Any]:
     """
     Maps given parsing results to their corresponding configuration option; elements that cannot be mapped are ignored.
     If a configuration option has inner elements, these well be also read and added as inner dictionary.

fameio/input/__init__.py

@@ -4,24 +4,16 @@
 
 
 class InputError(Exception):
-    """An error that occurred while parsing any kind of input"""
-
-    pass
+    """An error that occurred while preparing a fame input file"""
 
 
 class SchemaError(InputError):
     """An error that occurred while parsing a Schema"""
 
-    pass
-
 
 class ScenarioError(InputError):
     """An error that occurred while parsing a Scenario"""
 
-    pass
-
 
 class YamlLoaderError(InputError):
     """An error that occurred while parsing a YAML file"""
-
-    pass

fameio/input/loader/__init__.py

@@ -1,16 +1,18 @@
-# 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 pathlib import Path
 from typing import Any
 
 import yaml
 
 from fameio.input import YamlLoaderError
-from fameio.input.resolver import PathResolver
 from fameio.input.loader.controller import LoaderController
 from fameio.input.loader.loader import FameYamlLoader
-from fameio.logs import log, log_critical_and_raise
+from fameio.input.resolver import PathResolver
+from fameio.logs import log, log_critical
 
 ALLOWED_SUFFIXES: tuple[str, ...] = (".yaml", ".yml")
 
@@ -29,7 +31,7 @@ def _include_callback(own_loader: FameYamlLoader, args: yaml.Node) -> Any:
 FameYamlLoader.add_constructor(FameYamlLoader.INCLUDE_COMMAND, _include_callback)
 
 
-def load_yaml(yaml_file_path: Path, path_resolver: PathResolver = PathResolver(), encoding: str = None) -> dict:
+def load_yaml(yaml_file_path: Path, path_resolver: PathResolver = PathResolver(), encoding: str | None = None) -> dict:
     """
     Loads the YAML file from given and returns its content as a dict
 
@@ -42,14 +44,14 @@ def load_yaml(yaml_file_path: Path, path_resolver: PathResolver = PathResolver()
         Content of the specified YAML file
 
     Raises:
-        YamlLoaderError: if the YAML file could not be read
+        YamlLoaderError: if the YAML file could not be found, read, or parsed
     """
     log().info(_INFO_LOADING.format(yaml_file_path))
     _update_current_controller(path_resolver, encoding)
     return __CONTROLLERS[0].load(yaml_file_path)
 
 
-def _update_current_controller(path_resolver: PathResolver, encoding: str) -> None:
+def _update_current_controller(path_resolver: PathResolver, encoding: str | None) -> None:
     """Updates the current LoaderController to use the given `path_resolver` and `encoding`"""
     __CONTROLLERS[0] = LoaderController(path_resolver, encoding)
 
@@ -65,4 +67,4 @@ def validate_yaml_file_suffix(yaml_file: Path) -> None:
           YamlLoaderError: if given file has no YAML-associated file suffix
     """
     if yaml_file.suffix.lower() not in ALLOWED_SUFFIXES:
-        log_critical_and_raise(YamlLoaderError(_ERR_NO_YAML_SUFFIX.format(ALLOWED_SUFFIXES, yaml_file)))
+        raise log_critical(YamlLoaderError(_ERR_NO_YAML_SUFFIX.format(ALLOWED_SUFFIXES, yaml_file)))

fameio/input/loader/controller.py

@@ -1,6 +1,8 @@
-# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
 from fnmatch import fnmatch
 from pathlib import Path
 from typing import Callable, IO, Any, Final
@@ -8,9 +10,9 @@ 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.logs import log, log_critical_and_raise
+from fameio.input.resolver import PathResolver
+from fameio.logs import log, log_critical
 
 
 class LoaderController:
@@ -22,6 +24,8 @@ class LoaderController:
     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,70 @@ 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"""
-        return lambda stream: FameYamlLoader(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)
@@ -100,13 +151,13 @@ class LoaderController:
             if node:
                 if node not in data.keys():
                     message = LoaderController._ERR_NODE_MISSING.format(file_name, node_address, node)
-                    log_critical_and_raise(YamlLoaderError(message))
+                    raise log_critical(YamlLoaderError(message))
                 data = data[node]
         log().debug(LoaderController._DEBUG_SEARCH_NODE.format(file_name, node_address))
         return data
 
     @staticmethod
-    def _join_data(new_data: list, previous_data: list) -> list:
+    def _join_data(new_data: list, previous_data: list | None) -> list:
         """
         Joins two lists with data to a larger list
 
@@ -125,5 +176,4 @@ class LoaderController:
         if isinstance(new_data, list) and isinstance(previous_data, list):
             previous_data.extend(new_data)
             return previous_data
-        else:
-            log_critical_and_raise(YamlLoaderError(LoaderController._ERR_NOT_LIST))
+        raise log_critical(YamlLoaderError(LoaderController._ERR_NOT_LIST))

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,7 +7,7 @@ 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):
@@ -43,9 +43,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,7 +54,7 @@ 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]:
@@ -79,10 +80,13 @@ class FameYamlLoader(yaml.SafeLoader):
 
         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 ""
@@ -98,10 +102,13 @@ class FameYamlLoader(yaml.SafeLoader):
 
         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,10 +1,13 @@
-# 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 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):
@@ -12,7 +15,7 @@ class Metadata(ABC):
 
     KEY_METADATA: Final[str] = "Metadata".lower()
 
-    def __init__(self, definitions: Optional[Union[Any, dict[str, Any]]] = None):
+    def __init__(self, definitions: Any | dict[str, Any] | None = None):
         """
         Initialises the metadata by searching the given definitions' top level for metadata.
         Alternatively, call `_extract_metadata()` to add metadata later on.
@@ -21,7 +24,7 @@ class Metadata(ABC):
         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:
         """
         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
@@ -37,7 +40,7 @@ class Metadata(ABC):
         return self._metadata
 
     @final
-    def _extract_metadata(self, definitions: Optional[dict[str, Any]]) -> None:
+    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)
 
@@ -76,7 +79,7 @@ class MetadataComponent(Metadata):
     Metadata itself, like, e.g., Strings in a list.
     """
 
-    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]:
@@ -89,25 +92,41 @@ class ValueContainer:
     class ParseError(InputError):
         """An error that occurred while parsing content for metadata-annotated simple values"""
 
-        pass
+    _ERR_VALUES_ILL_FORMATTED = "Only Lists or Dictionaries are supported for value definitions, but was: {}"
+
+    def __init__(self, definition: dict[str, Any] | list | None = None) -> None:
+        """
+        Sets data (and metadata - if any) from given `definition`
 
-    _ERR_VALUES_ILL_FORMATTED = "Only Lists and Dictionaries are supported here, but was: {}"
+        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 {}
-        elif isinstance(definition, dict):
+        if isinstance(definition, dict):
             return {key: MetadataComponent(key_definition) for key, key_definition in definition.items()}
-        elif isinstance(definition, list):
+        if isinstance(definition, list):
             return {key: MetadataComponent() for key in definition}
-        else:
-            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]:
@@ -127,7 +146,7 @@ class ValueContainer:
         """
         return {value: component_metadata.to_dict() for value, component_metadata in self._values.items()}
 
-    def has_value(self, to_search) -> bool:
+    def has_value(self, to_search: Any) -> bool:
         """
         Returns True if given value `to_search` is a key in this ValueContainer