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

fameio/__init__.py

@@ -1,6 +1,7 @@
-# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: CC0-1.0
+"""Source code for FAME-Io."""
 
 FILE_HEADER_V1 = "famecoreprotobufstreamfilev001"  # noqa
 FILE_HEADER_V2 = "fameprotobufstreamfilev002    "  # noqa

fameio/cli/__init__.py

@@ -1,4 +1,6 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Parsing of the scripts' command line options."""
+
 from fameio.cli.parser import update_default_config  # noqa: F401

fameio/cli/convert_results.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Static methods to handle command line arguments for the command that extracts protobuf files."""
+
 from __future__ import annotations
 
 import argparse
@@ -19,6 +21,8 @@ from fameio.cli.parser import (
     add_time_argument,
     add_merge_time_argument,
     add_inputs_recovery_argument,
+    add_output_metadata_argument,
+    add_output_template_argument,
     map_namespace_to_options_dict,
 )
 
@@ -34,6 +38,8 @@ CLI_DEFAULTS = {
     Options.TIME: TimeOptions.UTC,
     Options.TIME_MERGING: None,
     Options.INPUT_RECOVERY: False,
+    Options.METADATA: True,
+    Options.METADATA_TEMPLATE: None,
 }
 
 _INFILE_PATH_HELP = "Provide path to protobuf file"
@@ -75,6 +81,8 @@ def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentPar
     add_time_argument(parser, _get_default(defaults, Options.TIME))
     add_merge_time_argument(parser, _get_default(defaults, Options.TIME_MERGING))
     add_inputs_recovery_argument(parser, _get_default(defaults, Options.INPUT_RECOVERY))
+    add_output_metadata_argument(parser, _get_default(defaults, Options.METADATA))
+    add_output_template_argument(parser, _get_default(defaults, Options.METADATA_TEMPLATE))
 
     return parser
 

fameio/cli/make_config.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Static methods to handle command line arguments for the command that creates configuration files."""
+
 from __future__ import annotations
 
 import argparse

fameio/cli/options.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds allowed command line arguments and value restrictions."""
+
 import argparse
 from enum import Enum, auto
 
@@ -36,6 +38,8 @@ class Options(Enum):
     INPUT_ENCODING = auto()
     FILE_PATTERN = auto()
     REPLACE = auto()
+    METADATA = auto()
+    METADATA_TEMPLATE = auto()
 
 
 class TimeOptions(ParsableEnum, Enum):

fameio/cli/parser.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Methods to add individual command-line arguments to parsers."""
+
 from __future__ import annotations
 
 import copy
@@ -28,6 +30,8 @@ _OPTION_ARGUMENT_NAME: dict[str, Options] = {
     "merge_times": Options.TIME_MERGING,
     "file_pattern": Options.FILE_PATTERN,
     "replace": Options.REPLACE,
+    "metadata": Options.METADATA,
+    "template": Options.METADATA_TEMPLATE,
 }
 
 
