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

fameio/cli/convert_results.py

@@ -26,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,
@@ -41,8 +41,7 @@ _OUTFILE_PATH_HELP = "Provide path to folder to store output .csv files"
 
 
 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
+    """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
@@ -57,8 +56,7 @@ def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) ->
 
 
 def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentParser:
-    """
-    Creates a parser with given defaults to handle `make_config` configuration arguments
+    """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
@@ -82,5 +80,5 @@ def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentPar
 
 
 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

@@ -34,8 +34,7 @@ _ENCODING_HELP = (
 
 
 def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) -> dict[Options, Any]:
-    """
-    Converts given `arguments` and returns a configuration for the make_config script
+    """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
@@ -50,8 +49,7 @@ def handle_args(args: list[str], defaults: dict[Options, Any] | None = None) ->
 
 
 def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentParser:
-    """
-    Creates a parser with given defaults to handle `make_config` configuration arguments
+    """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
@@ -67,5 +65,5 @@ def _prepare_parser(defaults: dict[Options, Any] | None) -> argparse.ArgumentPar
 
 
 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

@@ -26,13 +26,15 @@ _OPTION_ARGUMENT_NAME: dict[str, Options] = {
     "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: 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)
+    """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
@@ -46,24 +48,24 @@ def add_file_argument(parser: ArgumentParser, default: Path | None, help_text: s
 
 
 def add_select_agents_argument(parser: ArgumentParser, default_value: list[str] | None) -> None:
-    """Adds optional repeatable string argument 'agent' to given `parser`"""
+    """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_value: Path | None) -> None:
-    """Adds optional argument 'logfile' to given `parser`"""
+    """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`"""
+    """Adds optional argument 'log' to given `parser`."""
     help_text = f"choose logging level (default={default_value})"
     # noinspection PyTypeChecker
     parser.add_argument(
@@ -82,7 +84,7 @@ def add_encoding_argument(parser: ArgumentParser, default_value: str | None, hel
 
 
 def add_single_export_argument(parser: ArgumentParser, default_value: bool) -> None:
-    """Adds optional repeatable string argument 'agent' to given `parser`"""
+    """Adds optional repeatable string argument 'agent' to given `parser`."""
     help_text = f"Enable export of single agents (default={default_value})"
     parser.add_argument(
         "-se",
@@ -94,7 +96,7 @@ def add_single_export_argument(parser: ArgumentParser, default_value: bool) -> N
 
 
 def add_memory_saving_argument(parser: ArgumentParser, default_value: bool) -> None:
-    """Adds optional bool argument to given `parser` to enable memory saving mode"""
+    """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",
@@ -106,7 +108,7 @@ def add_memory_saving_argument(parser: ArgumentParser, default_value: bool) -> N
 
 
 def add_resolve_complex_argument(parser: ArgumentParser, default_value: ResolveOptions | str):
-    """Instructs given `parser` how to deal with complex field outputs"""
+    """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.name})"
     parser.add_argument(
@@ -120,7 +122,7 @@ def add_resolve_complex_argument(parser: ArgumentParser, default_value: ResolveO
 
 
 def add_time_argument(parser: ArgumentParser, default_value: TimeOptions | str) -> None:
-    """Adds optional argument to given `parser` to define conversion of TimeSteps"""
+    """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 = f"Apply conversion of time steps to given format (default={default_value.name})"
     parser.add_argument(
@@ -134,7 +136,7 @@ def add_time_argument(parser: ArgumentParser, default_value: TimeOptions | str)
 
 
 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`"""
+    """Adds optional three-fold argument for merging of TimeSteps to given `parser`."""
     if defaults is None:
         defaults = []
     if (
@@ -152,21 +154,43 @@ def add_merge_time_argument(parser: ArgumentParser, defaults: list[int] | None =
 
 
 def add_inputs_recovery_argument(parser: ArgumentParser, default_value: bool) -> None:
-    """Adds optional bool argument to given `parser` to recover inputs"""
-    arg_name = "input-recovery"
-    default_str = "--" + ("no-" if not default_value else "") + arg_name
-    help_text = f"If --(no-)input-recovery is specified, (no) inputs will be recovered (default={default_str})"
-    parser.add_argument(
-        f"--{arg_name}",
-        action=BooleanOptionalAction,
-        default=default_value,
-        help=help_text,
-    )
+    """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 update_default_config(overrides: dict[Options, Any] | None, defaults: dict[Options, Any]) -> dict[Options, Any]:
+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)'
     """
-    Returns `defaults` with updated fields received from `overrides`
+    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 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`
@@ -183,8 +207,7 @@ def update_default_config(overrides: dict[Options, Any] | None, defaults: dict[O
 
 
 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
@@ -196,9 +219,10 @@ def map_namespace_to_options_dict(parsed: Namespace) -> dict[Options, Any]:
 
 
 def _map_namespace_to_options(parsed: Namespace, names_to_options: dict[str, Options]) -> dict[Options, Any]:
-    """
-    Maps given parsing results to their corresponding configuration option; elements that cannot be mapped are ignored.
-    If a configuration option has inner elements, these well be also read and added as inner dictionary.
+    """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 preparing a fame input file"""
+    """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

@@ -32,8 +32,7 @@ FameYamlLoader.add_constructor(FameYamlLoader.INCLUDE_COMMAND, _include_callback
 
 
 def load_yaml(yaml_file_path: Path, path_resolver: PathResolver = PathResolver(), encoding: str | None = None) -> dict:
-    """
-    Loads the YAML file from given and returns its content as a dict
+    """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
@@ -52,19 +51,18 @@ def load_yaml(yaml_file_path: Path, path_resolver: PathResolver = PathResolver()
 
 
 def _update_current_controller(path_resolver: PathResolver, encoding: str | None) -> None:
-    """Updates the current LoaderController to use the given `path_resolver` and `encoding`"""
+    """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:
         raise log_critical(YamlLoaderError(_ERR_NO_YAML_SUFFIX.format(ALLOWED_SUFFIXES, yaml_file)))

