fameio 1.8.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

CHANGELOG.md

@@ -0,0 +1,204 @@
+<!-- SPDX-FileCopyrightText: 2023 German Aerospace Center <fame@dlr.de>
+
+SPDX-License-Identifier: CC0-1.0 -->
+
+# Changelog
+
+## [2.0.0 - 2024-04-03](https://gitlab.com/fame-framework/fame-io/-/tags/v2.0.0)
+### Changed
+- **Breaking**: Removed support for `python==3.8` #163 (@dlr-cjs @dlr_fn)
+- **Breaking**: Signature of `run` functions in `make_config.py` and `convert_results.py` changed: the input file is now read from the configuration dictionary #163 (@dlr-cjs @dlr_fn)
+- **Breaking**: Created protobuf files now have a header section -> minimum required FAME-Core version is now 1.6.0 #183 (@dlr-cjs @dlr_fn)
+- Raise error for NaN float values in scenario and time series #165 (@dlr-cjs @dlr_fn)
+- Enhance Schema to include metadata and output fields #156 (@dlr-cjs @litotes18 @dlr_fn)
+- Enhance Contracts to include metadata #158 (@dlr-cjs @litotes18 @dlr_fn)
+- Enhance Agents to include metadata #159 (@dlr-cjs @litotes18 @dlr_fn)
+- Improve general handling of CLI arguments #163 (@dlr_fn @dlr-cjs)
+- Ensure `fameio` logger is used consistently !126 (@dlr-cjs @dlr_fn)
+- Enhanced error message if mandatory attribute is not defined by logging `full_name` #177 (@dlr_fn)
+- Switch to pyproject.toml #173 (@dlr-cjs)
+- Restrict supported pandas versions #171 (@dlr-cjs)
+- Enable to specify defaults for MERGE_TIME parameters #179 (@dlr-cjs)
+- Conserve order of keys in YAML files #186 (@dlr-cjs @dlr_fn)
+- Update to `fameprotobuf==1.4.0` #189 (@dlr-cjs @dlr_fn)
+- Update `CHANGELOG.md` to conform with Common Changelog format #172 (@dlr-cjs @dlr_fn)
+
+### Added
+- Write Schema and Metadata of Contracts and Agents to protobuf file #160 (@dlr-cjs @litotes18 @dlr_fn)
+- Add option to recover input data `--input-recovery`/`--no-input-recovery` #163 (@litotes18 @dlr_fn @dlr-cjs)
+- Add pipeline tests for all major Python versions >= 3.8 #173 (@dlr-cjs)
+- Read all input from protobuf file #162 (@dlr-cjs @litotes18 @dlr_fn)
+- Write all input from protobuf to disk #163 (@litotes18 @dlr_fn @dlr-cjs)
+- Add header section to input protobuf enabling recovering of inputs from protobuf #183 (@dlr-cjs @dlr_fn)
+- Add pipeline tests for all major Python versions >= 3.8, < 3.12 #173 (@dlr-cjs)
+- Enable comments in timeseries using '#' #184 (@dlr-cjs)
+- Raise Warning if Agent has no Contracts attributed #187 (@dlr_fn)
+- Add JOSS Paper in folder paper/ #139 (@dlr-cjs @litotes18 @dlr_fn)
+- Add `CONTRIBUTING.md` #102 (@dlr-cjs @dlr_fn)
+- Add `Citation.cff` #166 (@dlr-cjs)
+
+### Removed
+- Remove deprecated protobuf test !127 (@dlr-cjs @dlr_fn)
+
+### Fixed
+- Fix deprecated arguments in pandas groupby !129 (@maurerle)
+- Fix breaking tests in Pytest 8.0 #176 (@dlr-cjs)
+- Fix PyTests for Python 3.12 #182 (@dlr_fn)
+
+## [1.8.1 - 2023-05-04](https://gitlab.com/fame-framework/fame-io/-/tags/v1.8.1)
+### Fixed
+- Fix fail of `ConvertFameResults` when `merge-times` was not specified
+
+## [1.8.0 - 2023-04-14](https://gitlab.com/fame-framework/fame-io/-/tags/v1.8)
+### Changed
+- Update repository to be compliant to `REUSE` standard
+- Accept custom `date_format` (default: `"%Y-%m-%d_%H:%M:%S"`) for `FameTime.convert_fame_time_step_to_datetime()`
+- Parse command-line arguments case-insensitive for arguments with predefined options
+- Handle potentially missing cli arguments in `cli.update_default_config` for `makeFameRunConfig` and `convertFameResults` in a robust way.
+
+### Added
+- **Breaking**: Add option to define conversion of time steps to given format (default=`UTC`) by `-t/--time {UTC, INT, FAME}` for `convertFameResults`
+- Add option to merge time steps in results with `convertFameResults`
+- Add pre-commit hooks enforcing high coding standards and reducing CI runner minutes during development
+
+## [1.7.0 - 2023-02-20](https://gitlab.com/fame-framework/fame-io/-/tags/v1.7)
+### Added
+- Support dictionaries in Schema for field `Products` in elements of `AgentTypes`
+- Support dictionaries in Schema for field `Values` in elements of `Attributes`
+
+### Changed
+- Use `Pathlib` for path handling
+- Improve error message when no valid `YAML` file is specified for `makeFameRunConfig`
+
+### Remove
+- **Breaking**: `Products` in Schema no longer support single non-list values
+
+## [1.6.3 - 2022-11-04](https://gitlab.com/fame-framework/fame-io/-/tags/v1.6.3)
+### Added
+- Allow parsing `Help` for `Attributes` in `schema`
+
+## [1.6.1 - 2022-11-02](https://gitlab.com/fame-framework/fame-io/-/tags/v1.6.1)
+### Changed
+- Use existing logger if already set up to avoid duplicates when `fameio` is used as dependency in third party workflows
+
+## [1.6.0 - 2022-07-08](https://gitlab.com/fame-framework/fame-io/-/tags/v1.6)
+### Added
+- Add option to enable memory saving mode using the flag `-m` or `--memory-saving`
+- Add options to deal with complex indexed output columns using the flag `-cc` or `--complex-column` with
+  options `IGNORE`, `MERGE` or `SPLIT`
+
+### Changed
+- **Breaking**: Update requirement to `python>=3.8`
+- **Breaking**: Update requirement to `fameprotobuf==v1.2`
+- Enable parsing of protobuf output files > 2 GB
+- Reduce memory profile for `convertFameResults`
+- Extract `source` scripts relevant for `convertFameResults` to be hosted in subpackage `results`
+
+## [1.5.4 - 2022-06-01](https://gitlab.com/fame-framework/fame-io/-/tags/v1.5.4)
+### Changed
+- Limit `protobuf` dependency to `>=3.19,<4.0`
+
+## [1.5.3 - 2022-03-18](https://gitlab.com/fame-framework/fame-io/-/tags/v1.5.3)
+### Changed
+- Harmonize interface with `famegui`
+- Return `None` on failure of `resolve_series_file_path` instead of raising a `FileNotFoundError`
+
+## [1.5.2 - 2022-03-10](https://gitlab.com/fame-framework/fame-io/-/tags/v1.5.2)
+### Changed
+- Allow interfacing of `famegui` with `scenario` (e.g. serialization, error handling)
+- Move `scenario` validation to `validator.py`
+- Extract `path_resolver.py`
+- Increase test coverage by incorporating [AMIRIS examples](https://gitlab.com/dlr-ve/esy/amiris/examples)
+
+## [1.5.1 - 2022-01-10](https://gitlab.com/fame-framework/fame-io/-/tags/v1.5.1)
+### Added
+- Provide documentation on installation using `pipx`
+- Add optional argument `-se`/`--singleexport` for exporting individual files for each agent
+- Add compatibility hook for `famegui` integration
+
+### Changed
+- Refactor `scenario.py`
+- Ensure code formatting using `black`
+
+## [1.5.0 - 2021-06-30](https://gitlab.com/fame-framework/fame-io/-/tags/v1.5)
+### Added
+- Support specifying an output folder in command line interface of `convert_results.py`
+
+### Changed
+- Update to latest protobuf package
+- Refactor code
+
+## [1.4.0 - 2021-06-10](https://gitlab.com/fame-framework/fame-io/-/tags/v1.4)
+### Added
+- Enable "Default" values for Attributes - these are used in case a mandatory attribute is not specified in the Scenario
+- Allow "List" Attributes with multiple values
+- Add new AttributeTypes "Long", "String" and "TimeStamp"
+- Add compact definition of multiple contracts: enable lists for senders and receivers
+
+### Changed
+- **Breaking**: Update requirement to `fameprotobuf==1.1.4`
+- Refactor `make_config.py`: split into several classes and packages, improved exception handling
+- Switch to pytest and improved test coverage
+- Make keywords in Schema and Scenario case-insensitive
+- Improve validations for Schema and Scenario
+
+### Fixed
+- Fixed minor bugs
+
+## [1.3.0 - 2021-04-13](https://gitlab.com/fame-framework/fame-io/-/tags/v1.3)
+### Added
+- Enable `Attributes` in agents (formerly known as `Fields`) to be structured in complex tree-like data dictionaries
+- Allow contracts to support `Attributes` of type `int`, `float`, `enum` or `dict`
+- Add coverage report badge
+- Add `CHANGELOG.md`
+
+### Changed
+- **Breaking**: Use new format `DataStorage` for input and output protobuf files allowing `FAME-Core` input and output to be written to the same file (requires `FAME-Core > 1.0`)
+- **Breaking**: Update requirement to `fameprotobuf==1.1.2`
+- Enable automatic detection of `TimeStamps` by string format and conversion to int64
+- Raise proper error when file can not be loaded triggered by `!include` command
+- Raise critical error when trying to convert empty protobuf output file
+- Check if `product` in `contract` is valid according to `schema.yaml`
+
+## [1.2.4 - 2021-02-26](https://gitlab.com/fame-framework/fame-io/-/tags/v1.2.4)
+### Changed
+- Move `is_compatible` function to class `AttributeType`
+
+## [1.2.3 - 2021-02-24](https://gitlab.com/fame-framework/fame-io/-/tags/v1.2.3)
+### Fixed
+- Fix file prefix `IGNORE_` (used when loading a set of contract files with the !include argument) is now working consistently
+
+## [1.2.2 - 2021-02-18](https://gitlab.com/fame-framework/fame-io/-/tags/v1.2.2)
+### Changed
+- **Breaking**: Rename `fieldtype` to `attributetype` in `schema.yaml`
+- Derive protobuf imports from `fameprotobuf` package
+- Improve handling of cases for keys in `scenario.yaml`
+- Improve handling of time stamp strings
+
+## [1.2.1 - 2021-02-10](https://gitlab.com/fame-framework/fame-io/-/tags/v1.2.1)
+### Changed
+- Improve key handling for contracts which are now case-insensitive
+
+## [1.2.0 - 2021-02-04](https://gitlab.com/fame-framework/fame-io/-/tags/v1.2)
+### Added
+- Add `!include` command to yaml loading to allow integrating additional yaml files
+
+### Changed
+- **Breaking**: Rename package to `fameio`
+- Improve executables
+- Restructure logging
+- Improve documentation
+
+### Fixed
+- Fix bugs
+
+## [1.1.0 - 2020-12-09](https://gitlab.com/fame-framework/fame-io/-/tags/v1.1)
+### Added
+- Package to PyPI
+- Provide executables for calling `makeFameRunConfig` and `convertFameResults`
+
+### Changed
+- Improve documentation
+
+## [1.0.0 - 2020-11-17](https://gitlab.com/fame-framework/fame-io/-/tags/v1.0)
+_Initial release of `famepy`_

fameio/scripts/__init__.py

@@ -3,16 +3,18 @@ import sys
 
 from fameio.scripts.convert_results import DEFAULT_CONFIG as DEFAULT_CONVERT_CONFIG
 from fameio.scripts.convert_results import run as convert_results
-from fameio.scripts.make_config import DEFAULT_CONFIG as DEFAULT_MAKE_CONFIG
 from fameio.scripts.make_config import run as make_config
-from fameio.source.cli import arg_handling_convert_results, arg_handling_make_config
+from fameio.source.cli.convert_results import handle_args as handle_convert_results_args
+from fameio.source.cli.make_config import handle_args as handle_make_config_args
 
 
+# noinspection PyPep8Naming
 def makeFameRunConfig():
-    input_file, run_config = arg_handling_make_config(sys.argv[1:], DEFAULT_MAKE_CONFIG)
-    make_config(input_file, run_config)
+    run_config = handle_make_config_args(sys.argv[1:])
+    make_config(run_config)
 
 
+# noinspection PyPep8Naming
 def convertFameResults():
-    input_file, run_config = arg_handling_convert_results(sys.argv[1:], DEFAULT_CONVERT_CONFIG)
-    convert_results(input_file, run_config)
+    run_config = handle_convert_results_args(sys.argv[1:], DEFAULT_CONVERT_CONFIG)
+    convert_results(run_config)

fameio/scripts/__init__.py.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+
+SPDX-License-Identifier: Apache-2.0

fameio/scripts/convert_results.py

@@ -1,75 +1,71 @@
 #!/usr/bin/env python
 
-import logging as log
 import sys
 from pathlib import Path
-from typing import Union
 
-from fameio.source.cli import (
-    Options,
-    ResolveOptions,
-    arg_handling_convert_results,
-    update_default_config,
-    TimeOptions,
-)
-from fameio.source.logs import log_and_raise_critical, set_up_logger
+from fameio.source.cli.convert_results import handle_args, CLI_DEFAULTS as DEFAULT_CONFIG
+from fameio.source.cli.options import Options
+from fameio.source.cli.parser import update_default_config
+from fameio.source.logs import log_and_raise_critical, set_up_logger, logger
 from fameio.source.results.agent_type import AgentTypeLog
 from fameio.source.results.conversion import apply_time_option, apply_time_merging
 from fameio.source.results.csv_writer import CsvWriter
 from fameio.source.results.data_transformer import DataTransformer
+from fameio.source.results.input_dao import InputDao
 from fameio.source.results.output_dao import OutputDAO
 from fameio.source.results.reader import Reader
-
-DEFAULT_CONFIG = {
-    Options.LOG_LEVEL: "info",
-    Options.LOG_FILE: None,
-    Options.AGENT_LIST: None,
-    Options.OUTPUT: None,
-    Options.SINGLE_AGENT_EXPORT: False,
-    Options.MEMORY_SAVING: False,
-    Options.RESOLVE_COMPLEX_FIELD: ResolveOptions.SPLIT.name,
-    Options.TIME: TimeOptions.UTC.name,
-    Options.TIME_MERGING: {},
-}
+from fameio.source.results.yaml_writer import data_to_yaml_file
 
 ERR_MEMORY_ERROR = "Out of memory. Try using `-m` or `--memory-saving` option."
 ERR_MEMORY_SEVERE = "Out of memory despite memory-saving mode. Reduce output interval in `FAME-Core` and rerun model"
 
 
-def run(file_path: Union[str, Path], config: dict = None) -> None:
-    """Reads file in protobuf format at given `file_path` and extracts its content to .csv file(s)"""
+def run(config: dict = None) -> None:
+    """Reads file in protobuf format for configures FILE and extracts its content to .csv file(s)"""
     config = update_default_config(config, DEFAULT_CONFIG)
     set_up_logger(level_name=config[Options.LOG_LEVEL], file_name=config[Options.LOG_FILE])
 
-    writer = CsvWriter(config[Options.OUTPUT], Path(file_path), config[Options.SINGLE_AGENT_EXPORT])
+    file_path = config[Options.FILE]
+    output_writer = CsvWriter(config[Options.OUTPUT], Path(file_path), config[Options.SINGLE_AGENT_EXPORT])
     file_stream = open(Path(file_path), "rb")
 
     if config[Options.MEMORY_SAVING]:
-        log.info("Memory saving mode enabled: Disable on conversion of small files for performance improvements.")
+        logger().info("Memory saving mode enabled: Disable on conversion of small files for performance improvements.")
 
-    log.info("Reading and extracting data...")
+    logger().info("Reading and extracting data...")
     reader = Reader.get_reader(file=file_stream, read_single=config[Options.MEMORY_SAVING])
     agent_type_log = AgentTypeLog(requested_agents=config[Options.AGENT_LIST])
     data_transformer = DataTransformer.build(config[Options.RESOLVE_COMPLEX_FIELD])
     try:
+        input_dao = InputDao()
         while data_storages := reader.read():
+            if config[Options.INPUT_RECOVERY]:
+                input_dao.store_inputs(data_storages)
             output = OutputDAO(data_storages, agent_type_log)
             for agent_name in output.get_sorted_agents_to_extract():
-                log.debug(f"Extracting data for {agent_name}...")
+                logger().debug(f"Extracting data for {agent_name}...")
                 data_frames = output.get_agent_data(agent_name, data_transformer)
                 apply_time_merging(data_frames, config[Options.TIME_MERGING])
                 apply_time_option(data_frames, config[Options.TIME])
-                log.debug(f"Writing data for {agent_name}...")
-                writer.write_to_files(agent_name, data_frames)
-        log.info("Data conversion completed.")
+                logger().debug(f"Writing data for {agent_name}...")
+                output_writer.write_to_files(agent_name, data_frames)
+
+        if config[Options.INPUT_RECOVERY]:
+            logger().info("Recovering inputs...")
+            timeseries, scenario = input_dao.recover_inputs()
+            series_writer = CsvWriter(Path(config[Options.OUTPUT], "./recovered"), Path("./"), False)
+            series_writer.write_time_series_to_disk(timeseries)
+            data_to_yaml_file(scenario.to_dict(), Path(config[Options.OUTPUT], "./recovered/scenario.yaml"))
+
+        logger().info("Data conversion completed.")
     except MemoryError:
         log_and_raise_critical(ERR_MEMORY_SEVERE if Options.MEMORY_SAVING else ERR_MEMORY_ERROR)
 
     file_stream.close()
     if not agent_type_log.has_any_agent_type():
-        log.error("Provided file did not contain any output data.")
+        logger().error("Provided file did not contain any output data.")
 
 
 if __name__ == "__main__":
-    input_file, run_config = arg_handling_convert_results(sys.argv[1:], DEFAULT_CONFIG)
-    run(input_file, run_config)
+    run_config = handle_args(sys.argv[1:])
+    run(run_config)

fameio/scripts/convert_results.py.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+
+SPDX-License-Identifier: Apache-2.0

fameio/scripts/make_config.py

@@ -1,37 +1,34 @@
 #!/usr/bin/env python
-import logging as log
 import sys
 from pathlib import Path
-from typing import Union
 
-from fameio.source.cli import Options, arg_handling_make_config, update_default_config
+from fameio.source.cli.make_config import handle_args, CLI_DEFAULTS as DEFAULT_CONFIG
+from fameio.source.cli.options import Options
+from fameio.source.cli.parser import update_default_config
 from fameio.source.loader import load_yaml, check_for_yaml_file_type
-from fameio.source.logs import set_up_logger
+from fameio.source.logs import set_up_logger, logger
 from fameio.source.scenario import Scenario
 from fameio.source.validator import SchemaValidator
 from fameio.source.writer import ProtoWriter
 
-DEFAULT_CONFIG = {
-    Options.LOG_LEVEL: "info",
-    Options.LOG_FILE: None,
-    Options.OUTPUT: Path("config.pb"),
-}
 
-
-def run(file: Union[str, Path], config: dict = None) -> None:
+def run(config: dict = None) -> None:
     """Executes the main workflow for the building of a FAME configuration file"""
     config = update_default_config(config, DEFAULT_CONFIG)
     set_up_logger(level_name=config[Options.LOG_LEVEL], file_name=config[Options.LOG_FILE])
 
+    file = config[Options.FILE]
     check_for_yaml_file_type(Path(file))
     scenario = Scenario.from_dict(load_yaml(Path(file)))
-    SchemaValidator.ensure_is_valid_scenario(scenario)
-    writer = ProtoWriter(config[Options.OUTPUT])
+    SchemaValidator.check_agents_have_contracts(scenario)
+
+    timeseries_manager = SchemaValidator.validate_scenario_and_timeseries(scenario)
+    writer = ProtoWriter(config[Options.OUTPUT], timeseries_manager)
     writer.write_validated_scenario(scenario)
 
-    log.info("Configuration completed.")
+    logger().info("Configuration completed.")
 
 
 if __name__ == "__main__":
-    input_file, run_config = arg_handling_make_config(sys.argv[1:], DEFAULT_CONFIG)
-    run(input_file, run_config)
+    run_config = handle_args(sys.argv[1:])
+    run(run_config)

fameio/scripts/make_config.py.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+
+SPDX-License-Identifier: Apache-2.0

fameio/source/cli/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0

fameio/source/cli/convert_results.py

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+import argparse
+from typing import List, Dict, Any, Optional
+
+from fameio.source.cli.options import Options, ResolveOptions, TimeOptions
+from fameio.source.cli.parser import (
+    add_file_argument,
+    add_log_level_argument,
+    add_logfile_argument,
+    add_output_argument,
+    add_select_agents_argument,
+    add_single_export_argument,
+    add_memory_saving_argument,
+    add_resolve_complex_argument,
+    add_time_argument,
+    add_merge_time_parser,
+    add_inputs_recovery_argument,
+    map_namespace_to_options_dict,
+)
+
+CLI_DEFAULTS = {
+    Options.FILE: None,
+    Options.LOG_LEVEL: "info",
+    Options.LOG_FILE: None,
+    Options.AGENT_LIST: None,
+    Options.OUTPUT: None,
+    Options.SINGLE_AGENT_EXPORT: False,
+    Options.MEMORY_SAVING: False,
+    Options.RESOLVE_COMPLEX_FIELD: ResolveOptions.SPLIT,
+    Options.TIME: TimeOptions.UTC,
+    Options.TIME_MERGING: {},
+    Options.INPUT_RECOVERY: False,
+}
+
+_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]:
+    """Handles command line arguments and returns `input_file` and `run_config` for convert_results script"""
+    parser = _prepare_parser(defaults)
+    parsed = parser.parse_args(args)
+    return map_namespace_to_options_dict(parsed)
+
+
+def _prepare_parser(defaults: Optional[Dict[Options, Any]]) -> argparse.ArgumentParser:
+    """
+    Creates a parser with given defaults to handle `make_config` configuration arguments
+
+    Returns:
+        new parser using given defaults for its arguments; if a default is not specified, hard-coded defaults are used
+    """
+    defaults = defaults if (defaults is not None) else {}
+    parser = argparse.ArgumentParser()
+
+    add_file_argument(parser, _get_default(defaults, Options.FILE), _INFILE_PATH_HELP)
+    add_log_level_argument(parser, _get_default(defaults, Options.LOG_LEVEL))
+    add_logfile_argument(parser, _get_default(defaults, Options.LOG_FILE))
+    add_output_argument(parser, _get_default(defaults, Options.OUTPUT), _OUTFILE_PATH_HELP)
+    add_select_agents_argument(parser, _get_default(defaults, Options.AGENT_LIST))
+    add_single_export_argument(parser, _get_default(defaults, Options.SINGLE_AGENT_EXPORT))
+    add_memory_saving_argument(parser, _get_default(defaults, Options.MEMORY_SAVING))
+    add_resolve_complex_argument(parser, _get_default(defaults, Options.RESOLVE_COMPLEX_FIELD))
+    add_time_argument(parser, _get_default(defaults, Options.TIME))
+    add_merge_time_parser(parser)
+    add_inputs_recovery_argument(parser, _get_default(defaults, Options.INPUT_RECOVERY))
+
+    return parser
+
+
+def _get_default(defaults: dict, option: Options) -> Any:
+    """Returns default for given `option` or its cli default"""
+    return defaults.get(option, CLI_DEFAULTS[option])