@@ -168,7 +172,7 @@ def _add_optional_boolean_argument(parser: ArgumentParser, default: bool, arg_na
     Args:
         parser: to add the argument to
         default: of the argument
-        arg_name: long name of the argument, no short name allowed; will be prepended with 'no-' for negation
+        arg_name: long name of the argument without '--', no short name allowed; prepends 'no-' for negation
         description: to create the help text from: "If --(no-)<arg_name> is specified, <description> (default=X)'
     """
     default_str = "--" + ("no-" if not default else "") + arg_name
@@ -189,6 +193,18 @@ def add_replace_argument(parser: ArgumentParser, default_value: bool) -> None:
     _add_optional_boolean_argument(parser, default_value, "replace", description)
 
 
+def add_output_metadata_argument(parser: ArgumentParser, default_value: bool) -> None:
+    """Adds optional boolean argument to given `parser` to write output metadata."""
+    description = "metadata JSON file accompanying the output files are (not) written"
+    _add_optional_boolean_argument(parser, default_value, "metadata", description)
+
+
+def add_output_template_argument(parser: ArgumentParser, default_value: Path | None) -> None:
+    """Adds optional argument to given `parser` to provide a metadata template."""
+    help_text = f"Path to metadata template file. Uses provided OEO template if not specified (default={default_value})"
+    parser.add_argument("-tmp", "--template", type=Path, help=help_text, required=False, default=default_value)
+
+
 def update_default_config(overrides: dict[Options, Any] | None, defaults: dict[Options, Any]) -> dict[Options, Any]:
     """Returns `defaults` with updated fields received from `overrides`.
 

fameio/cli/reformat.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Static methods to handle command line arguments for the command that reformats time series files."""
+
 from __future__ import annotations
 
 import argparse

fameio/input/__init__.py

@@ -1,6 +1,7 @@
-# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Classes and modules required for the compilation of FAME simulation input files in protobuf format."""
 
 
 class InputError(Exception):

fameio/input/loader/__init__.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Loading of YAML files that include custom commands."""
 from __future__ import annotations
 
 from pathlib import Path

fameio/input/loader/controller.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds the class that spawns the loaders for all YAML files to be read."""
+
 from __future__ import annotations
 
 from fnmatch import fnmatch
@@ -19,6 +21,10 @@ class LoaderController:
     """Controls loading of YAML files by spawning one FameYamlLoader per file.
 
     Uses same PathResolver and encoding for all files.
+
+    Attributes:
+        DISABLING_YAML_FILE_PREFIX: files starting with this string will be ignored
+        NODE_SPLIT_STRING: symbol that separates nodes in include patterns
     """
 
     DISABLING_YAML_FILE_PREFIX: Final[str] = "IGNORE_"
@@ -36,6 +42,12 @@ class LoaderController:
     _DEBUG_FILES_INCLUDED = "!include directive '{}' yielded these files: '{}'"
 
     def __init__(self, path_resolver: PathResolver = PathResolver(), encoding: str | None = None) -> None:
+        """Instantiate a new LoaderController.
+
+        Args:
+            path_resolver: to resolve paths to files that are to be included
+            encoding: to use when reading the file
+        """
         self._path_resolver = path_resolver
         self._encoding: str | None = encoding
 

fameio/input/loader/loader.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds the class that loads a YAML file supporting custom commands."""
+
 from os import path
 from typing import IO, Final
 

fameio/input/metadata.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Storing Metadata associated with inputs, outputs, or models."""
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod

fameio/input/resolver.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Resolving of file paths."""
+
 from __future__ import annotations
 
 import glob

fameio/input/scenario/__init__.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Classes to load, represent, modify, and save scenarios and their components."""
+
 from .agent import Agent  # noqa: F401
 from .attribute import Attribute  # noqa: F401
 from .contract import Contract  # noqa: F401

fameio/input/scenario/agent.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds the class that represents agents of scenarios."""
+
 from __future__ import annotations
 
 import ast

fameio/input/scenario/attribute.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds the class that represents agent attributes in scenarios."""
+
 from __future__ import annotations
 
 from enum import Enum, auto

fameio/input/scenario/contract.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds the class that represents contracts in scenarios."""
+
 from __future__ import annotations
 
 from typing import Any, Final, overload
@@ -10,7 +12,7 @@ from fameio.input.metadata import Metadata
 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 fameio.tools import keys_to_lower
 
 
 class Contract(Metadata):
@@ -24,6 +26,7 @@ class Contract(Metadata):
     KEY_PRODUCT: Final[str] = "ProductName".lower()
     KEY_FIRST_DELIVERY: Final[str] = "FirstDeliveryTime".lower()
     KEY_INTERVAL: Final[str] = "DeliveryIntervalInSteps".lower()
+    KEY_EVERY: Final[str] = "Every".lower()
     KEY_EXPIRE: Final[str] = "ExpirationTime".lower()
     KEY_ATTRIBUTES: Final[str] = "Attributes".lower()
 
@@ -33,7 +36,8 @@ class Contract(Metadata):
         "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_XOR_KEYS = "Contract expects exactly one of the keys '{}' or '{}'. Found either both or none."
+    _ERR_INTERVAL_INVALID = "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: '{}'"
@@ -73,7 +77,7 @@ class Contract(Metadata):
         if sender_id == receiver_id:
             log().warning(self._ERR_SENDER_IS_RECEIVER.format(sender_id))
         if delivery_interval <= 0:
-            raise log_error(self.ContractError(self._ERR_INTERVAL_NOT_POSITIVE.format(delivery_interval)))
+            raise log_error(self.ContractError(self._ERR_INTERVAL_INVALID.format(delivery_interval)))
         self._sender_id = sender_id
         self._receiver_id = receiver_id
         self._product_name = product_name
@@ -164,7 +168,7 @@ class Contract(Metadata):
         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)
+        delivery_interval = Contract._get_interval(definitions)
         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)
@@ -224,6 +228,43 @@ class Contract(Metadata):
             raise log_error(Contract.ContractError(Contract._ERR_MISSING_KEY.format(key)))
         return None
 
+    @staticmethod
+    def _get_interval(definitions: dict) -> int:
+        """Extract delivery interval from Contract definition, or raise an error if not present or ill formatted.
+
+        Args:
+            definitions: to extract the delivery interval from
+
+        Returns:
+            the delivery interval in fame time steps
+
+        Raises:
+            ContractError: if delivery interval is not defined or invalid, logged with level "ERROR"
+        """
+        has_interval = Contract.KEY_INTERVAL in definitions
+        has_every = Contract.KEY_EVERY in definitions
+
+        if has_interval and not has_every:
+            value = definitions[Contract.KEY_INTERVAL]
+            if isinstance(value, int):
+                return value
+            raise log_error(Contract.ContractError(Contract._ERR_INTERVAL_INVALID.format(value)))
+        if has_every and not has_interval:
+            value = definitions[Contract.KEY_EVERY]
+            if isinstance(value, int):
+                return value
+            if isinstance(value, str):
+                try:
+                    return FameTime.convert_text_to_time_span(value)
+                except ConversionError as e:
+                    raise log_error(
+                        Contract.ContractError(Contract._ERR_TIME_CONVERSION.format(Contract.KEY_EVERY, value))
+                    ) from e
+            raise log_error(Contract.ContractError(Contract._ERR_TIME_CONVERSION.format(Contract.KEY_EVERY, value)))
+        raise log_error(
+            Contract.ContractError(Contract._ERR_XOR_KEYS.format(Contract.KEY_INTERVAL, Contract.KEY_EVERY))
+        )
+
     def _init_attributes_from_dict(self, attributes: dict[str, Any]) -> None:
         """Resets Contract `attributes` from dict.
 
@@ -280,15 +321,14 @@ class Contract(Metadata):
             Contract.KEY_EXPIRE,
             Contract.KEY_METADATA,
             Contract.KEY_ATTRIBUTES,
+            Contract.KEY_EVERY,
         ]:
             if key in multi_definition:
                 base_data[key] = multi_definition[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)
