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.

• fail_on_error – If True, raise exceptions instead of returning error dictionaries.

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

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.cli.cli_types_enabled()

Whether the words of the command line are read by annotations and descriptions (the default) or stay text as before cMeta 0.37: CMETA_CLI_TYPES=off (0, no, false) turns the reading off for a process.

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 the ‘args’ list; a negative number (-5, -1.5) is one too

• Flags: –key=value, -key=value, key=value (a bare key=value only when the part before “=” looks like a key - KEY_LIKE: free text with “=”, such as “echo a=b” or a URL with a query, stays positional)

• 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

Raises:

Exception – Propagated runtime errors, if any.

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

Raises:

Exception – Propagated runtime errors, if any.

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

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.cli.typed_params_from_cli(func, params, described=None, where='', fail_on_error=False)

Read the words of the command line by what the function expects: the strings of params for the parameters func annotates bool become booleans; the strings for the parameters described names (name -> ‘bool’ | ‘int’ | ‘float’ | ‘str’, or name -> {‘type’, ‘values’, ‘min’, ‘max’}) become the described type and are checked against the allowed values and the range. Any other parameter, and any value that is not a string, is left as it is. A string that is not of the type is an error.

Returns:

{‘return’: 0, ‘converted’: {name: value}} or {‘return’: 1, ‘error’: …}.

Return type:

dict

Constants

cmeta.utils.cli.BOOL_WORDS = {'0': False, '1': True, 'false': False, 'no': False, 'off': False, 'on': True, 'true': True, 'yes': True}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

cmeta.utils.cli.CLI_PARAMS_META_KEY = 'cli_params'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

cmeta.utils.cli.CLI_TYPES = {'bool': <class 'bool'>, 'float': <class 'float'>, 'int': <class 'int'>, 'str': <class 'str'>}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

cmeta.utils.cli.CLI_TYPES_ENV = 'CMETA_CLI_TYPES'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

cmeta.utils.cli.CLI_TYPES_META_KEY = 'cli_types'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.