fameio 3.2.0__tar.gz → 3.3.0__tar.gz

{fameio-3.2.0 → fameio-3.3.0}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 SPDX-License-Identifier: CC0-1.0 -->
 
+## [3.3.0](https://gitlab.com/fame-framework/fame-io/-/tags/v3.3.0) - 2025-5-09
+### Changed
+- Expose static methods to read, convert, and write time series #245 (@dlr-cjs)
+- Improve docstrings of SchemaValidator !219 (@dlr-cjs)
+
+### Added
+- Add command-line script to reformat time series #246 (@dlr-cjs)
+- Read execution metadata from protobuf file #193 (@dlr-cjs)
+
 ## [3.2.0](https://gitlab.com/fame-framework/fame-io/-/tags/v3.2.0) - 2025-04-22
 ### Changed
 - Suppress detailed Exception traceback in console #239 (@dlr_fn, @dlr-cjs)

{fameio-3.2.0 → fameio-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fameio
-Version: 3.2.0
+Version: 3.3.0
 Summary: Tools for input preparation and output digestion of FAME models
 License: Apache-2.0
 Keywords: FAME,fameio,agent-based modelling,energy systems
@@ -47,8 +47,7 @@ SPDX-License-Identifier: Apache-2.0 -->
 *Tools for input preparation and output digestion of FAME models*
 
 FAME-Io compiles input for FAME models in protobuf format and extracts model outputs to human-readable files.
-Please visit the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/home) to get an explanation of FAME and its
-components.
+Please visit the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/home) to get an explanation of FAME and its components.
 
 # Installation
 
@@ -56,30 +55,26 @@ We recommend installing `fameio` using PyPI:
 
     pip install fameio
 