-        )
+        sender_value = Contract._get_or_raise(multi_definition, Contract.KEY_SENDER, Contract._ERR_MISSING_KEY)
+        senders = Contract._unpack_list(sender_value)
+        receiver_value = Contract._get_or_raise(multi_definition, Contract.KEY_RECEIVER, Contract._ERR_MISSING_KEY)
+        receivers = Contract._unpack_list(receiver_value)
         if len(senders) > 1 and len(receivers) == 1:
             for index, sender in enumerate(senders):
                 contracts.append(Contract._copy_contract(sender, receivers[0], base_data))
@@ -302,6 +342,13 @@ class Contract(Metadata):
             raise log_error(Contract.ContractError(Contract._ERR_MULTI_CONTRACT_CORRUPT.format(senders, receivers)))
         return contracts
 
+    @staticmethod
+    def _unpack_list(obj: Any | list) -> list[Any]:
+        """Returns the given value as a flat list - unpacks potential nested list(s)"""
+        if isinstance(obj, list):
+            return [item for element in obj for item in Contract._unpack_list(element)]
+        return [obj]
+
     @staticmethod
     def _copy_contract(sender: int, receiver: int, base_data: dict) -> dict:
         """Returns a new contract definition dictionary, with given `sender` and `receiver` and copied `base_data`."""

fameio/input/scenario/exception.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds static methods to create or log exceptions."""
+
 from __future__ import annotations
 
 from typing import Any

fameio/input/scenario/fameiofactory.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds a class that helps to create scenario."""
+
 from fameio.input.schema import Schema
 from .agent import Agent
 from .contract import Contract

fameio/input/scenario/generalproperties.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds a class to describe the general properties of a simulation."""
+
 from __future__ import annotations
 
 from typing import Final

fameio/input/scenario/scenario.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds a class to describe scenarios."""
+
 from __future__ import annotations
 
 from typing import Final, Any

fameio/input/scenario/stringset.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds a class to describe StringSets."""
+
 from __future__ import annotations
 
 from typing import Final, Any, Union

fameio/input/schema/__init__.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Classes to load, represent, and save schemas and their components."""
 
 from .agenttype import AgentType  # noqa: F401
 from .attribute import AttributeSpecs, AttributeType  # noqa: F401

fameio/input/schema/agenttype.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Hold a class to describe a type of agent."""
+
 from __future__ import annotations
 
 from typing import Any, Final

fameio/input/schema/attribute.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds classes to describe an attribute of an agent."""
+
 from __future__ import annotations
 
 from enum import Enum, auto

fameio/input/schema/java_packages.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds the class to describe the names of java packages that contain the model."""
+
 from __future__ import annotations
 
 from typing import Final

fameio/input/schema/schema.py

@@ -1,19 +1,23 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Holds the basic schema class."""
+
 from __future__ import annotations
 
 import ast
+from copy import deepcopy
 from typing import Any, Final
 
 from fameio.input import SchemaError
+from fameio.input.metadata import Metadata
 from fameio.logs import log_error
 from fameio.tools import keys_to_lower
 from .agenttype import AgentType
 from .java_packages import JavaPackages
 
 
-class Schema:
+class Schema(Metadata):
     """Definition of a schema."""
 
     KEY_AGENT_TYPE: Final[str] = "AgentTypes".lower()