fameio/source/cli/make_config.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+import argparse
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+from fameio.source.cli.options import Options
+from fameio.source.cli.parser import (
+    add_file_argument,
+    add_log_level_argument,
+    add_logfile_argument,
+    add_output_argument,
+    map_namespace_to_options_dict,
+)
+
+CLI_DEFAULTS = {
+    Options.FILE: None,
+    Options.LOG_LEVEL: "info",
+    Options.LOG_FILE: None,
+    Options.OUTPUT: Path("config.pb"),
+}
+
+_INFILE_PATH_HELP = "provide path to configuration file"
+_OUTFILE_PATH_HELP = "provide file-path for the file to generate"
+
+
+def handle_args(args: List[str], defaults: Optional[Dict[Options, Any]] = None) -> Dict[Options, Any]:
+    """
+    Converts given `arguments` and returns a configuration for the make_config script
+
+    Args:
+        args: list of (command line) arguments, e.g., ['-f', 'my_file']; arg values take precedence over defaults
+        defaults: optional default values used for unspecified parameters; missing defaults are replaced by CLI defaults
+
+    Returns:
+        final configuration compiled from (given) defaults and
+    """
+    parser = _prepare_parser(defaults)
+    parsed = parser.parse_args(args)
+    return map_namespace_to_options_dict(parsed)
+
+
+def _prepare_parser(defaults: Optional[Dict[Options, Any]]) -> argparse.ArgumentParser:
+    """
+    Creates a parser with given defaults to handle `make_config` configuration arguments
+
+    Returns:
+        new parser using given defaults for its arguments; if a default is not specified, hard-coded defaults are used
+    """
+    defaults = defaults if (defaults is not None) else {}
+    parser = argparse.ArgumentParser()
+    add_file_argument(parser, _get_default(defaults, Options.FILE), _INFILE_PATH_HELP)
+    add_log_level_argument(parser, _get_default(defaults, Options.LOG_LEVEL))
+    add_logfile_argument(parser, _get_default(defaults, Options.LOG_FILE))
+    add_output_argument(parser, _get_default(defaults, Options.OUTPUT), _OUTFILE_PATH_HELP)
+    return parser
+
+
+def _get_default(defaults: dict, option: Options) -> Any:
+    """Returns default for given `option` or, if missing, its cli default"""
+    return defaults.get(option, CLI_DEFAULTS[option])