fameio/input/loader/controller.py

@@ -16,9 +16,9 @@ from fameio.logs import log, log_critical
 
 
 class LoaderController:
-    """
-    Controls loading of YAML files by spawning one FameYamlLoader per file.
-    Uses same PathResolver and encoding for all files
+    """Controls loading of YAML files by spawning one FameYamlLoader per file.
+
+    Uses same PathResolver and encoding for all files.
     """
 
     DISABLING_YAML_FILE_PREFIX: Final[str] = "IGNORE_"
@@ -40,8 +40,7 @@ class LoaderController:
         self._encoding: str | None = encoding
 
     def load(self, yaml_file_path: Path) -> dict:
-        """
-        Spawns a new FameYamlLoader, loads the given `yaml_file_path` and returns its content
+        """Spawns a new FameYamlLoader, loads the given `yaml_file_path` and returns its content.
 
         Args:
             yaml_file_path: path to YAML file that is to be loaded
@@ -65,13 +64,12 @@ class LoaderController:
 
     @staticmethod
     def _spawn_loader_builder() -> Callable[[IO], FameYamlLoader]:
-        """Returns a new Callable that instantiates a new FameYamlLoader with an IO-stream"""
+        """Returns a new Callable that instantiates a new FameYamlLoader with an IO-stream."""
         return lambda stream: FameYamlLoader(stream)  # pylint: disable=unnecessary-lambda
 
     @staticmethod
     def _get_problem_position(exception: yaml.YAMLError) -> tuple[str, str]:
-        """
-        Returns problematic line and column from given error (if available)
+        """Returns problematic line and column from given error (if available).
 
         Args:
             exception: error thrown by yaml.load()
@@ -85,8 +83,7 @@ class LoaderController:
         return "?", "?"
 
     def include(self, loader: FameYamlLoader, include_args: yaml.Node) -> Any:
-        """
-        Returns content loaded from the specified `include_args`
+        """Returns content loaded from the specified `include_args`.
 
         Args:
             loader: the YAML loader to be used to load the file(s) that are to be included
@@ -113,8 +110,8 @@ class LoaderController:
         return joined_data
 
     def _resolve_imported_path(self, root_path: str, include_pattern: str) -> list[str]:
-        """
-        Returns a list of file paths matching the given `include_pattern` relative to the `root_path`.
+        """Returns a list of file paths matching the given `include_pattern` relative to the `root_path`.
+
         Ignores files starting with the `DISABLING_YAML_FILE_PREFIX`
         """
         file_list = self._path_resolver.resolve_file_pattern(root_path, include_pattern)
@@ -133,8 +130,7 @@ class LoaderController:
 
     @staticmethod
     def _extract_node(file_name: str, data: dict, node_address: list[str]) -> Any:
-        """
-        Returns only the part of the data that is at the specified node address
+        """Returns only the part of the data that is at the specified node address.
 
         Args:
             file_name: name of the file from which the data were read - used to enrich logging messages
@@ -158,8 +154,7 @@ class LoaderController:
 
     @staticmethod
     def _join_data(new_data: list, previous_data: list | None) -> list:
-        """
-        Joins two lists with data to a larger list
+        """Joins two lists with data to a larger list.
 
         Args:
             new_data: list of any data

fameio/input/loader/loader.py

@@ -11,7 +11,7 @@ from fameio.logs import log, log_critical
 
 
 class FameYamlLoader(yaml.SafeLoader):
-    """Custom YAML Loader for `!include` constructor"""
+    """Custom YAML Loader for `!include` constructor."""
 
     INCLUDE_COMMAND: Final[str] = "!include"
 
@@ -29,8 +29,7 @@ class FameYamlLoader(yaml.SafeLoader):
         super().__init__(stream)
 
     def digest_include(self, node: yaml.Node) -> tuple[str, str, str]:
-        """
-        Reads arguments in an !include statement and returns information which files to include
+        """Reads arguments in an !include statement and returns information which files to include.
 
         Args:
             node: the current node that is to be deconstructed; could be a file-pattern to load;
@@ -58,8 +57,9 @@ class FameYamlLoader(yaml.SafeLoader):
         return self._root_path, file_pattern, node_string
 
     def _read_scalar_node(self, args: yaml.nodes.ScalarNode) -> tuple[str, str]:
-        """
-        Reads and returns content of a scalar !include statement; Example: !include "file"
+        """Reads and returns content of a scalar !include statement.
+
+        Example: !include "file".
 
         Args:
             args: argument assigned to the !include statement
@@ -72,8 +72,9 @@ class FameYamlLoader(yaml.SafeLoader):
         return str(file_pattern), ""
 
     def _read_sequence_node(self, args: yaml.nodes.SequenceNode) -> tuple[str, str]:
-        """
-        Reads and returns content of a sequence !include statement; Example: !include ["file", Path:to:Node]
+        """Reads and returns content of a sequence !include statement.
+
+        Example: !include ["file", Path:to:Node].
 
         Args:
             args: argument assigned to the !include statement
@@ -94,8 +95,9 @@ class FameYamlLoader(yaml.SafeLoader):
         return file_pattern, node_string
 
     def _read_mapping_node(self, args: yaml.nodes.MappingNode) -> tuple[str, str]:
-        """
-        Reads and returns content of a mapping !include statement; Example: !include {file="file", node="Path:to:Node"}
+        """Reads and returns content of a mapping !include statement.
+
+        Example: !include {file="file", node="Path:to:Node"}
 
         Args:
             args: argument assigned to the !include statement