@@ -24,7 +28,8 @@ class Schema:
     _ERR_MISSING_PACKAGES = "Missing required section `JavaPackages` in Schema."
 
     def __init__(self, definitions: dict) -> None:
-        self._original_input_dict = definitions
+        super().__init__(definitions)
+        self._original_input_dict = deepcopy(definitions)
         self._agent_types: dict[str, AgentType] = {}
         self._packages: JavaPackages | None = None
 
@@ -80,7 +85,7 @@ class Schema:
         """Load given string `definitions` into a new Schema."""
         return cls.from_dict(ast.literal_eval(definitions))
 
-    def to_dict(self) -> dict:
+    def _to_dict(self) -> dict:
         """Serializes the schema content to a dict."""
         return self._original_input_dict
 

fameio/input/validator.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Checking scenarios for consistency with their model schema."""
+
 from __future__ import annotations
 
 import math

fameio/input/writer.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Writing simulation configuration files in protobuf format."""
+
 from __future__ import annotations
 
 import sys
@@ -88,6 +90,7 @@ class ProtoWriter:
         self._set_time_series(pb_input)
         self._set_schema(pb_input, scenario.schema)
         self._set_string_sets(pb_input, scenario.string_sets)
+        self._set_scenario_metadata(pb_input, scenario.metadata)
 
         self._set_java_package_names(pb_data_storage.model, scenario.schema.packages)
         self._set_execution_versions(pb_data_storage.execution.version_data)
@@ -146,6 +149,7 @@ class ProtoWriter:
         values_not_set = list(specs.keys())
         for name, attribute in attributes.items():
             pb_field = self._add_field(pb_parent, name)
+            self._set_field_metadata(pb_field, attribute.metadata)
             attribute_specs = specs[name]
             values_not_set.remove(name)
             attribute_type = attribute_specs.attr_type
@@ -172,6 +176,12 @@ class ProtoWriter:
         pb_field.field_name = name
         return pb_field
 
+    @staticmethod
+    def _set_field_metadata(pb_field: NestedField, attribute_metadata: dict) -> None:
+        """Sets metadata of given `pb_field`, provided that given `attribute_metadata` are not empty"""
+        if attribute_metadata:
+            pb_field.metadata = repr(attribute_metadata)
+
     def _set_attribute(self, pb_field: NestedField, value: Any, attribute_type: AttributeType) -> None:
         """Sets given `value` to given protobuf `pb_field` depending on specified `attribute_type`.
 
@@ -285,6 +295,12 @@ class ProtoWriter:
             if string_set.has_metadata():
                 pb_set.metadata = string_set.get_metadata_string()
 
+    @staticmethod
+    def _set_scenario_metadata(pb_input: InputData, scenario_metadata: dict) -> None:
+        """Adds the given metadata to the provided `pb_input.`"""
+        if scenario_metadata:
+            pb_input.metadata = repr(scenario_metadata)
+
     @staticmethod
     def _set_java_package_names(pb_model: ModelData, java_packages: JavaPackages) -> None:
         """Adds given JavaPackages names to given ModelData section."""

fameio/logs.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Handling of fameio-specific logger, log levels, and log formatting."""
 from __future__ import annotations
 
 import logging as pylog
@@ -49,7 +50,7 @@ def log_critical(exception: T) -> T:
     """Logs a critical error with the exception's message and returns the exception for raising it.
 
     Does **not** raise the exception, i.e. the command must be preceded by a `raise`.
-    Example: `raise log_critical(MyException("My error message"))
+    Example: `raise log_critical(MyException("My error message"))`
 
     Args:
         exception: to extract the error message from

fameio/output/__init__.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: CC0-1.0
+"""Classes and modules required for the transformation of protobuf files to human-readable file formats."""
 
 
 class OutputError(Exception):

fameio/output/agent_type.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Description of types of agents and their output data."""
+
 from __future__ import annotations
 
 from fameprotobuf.services_pb2 import Output
@@ -151,3 +153,15 @@ class AgentTypeLog:
     def get_agents_with_output(self) -> list[str]:
         """Returns all names of agents that had output."""
         return self._agents_with_output
+
+    def get_agent_columns(self) -> dict[str, list[str]]:
+        """Returns all agents with output mapped to their simple output columns.
+
+        Raises:
+            AgentTypeError: if - somehow - an agent type is not registered but has data, logged with level "ERROR"
+        """
+        result = {}
+        for agent in self.get_agents_with_output():
+            agent_type = self.get_agent_type(agent)
+            result[agent] = list(agent_type.get_simple_column_map().values())
+        return result

fameio/output/conversion.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Methods to convert or merge time stamps of agent timeseries output."""
+
 from __future__ import annotations
 
 import math