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

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 (
@@ -24,8 +26,8 @@ CLI_DEFAULTS = {
     Options.FILE: None,
     Options.LOG_LEVEL: "WARN",
     Options.LOG_FILE: None,
-    Options.AGENT_LIST: None,
     Options.OUTPUT: None,
+    Options.AGENT_LIST: None,
     Options.SINGLE_AGENT_EXPORT: False,
     Options.MEMORY_SAVING: False,
     Options.RESOLVE_COMPLEX_FIELD: ResolveOptions.SPLIT,
@@ -38,9 +40,8 @@ _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 `run_config` for convert_results script
+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.
 
     Args:
         args: list of (command line) arguments, e.g., ['-f', 'my_file']; arg values take precedence over defaults
@@ -54,9 +55,8 @@ 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:
-    """
-    Creates a parser with given defaults to handle `make_config` configuration arguments
+def _prepare_parser(defaults: dict[Options, Any] | None) -> 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
@@ -80,5 +80,5 @@ def _prepare_parser(defaults: Optional[dict[Options, Any]]) -> argparse.Argument
 
 
 def _get_default(defaults: dict, option: Options) -> Any:
-    """Returns default for given `option` or its cli default"""
+    """Returns default for given `option` or its cli default."""
     return defaults.get(option, CLI_DEFAULTS[option])

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,9 +33,8 @@ _ENCODING_HELP = (
 )
 
 
-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
+def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) -> dict[Options, Any]:
+    """Converts given `args` 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
@@ -47,9 +48,8 @@ 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:
-    """
-    Creates a parser with given defaults to handle `make_config` configuration arguments
+def _prepare_parser(defaults: dict[Options, Any] | None) -> 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
@@ -65,5 +65,5 @@ def _prepare_parser(defaults: Optional[dict[Options, Any]]) -> argparse.Argument
 
 
 def _get_default(defaults: dict, option: Options) -> Any:
-    """Returns default for given `option` or, if missing, its cli default"""
+    """Returns default for given `option` or, if missing, its cli default."""
     return defaults.get(option, CLI_DEFAULTS[option])

fameio/cli/options.py

@@ -6,7 +6,7 @@ from enum import Enum, auto
 
 
 class ParsableEnum(Enum):
-    """Extend this to create an enum that can be parsed with argparse"""
+    """Extend this to create an enum that can be parsed with argparse."""
 
     @classmethod
     def instantiate(cls, name: str) -> Enum:
@@ -20,7 +20,7 @@ class ParsableEnum(Enum):
 
 
 class Options(Enum):
-    """Specifies command line configuration options"""
+    """Specifies command line configuration options."""
 
     FILE = auto()
     LOG_LEVEL = auto()
@@ -34,10 +34,12 @@ class Options(Enum):
     TIME_MERGING = auto()
     INPUT_RECOVERY = auto()
     INPUT_ENCODING = auto()
+    FILE_PATTERN = auto()
+    REPLACE = auto()
 
 
 class TimeOptions(ParsableEnum, Enum):
-    """Specifies options for conversion of time in output"""
+    """Specifies options for conversion of time in output."""
 
     INT = auto()
     UTC = auto()
@@ -45,7 +47,7 @@ class TimeOptions(ParsableEnum, Enum):
 
 
 class ResolveOptions(ParsableEnum, Enum):
-    """Specifies options for resolving complex fields in output files"""
+    """Specifies options for resolving complex fields in output files."""
 
     IGNORE = auto()
     SPLIT = auto()

fameio/cli/parser.py

@@ -1,18 +1,19 @@
 # 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,
@@ -25,13 +26,15 @@ _OPTION_ARGUMENT_NAME: dict[str, Union[Options, dict]] = {
     "input_recovery": Options.INPUT_RECOVERY,
     "complex_column": Options.RESOLVE_COMPLEX_FIELD,
     "merge_times": Options.TIME_MERGING,
+    "file_pattern": Options.FILE_PATTERN,
+    "replace": Options.REPLACE,
 }
 
 
-def add_file_argument(parser: ArgumentParser, default: Optional[Path], 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)
+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).
 
     Args:
         parser: to add the argument to
@@ -44,26 +47,26 @@ 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:
-    """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)
+def add_select_agents_argument(parser: ArgumentParser, default_value: list[str] | None) -> None:
+    """Adds optional repeatable string argument 'agent' to given `parser`."""
+    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:
-    """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)
+def add_logfile_argument(parser: ArgumentParser, default_value: Path | None) -> None:
+    """Adds optional argument 'logfile' to given `parser`."""
+    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:
-    """Adds optional argument 'output' to given `parser` using the given `help_text` and `default_value`"""
+    """Adds optional argument 'output' to given `parser` using the given `help_text` and `default_value`."""
     parser.add_argument("-o", "--output", type=Path, default=default_value, help=help_text)
 
 
 def add_log_level_argument(parser: ArgumentParser, default_value: str) -> None:
-    """Adds optional argument 'log' to given `parser`"""
-    help_text = f"choose logging level (default: {default_value})"
+    """Adds optional argument 'log' to given `parser`."""
+    help_text = f"choose logging level (default={default_value})"
     # noinspection PyTypeChecker
     parser.add_argument(
         "-l",
@@ -75,14 +78,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)"
+    """Adds optional repeatable string argument 'agent' to given `parser`."""
+    help_text = f"Enable export of single agents (default={default_value})"
     parser.add_argument(
         "-se",
         "--single-export",
@@ -93,8 +96,8 @@ 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)"
+    """Adds optional bool argument to given `parser` to enable memory saving mode."""
+    help_text = f"Reduces memory usage profile at the cost of runtime (default={default_value})"
     parser.add_argument(
         "-m",
         "--memory-saving",
@@ -104,10 +107,10 @@ def add_memory_saving_argument(parser: ArgumentParser, default_value: bool) -> N
     )
 
 
-def add_resolve_complex_argument(parser: ArgumentParser, default_value: Union[ResolveOptions, str]):
-    """Instructs given `parser` how to deal with complex field outputs"""
+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 +121,10 @@ def add_resolve_complex_argument(parser: ArgumentParser, default_value: Union[Re
     )
 
 
-def add_time_argument(parser: ArgumentParser, default_value: Union[TimeOptions, str]) -> None:
-    """Adds optional argument to given `parser` to define conversion of TimeSteps"""
+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,8 +135,8 @@ def add_time_argument(parser: ArgumentParser, default_value: Union[TimeOptions,
     )
 
 
-def add_merge_time_argument(parser: ArgumentParser, defaults: Optional[list[int]] = None) -> None:
-    """Adds optional three-fold argument for merging of TimeSteps to given `parser`"""
+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 (
@@ -150,29 +153,61 @@ 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:
-    """Adds optional bool argument to given `parser` to recover inputs"""
-    help_text = "If --(no-)input-recovery is specified, (no) inputs will be recovered"
-    parser.add_argument(
-        "--input-recovery",
-        action=BooleanOptionalAction,
-        default=default,
-        help=help_text,
-    )
+def add_inputs_recovery_argument(parser: ArgumentParser, default_value: bool) -> None:
+    """Adds optional bool argument to given `parser` to recover inputs."""
+    description = "(no) inputs will be recovered"
+    _add_optional_boolean_argument(parser, default_value, "input-recovery", description)
+
+
+def _add_optional_boolean_argument(parser: ArgumentParser, default: bool, arg_name: str, description: str) -> None:
+    """Adds optional boolean argument to parser.
+
+    Argument named `arg_name` is added to given `parser` overwriting the provided default.
+    Help from argument `description` is added as help text.
+
+    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
+        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
+    help_text = f"If --(no-){arg_name} is specified, {description} (default={default_str})"
+    parser.add_argument(f"--{arg_name}", action=BooleanOptionalAction, default=default, 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 add_file_pattern_argument(parser: ArgumentParser, default_value: str | None) -> None:
+    """Adds argument to given `parser` to specify a file pattern; if no default provided, the argument is mandatory."""
+    help_text = f"Path to csv file(s) that are to be converted (default='{default_value}')"
+    required = not bool(default_value)
+    parser.add_argument("--file-pattern", "-fp", required=required, type=str, default=default_value, help=help_text)
+
+
+def add_replace_argument(parser: ArgumentParser, default_value: bool) -> None:
+    """Adds optional bool argument to given `parser` to replace converted files."""
+    description = "original files will (not) be replaced"
+    _add_optional_boolean_argument(parser, default_value, "replace", description)
+
+
+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
 
 
 def map_namespace_to_options_dict(parsed: Namespace) -> dict[Options, Any]:
-    """
-    Maps given parsing results to their corresponding configuration option
+    """Maps given parsing results to their corresponding configuration option.
 
     Args:
         parsed: result of a parsing
@@ -183,10 +218,11 @@ 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]:
-    """
-    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.
+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 will be also read and added as inner dictionary.
 
     Args:
         parsed: result of a parsing

fameio/cli/reformat.py

@@ -0,0 +1,58 @@
+# 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
+
+from fameio.cli.options import Options
+from fameio.cli.parser import (
+    map_namespace_to_options_dict,
+    add_logfile_argument,
+    add_log_level_argument,
+    add_file_pattern_argument,
+    add_replace_argument,
+)
+
+CLI_DEFAULTS = {
+    Options.LOG_LEVEL: "WARN",
+    Options.LOG_FILE: None,
+    Options.FILE_PATTERN: None,
+    Options.REPLACE: False,
+}
+
+
+def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) -> dict[Options, Any]:
+    """Converts given `args` and returns a configuration for the transform script.
+
+    Args:
+        args: list of (command line) arguments, e.g., ['-fp', '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 given `args`
+    """
+    parser = _prepare_parser(defaults)
+    parsed = parser.parse_args(args)
+    return map_namespace_to_options_dict(parsed)
+
+
+def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentParser:
+    """Creates a parser with given defaults to handle `reformat` 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_log_level_argument(parser, _get_default(defaults, Options.LOG_LEVEL))
+    add_logfile_argument(parser, _get_default(defaults, Options.LOG_FILE))
+    add_file_pattern_argument(parser, _get_default(defaults, Options.FILE_PATTERN))
+    add_replace_argument(parser, _get_default(defaults, Options.REPLACE))
+    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/input/__init__.py

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

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,9 +31,8 @@ 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:
-    """
-    Loads the YAML file from given and returns its content as a dict
+def load_yaml(yaml_file_path: Path, path_resolver: PathResolver = PathResolver(), encoding: str | None = None) -> dict:
+    """Loads the YAML file from given `yaml_file_path` and returns its content as a dict.
 
     Args:
         yaml_file_path: Path to the YAML file that is to be read
@@ -42,27 +43,26 @@ 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:
-    """Updates the current LoaderController to use the given `path_resolver` and `encoding`"""
+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)
 
 
 def validate_yaml_file_suffix(yaml_file: Path) -> None:
-    """
-    Ensures that given file has a file suffix compatible with YAML
+    """Ensures that given file has a file suffix compatible with YAML.
 
     Args:
         yaml_file: that is to be checked for suffix correctness
 
     Raises:
-          YamlLoaderError: if given file has no YAML-associated file suffix
+          YamlLoaderError: if given file has no YAML-associated file suffix, logged with level "CRITICAL"
     """
     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)))