-You may also use `pipx`. For detailed information please refer to the
-official `pipx` [documentation](https://github.com/pypa/pipx).
+You may also use `pipx`. For detailed information please refer to the official `pipx` [documentation](https://github.com/pypa/pipx).
 
     pipx install fameio
 
-`fameio` is currently developed and tested for Python 3.8 or higher.
+`fameio` is currently developed and tested for Python 3.9 or higher.
 See the `pyproject.toml` for a complete listing of dependencies.
 
 # Usage
 
-FAME-Io currently offers two main scripts `makeFameRunConfig` and `convertFameResults`.
-Both are automatically installed with the package.
+FAME-Io currently offers two main scripts `makeFameRunConfig` and `convertFameResults`, plus a helper script `reformatTimeSeries`
+All are automatically installed with the package.
 The first one creates a protobuf file for FAME applications using YAML definition files and CSV files.
-The latter one reads output files from FAME applications in protobuf format and converts them to CSV files.
+The second one reads output files from FAME applications in protobuf format and converts them to CSV files.
+The third script reformats time series CSV files to FAME format.
 
-You may use the [example data](https://gitlab.com/dlr-ve/esy/amiris/examples) provided for
-the [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) model which can be used to simulate electricity markets
-in [Germany](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Germany2019), [Austria](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Austria2019),
-and a simple [proof-of-concept model](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Simple).
+You may use the [example data](https://gitlab.com/dlr-ve/esy/amiris/examples) provided for the [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) model which can be used to simulate electricity markets in [Germany](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Germany2019), [Austria](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Austria2019), and a simple [proof-of-concept model](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Simple).
 
 ## Make a FAME run configuration
 
-Digests configuration files in YAML format, combines them with CSV data files and creates a single input file for FAME
-applications in protobuf format.
+Digests configuration files in YAML format, combines them with CSV data files and creates a single input file for FAME applications in protobuf format.
 Call structure:
 
     makeFameRunConfig -f <path/to/scenario.yaml>
@@ -644,10 +639,8 @@ TIME_SERIES inputs are not directly fed into the Scenario YAML file.
 Instead, TIME_SERIES reference a CSV file that can be stored some place else.
 These CSV files follow a specific structure:
 
-* They should contain exactly two columns - any other columns are ignored.
-  A warning is raised if more than two non-empty columns are detected.
-* The first column must be a time stamp in form `YYYY-MM-DD_hh:mm:ss` or
-  a [FAME-Timestamp](https://gitlab.com/fame-framework/wiki/-/wikis/architecture/decisions/TimeStamp) integer value.
+* They should contain exactly two columns - any other columns are ignored. A warning is raised if more than two non-empty columns are detected.
+* The first column must be a time stamp in form `YYYY-MM-DD_hh:mm:ss` or a [FAME-Timestamp](https://gitlab.com/fame-framework/wiki/-/wikis/architecture/decisions/TimeStamp) integer value.
 * The second column must be a numerical value (either integer or floating-point)
 * The separator of the two columns is a semicolon
 * The data must **not** have headers, except for comments marked with `#`
@@ -663,11 +656,10 @@ Exemplary content of a valid CSV file:
     2016-01-01_00:00:00;42  # optional comment on this particular data point
     2017-01-01_00:00:00;0.1
 
-Please refer also to the detailed article about `TimeStamps` in
-the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/TimeStamp).
-For large CSV files (with more than 20,000 rows) we recommend using the integer representation of FAME-Timestamps in the
-first column (instead of text representation) to improve conversion speed.
+Please refer also to the detailed article about `TimeStamps` in the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/TimeStamp).
+For large CSV files (with more than 20,000 rows) we recommend using the integer representation of FAME-Timestamps in the first column (instead of text representation) to improve conversion speed.
 A warning will be raised for very large files (exceeding 50,000 rows) that require time stamp conversion.
+Use `reformatTimeSeries` to convert one or multiple timeseries CSV files into FAME format to improve conversion speed and avoid this warning.
 
 ### Split and join multiple YAML files
 
@@ -936,6 +928,24 @@ run_config = handle_args(my_arg_string, my_defaults)
 convert_results(run_config)
 ```
 
+## Reformat time series
+
+Takes CSV time series files and reformats them into FAME time format.
+This improves speed of run configuration creation but also reduces readability of the CSV files' content.
+Thus, we recommend to apply this reformatting only for CSV time series files with more than 20,000 lines.
+
+Call structure:
+
+    reformatTimeSeries -fp <file_or_file_pattern*.csv>
+
+You may also specify any of the following arguments:
+
+| Command                       | Action                                                                                                                                                                                 |
+|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `-l` or `--log` <option>      | Sets the logging level. Default is `WARNING`. Options are `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.                                                                             |
+| `-lf` or `--logfile` <file>   | Sets the logging file. Default is `None`. If `None` is provided, all logs get only printed to the console.                                                                             |
+| `--replace` or `--no-replace` | If `--replace` is specified, existing csv files are replaced with the new content. Otherwise and by default, new files are created extending the original file name by "_reformatted". |
+
 ## Cite FAME-Io
 
 If you use FAME-Io for academic work, please cite as follows.

{fameio-3.2.0 → fameio-3.3.0}/README.md

@@ -15,8 +15,7 @@ SPDX-License-Identifier: Apache-2.0 -->
 *Tools for input preparation and output digestion of FAME models*
 
 FAME-Io compiles input for FAME models in protobuf format and extracts model outputs to human-readable files.
-Please visit the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/home) to get an explanation of FAME and its
-components.
+Please visit the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/home) to get an explanation of FAME and its components.
 
 # Installation
 
@@ -24,30 +23,26 @@ We recommend installing `fameio` using PyPI:
 
     pip install fameio
 
-You may also use `pipx`. For detailed information please refer to the
-official `pipx` [documentation](https://github.com/pypa/pipx).
+You may also use `pipx`. For detailed information please refer to the official `pipx` [documentation](https://github.com/pypa/pipx).
 
     pipx install fameio
 
-`fameio` is currently developed and tested for Python 3.8 or higher.
+`fameio` is currently developed and tested for Python 3.9 or higher.
 See the `pyproject.toml` for a complete listing of dependencies.
 
 # Usage
 
-FAME-Io currently offers two main scripts `makeFameRunConfig` and `convertFameResults`.
-Both are automatically installed with the package.
+FAME-Io currently offers two main scripts `makeFameRunConfig` and `convertFameResults`, plus a helper script `reformatTimeSeries`
+All are automatically installed with the package.
 The first one creates a protobuf file for FAME applications using YAML definition files and CSV files.
-The latter one reads output files from FAME applications in protobuf format and converts them to CSV files.
+The second one reads output files from FAME applications in protobuf format and converts them to CSV files.
+The third script reformats time series CSV files to FAME format.
 
-You may use the [example data](https://gitlab.com/dlr-ve/esy/amiris/examples) provided for
-the [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) model which can be used to simulate electricity markets
-in [Germany](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Germany2019), [Austria](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Austria2019),
-and a simple [proof-of-concept model](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Simple).
+You may use the [example data](https://gitlab.com/dlr-ve/esy/amiris/examples) provided for the [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) model which can be used to simulate electricity markets in [Germany](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Germany2019), [Austria](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Austria2019), and a simple [proof-of-concept model](https://gitlab.com/dlr-ve/esy/amiris/examples/-/tree/main/Simple).
 
 ## Make a FAME run configuration
 
-Digests configuration files in YAML format, combines them with CSV data files and creates a single input file for FAME
-applications in protobuf format.
+Digests configuration files in YAML format, combines them with CSV data files and creates a single input file for FAME applications in protobuf format.
 Call structure:
 
     makeFameRunConfig -f <path/to/scenario.yaml>
@@ -612,10 +607,8 @@ TIME_SERIES inputs are not directly fed into the Scenario YAML file.
 Instead, TIME_SERIES reference a CSV file that can be stored some place else.
 These CSV files follow a specific structure:
 
-* They should contain exactly two columns - any other columns are ignored.
-  A warning is raised if more than two non-empty columns are detected.
-* The first column must be a time stamp in form `YYYY-MM-DD_hh:mm:ss` or
-  a [FAME-Timestamp](https://gitlab.com/fame-framework/wiki/-/wikis/architecture/decisions/TimeStamp) integer value.
+* They should contain exactly two columns - any other columns are ignored. A warning is raised if more than two non-empty columns are detected.
+* The first column must be a time stamp in form `YYYY-MM-DD_hh:mm:ss` or a [FAME-Timestamp](https://gitlab.com/fame-framework/wiki/-/wikis/architecture/decisions/TimeStamp) integer value.
 * The second column must be a numerical value (either integer or floating-point)
 * The separator of the two columns is a semicolon
 * The data must **not** have headers, except for comments marked with `#`
@@ -631,11 +624,10 @@ Exemplary content of a valid CSV file:
     2016-01-01_00:00:00;42  # optional comment on this particular data point
     2017-01-01_00:00:00;0.1
 
-Please refer also to the detailed article about `TimeStamps` in
-the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/TimeStamp).
-For large CSV files (with more than 20,000 rows) we recommend using the integer representation of FAME-Timestamps in the
-first column (instead of text representation) to improve conversion speed.
+Please refer also to the detailed article about `TimeStamps` in the [FAME-Wiki](https://gitlab.com/fame-framework/wiki/-/wikis/TimeStamp).
+For large CSV files (with more than 20,000 rows) we recommend using the integer representation of FAME-Timestamps in the first column (instead of text representation) to improve conversion speed.
 A warning will be raised for very large files (exceeding 50,000 rows) that require time stamp conversion.
+Use `reformatTimeSeries` to convert one or multiple timeseries CSV files into FAME format to improve conversion speed and avoid this warning.
 
 ### Split and join multiple YAML files
 
@@ -904,6 +896,24 @@ run_config = handle_args(my_arg_string, my_defaults)
 convert_results(run_config)
 ```
 
+## Reformat time series
+
+Takes CSV time series files and reformats them into FAME time format.
+This improves speed of run configuration creation but also reduces readability of the CSV files' content.
+Thus, we recommend to apply this reformatting only for CSV time series files with more than 20,000 lines.
+
+Call structure:
+
+    reformatTimeSeries -fp <file_or_file_pattern*.csv>
+
+You may also specify any of the following arguments:
+
+| Command                       | Action                                                                                                                                                                                 |
+|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `-l` or `--log` <option>      | Sets the logging level. Default is `WARNING`. Options are `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.                                                                             |
+| `-lf` or `--logfile` <file>   | Sets the logging file. Default is `None`. If `None` is provided, all logs get only printed to the console.                                                                             |
+| `--replace` or `--no-replace` | If `--replace` is specified, existing csv files are replaced with the new content. Otherwise and by default, new files are created extending the original file name by "_reformatted". |
+
 ## Cite FAME-Io
 
 If you use FAME-Io for academic work, please cite as follows.

{fameio-3.2.0 → fameio-3.3.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "fameio"
-version = "3.2.0"
+version = "3.3.0"
 description = "Tools for input preparation and output digestion of FAME models"
 license = "Apache-2.0"
 readme = "README.md"
@@ -39,6 +39,7 @@ repository = "https://gitlab.com/fame-framework/fame-io"
 [project.scripts]
 makeFameRunConfig = "fameio.scripts:makeFameRunConfig"
 convertFameResults = "fameio.scripts:convertFameResults"
+reformatTimeSeries = "fameio.scripts:reformatTimeSeries"
 
 [tool.poetry]
 classifiers = [

{fameio-3.2.0 → fameio-3.3.0}/src/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-3.2.0 → fameio-3.3.0}/src/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-3.2.0 → fameio-3.3.0}/src/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-3.2.0 → fameio-3.3.0}/src/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-3.3.0/src/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-3.3.0/src/fameio/input/__init__.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2024 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+class InputError(Exception):
+    """An error that occurred while preparing a fame input file."""
+
+
+class SchemaError(InputError):
+    """An error that occurred while parsing a Schema."""
+
+
+class ScenarioError(InputError):
+    """An error that occurred while parsing a Scenario."""
+
+
+class YamlLoaderError(InputError):
+    """An error that occurred while parsing a YAML file."""

{fameio-3.2.0 → fameio-3.3.0}/src/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)))