cmeta.utils.cli module

Reusable functions for CLI

cMeta author and developer: (C) 2025-2026 Grigori Fursin

See the cMeta COPYRIGHT and LICENSE files in the project root for details.

Functions

cmeta.utils.cli.check_params(params, params_description, fail_on_error=False) → Dict[str, Any]

Check and validate input dictionary based on input description. Convert aliases to keys and validate types.

Parameters:

• params – Input dictionary to validate

• params_description – List of configuration dictionaries with keys, types, etc.

Returns:

• return: 0 for success, >0 for error

• checked_params: Dictionary with validated and converted values for the group

• remaining_params: Dictionary with remaining keys not in the group

• error: Error message (only present if return > 0)

Return type:

Dictionary with

cmeta.utils.cli.parse_cmd(cmd, fail_on_error: bool = False)

Parse command line string or argument list into a structured dictionary.

Supports various argument formats:

• Positional arguments: stored in ‘positional_arguments’ list

• Flags: –key=value, -key=value, key=value

• Boolean flags: –key (True), –key- (False), –no-key (False)

• List flags: –key, (creates list)

• Nested keys: –parent.child=value

• File inclusion: @filename (loads JSON/YAML) Note: On Windows, wrap file paths in double quotes if they contain backslashes () to prevent shlex.split() from interpreting them as escape characters.

• Argument separator: – (remaining args go to ‘unparsed’)

Parameters:

• cmd – Command string to parse, list of arguments, or None.

• fail_on_error (bool) – If True, raise exception on error.

Returns:

Dictionary with keys: - ‘return’: 0 for success, >0 for error - ‘params’: Dictionary of parsed flags and values (may include “args” and “unparsed”) - ‘error’: Error message (only present if return > 0).

Return type:

dict

cmeta.utils.cli.print_params_help(params_description: list)

Generate formatted help text for command-line parameters.

Creates a formatted string displaying parameter flags, types, and descriptions with proper column alignment.

Parameters:

params_description (list) – List of parameter dictionaries containing ‘key’, ‘type’, ‘desc’, ‘aliases’, etc.

Returns:

Dictionary with ‘return’: 0 and ‘params_info’ containing formatted help text.

Return type:

dict

cmeta.utils.cli.split_flag(*args, **params)

Wrapper for _split_flag that handles exceptions.

Parameters:

• *args – Positional arguments passed to _split_flag.

• **params – Keyword arguments passed to _split_flag.

Returns:

Dictionary with ‘return’: 0 and ‘split_flag’ tuple, or ‘return’ > 0 and ‘error’.

Return type:

dict