fameio 3.4.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

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

fameio/output/csv_writer.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Writing of dataframes to CSV files."""
+
 from __future__ import annotations
 
 from pathlib import Path
@@ -115,7 +117,7 @@ class CsvWriter:
 
     @staticmethod
     def _dataframe_to_csv(data: pd.DataFrame, file: Path, header: bool, index: bool, mode: str) -> None:
-        """Write given data to specified CSV file with specified parameters using semicolon separators.
+        """Write given data to specified CSV file in UTF8 encoding with specified parameters using semicolon separators.
 
         Args:
             data: to be written
@@ -128,7 +130,7 @@ class CsvWriter:
             CsvWriterError: if data could not be written to disk, logged on level "ERROR"
         """
         try:
-            data.to_csv(path_or_buf=file, sep=";", header=header, index=index, mode=mode)
+            data.to_csv(path_or_buf=file, sep=";", header=header, index=index, mode=mode, encoding="UTF-8")
         except OSError as e:
             raise log_error(CsvWriterError(CsvWriter._ERR_FILE_OPEN.format(file))) from e
         except UnicodeError as e:

fameio/output/data_transformer.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Transformation of (complex) time series outputs from agents."""
+
 from __future__ import annotations
 
 from abc import ABC

fameio/output/execution_dao.py

@@ -1,8 +1,11 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Accessing execution content of protobuf messages."""
+
 from __future__ import annotations
 
+from importlib import metadata
 from typing import Any, Final
 
 from fameprotobuf.data_storage_pb2 import DataStorage
@@ -47,6 +50,7 @@ class ExecutionDao:
 
     KEY_COMPILATION: Final[str] = "InputCompilation"
     KEY_RUN: Final[str] = "ModelRun"
+    KEY_EXTRACTION: Final[str] = "OutputExtraction"
     KEY_VERSIONS: Final[str] = "SoftwareVersions"
     KEY_PROCESSES: Final[str] = "ProcessConfiguration"
     KEY_STATISTICS: Final[str] = "Statistics"
@@ -146,6 +150,7 @@ class ExecutionDao:
                 self.KEY_PROCESSES: self._get_dict(self._run_configuration, PROCESS_MAP),
                 self.KEY_STATISTICS: self._get_dict(self._run_simulation, STATISTICS_MAP),
             },
+            self.KEY_EXTRACTION: {self.KEY_VERSIONS: {"FameIo": metadata.version("fameio")}},
         }
         return result
 

fameio/output/input_dao.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Accessing input content of protobuf messages."""
+
 import ast
 from typing import Any
 
@@ -61,7 +63,7 @@ class InputDao:
             InputConversionError: if inputs could not be recovered, logged with level "ERROR"
             InputError: if scenario in file is incompatible with this version of fameio, logged with level "ERROR"
         """
-        input_data = self._get_input_data()
+        input_data = self.get_input_data()
         schema = self._get_schema(input_data)
         scenario = Scenario(schema, self._get_general_properties(input_data))
         for contract in self._get_contracts(input_data):
@@ -73,8 +75,8 @@ class InputDao:
 
         return self._timeseries_manager, scenario
 
-    def _get_input_data(self) -> InputData:
-        """Check that exactly one previously extracted input data exist, otherwise raises an exception.
+    def get_input_data(self) -> InputData:
+        """Check that exactly one previously extracted input data exist and returns them; otherwise raises an exception.
 
         Returns:
             the previously extracted input data

fameio/output/metadata/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: CC0-1.0
+"""Classes and modules to compile metadata associated with output files."""
+
+from fameio.output import OutputError
+
+
+class MetadataCompilationError(OutputError):
+    """An error occurred while compiling output metadata."""