fameio/source/cli/options.py

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+import argparse
+from enum import Enum, auto
+
+
+class ParsableEnum(Enum):
+    """Extend this to create an enum that can be parsed with argparse"""
+
+    @classmethod
+    def instantiate(cls, name: str) -> Enum:
+        try:
+            return cls[name]
+        except KeyError:
+            raise argparse.ArgumentTypeError(f"'{name}' is not a valid option")
+
+    def __str__(self):
+        return self.name
+
+
+class Options(Enum):
+    """Specifies command line configuration options"""
+
+    FILE = auto()
+    LOG_LEVEL = auto()
+    LOG_FILE = auto()
+    OUTPUT = auto()
+    AGENT_LIST = auto()
+    SINGLE_AGENT_EXPORT = auto()
+    MEMORY_SAVING = auto()
+    RESOLVE_COMPLEX_FIELD = auto()
+    TIME = auto()
+    TIME_MERGING = auto()
+    INPUT_RECOVERY = auto()
+
+
+class TimeOptions(ParsableEnum, Enum):
+    """Specifies options for conversion of time in output"""
+
+    INT = auto()
+    UTC = auto()
+    FAME = auto()
+
+
+class ResolveOptions(ParsableEnum, Enum):
+    """Specifies options for resolving complex fields in output files"""
+
+    IGNORE = auto()
+    SPLIT = auto()
+    MERGE = auto()
+
+
+class MergingOptions(Enum):
+    """Specifies options for merging TimeSteps"""
+
+    FOCAL_POINT = auto()
+    STEPS_BEFORE = auto()
+    STEPS_AFTER = auto()