cmeta.utils.sys module

Common reusable functions

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.sys.find_command_func(category_api, command: str)[source]

Find command function in category API object.

Searches for the command function using standard naming conventions: command_, command__, or command (in that order).

Parameters:

  • category_api – Category API object instance.

  • command (str) – Command name string to search for.

Returns:

Dictionary with ‘return’: 0, ‘func’ (function object or None),

and ‘func_name’ (actual function name if found).

Return type:

dict

cmeta.utils.sys.find_func_definition(obj, name: str)[source]

Find function definition in an object by name.

Locates a function by name in an object’s class, unwraps decorators, and extracts its source code properties.

Parameters:

  • obj – Object instance to search for the function.

  • name (str) – Name of the function to find.

Returns:

Dictionary with ‘return’: 0 and function properties on success,

or ‘return’: 1 and ‘error’ if function not found.

Return type:

dict

cmeta.utils.sys.flush_input()[source]

Flush stdin buffer on Unix/Linux/Mac and Windows.

Clears any pending keyboard input from the stdin buffer.

cmeta.utils.sys.format_size(size: int, binary: bool = True, unit: str | None = None)[source]

Convert size in bytes to a human-readable string.

Parameters:

  • size (int) – Size in bytes to format.

  • binary (bool) – If True, use 1024 base with IEC units (KiB, MiB, GiB). If False, use 1000 base with SI units (KB, MB, GB).

  • unit (str | None) – Force specific unit (e.g., ‘MB’, ‘MiB’). If None, auto-select.

Returns:

Dictionary with ‘return’: 0 and ‘nice_size’ containing formatted string.

Return type:

dict

Raises:

ValueError – If unit is not valid.

cmeta.utils.sys.get_api_info(category_api, command: str, full_command: str, control_params_desc=None, category_apis: list = [])[source]

Extract function definition and docstring for API information.

Parameters:

  • category_api – The category API object.

  • command (str) – The command name.

  • full_command (str) – Full command string.

  • control_params_desc – Control parameters description.

  • category_apis (list) – List of category APIs.

Returns:

Dictionary with ‘return’: 0 and ‘api_info’ string for success,

or ‘return’ > 0 and ‘error’ for errors.

Return type:

dict

cmeta.utils.sys.get_api_text(lines: list, start_line: int)[source]

Extract API text from function source lines.

Parses function definition and docstring from source code lines.

Parameters:

  • lines (list) – List of source code lines.

  • start_line (int) – Starting line number.

Returns:

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

Return type:

dict

cmeta.utils.sys.get_dir_size(path: str, binary: bool = False, unit: str | None = None)[source]

Calculate total size of a directory recursively.

Walks through directory tree and sums file sizes.

Parameters:

  • path (str) – Directory path to measure.

  • binary (bool) – If True, use binary (1024) units, else decimal (1000).

  • unit (str | None) – Force specific unit for size formatting.

Returns:

Dictionary with ‘return’: 0, ‘size’ in bytes, ‘nice_size’ formatted,

’total_dirs’ count, ‘total_files’ count, ‘latest_modification_dt’, and ‘weird_dates’ list of files with future modification dates.

Return type:

dict

cmeta.utils.sys.get_disk_space(path: str, nice: bool = False, binary: bool = False, unit: str | None = None, line: int = 0, self_time: bool = False)[source]

Get disk space information for a given path.

Retrieves total, used, and free disk space for the filesystem containing the specified path.

Parameters:

  • path (str) – Path to check disk space for.

  • nice (bool) – If True, return human-readable sizes with ‘nice_*’ keys.

  • binary (bool) – If True, use binary (1024) units, else decimal (1000).

  • unit (str | None) – Force specific unit for size formatting (e.g., ‘GB’, ‘GiB’).

Returns:

Dictionary with ‘return’: 0 and:

’total’ (int): Total disk space in bytes. ‘used’ (int): Used disk space in bytes. ‘free’ (int): Free disk space in bytes. ‘self_time’ (float): Execution time in seconds. ‘nice_self_time’ (str): Formatted execution time. If nice=True, also includes: ‘nice_total’ (str): Formatted total size. ‘nice_used’ (str): Formatted used size. ‘nice_free’ (str): Formatted free size.

Return type:

dict

cmeta.utils.sys.get_func_properties(f)[source]

Extract source code properties from a function object.

Gets the source file path, line numbers, and API documentation text for a given function.

Parameters:

f – Function object to inspect.

Returns:

Dictionary with ‘return’: 0 and properties including ‘filename’,

’start_line’, ‘end_line’, and ‘api_text’.

Return type:

dict

cmeta.utils.sys.get_min_host_info(only_memory: bool = False, binary: bool = False, unit: str = 'GB', con: bool = False, line: int = 0, self_time: bool = False)[source]

Get minimal host system information including CPU and memory.

Retrieves system information including CPU core counts, total memory, free memory, and current process memory usage.

Parameters:

  • only_memory (bool) – If True, only return memory information.

  • binary (bool) – If True, use binary (1024) units for memory sizes.

  • unit (str) – Unit for memory size formatting (default: ‘GB’).

  • con (bool) – If True, print information to console.

Returns:

Dictionary with ‘return’: 0 and host information including:

’physical_cores’ (int): Number of physical CPU cores. ‘logical_cores’ (int): Number of logical CPU cores. ‘total_memory’ (int): Total system memory in bytes. ‘nice_total_memory’ (str): Formatted total memory string. ‘free_memory’ (int): Free system memory in bytes. ‘nice_free_memory’ (str): Formatted free memory string. ‘memory_used’ (int): Memory used by current process in bytes. ‘nice_memory_used’ (str): Formatted process memory string. ‘self_time’ (float): Execution time in seconds. ‘nice_self_time’ (str): Formatted execution time. ‘string’ (str): Formatted output for display.

Return type:

dict

cmeta.utils.sys.load_module(module_path: str, module_cache: dict, fail_on_error: bool = False, category: bool = False, cmeta=None, suffix: str | None = None)[source]

Dynamically load a Python module from file path with caching support.

Loads category API modules and manages them in a cache. Handles module naming sanitization and creates proper package structures for category modules.

Parameters:

  • module_path (str) – Absolute path to the Python module file.

  • module_cache (dict) – Dictionary to store cached module information.

  • fail_on_error (bool) – If True, raises exception on error instead of returning error dict.

  • category (bool) – If True, initializes the Category class from the module.

  • cmeta – CMeta instance to pass to Category initialization.

  • suffix (str | None) – Optional suffix for module name sanitization.

Returns:

Dictionary with ‘return’: 0 and ‘cache’ containing module info,

or ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

cmeta.utils.sys.run(cmd: str, work_dir: str | None = None, env: dict | None = None, envs: dict | None = None, genv: dict | None = None, capture_output: bool = False, text_cmd: str = '$', timeout: int | None = None, verbose: bool = False, hide_in_cmd: list | None = None, save_script: str = '', run_script: bool = False, script_prefix: str = '', skip_run: bool = False, print_cmd: bool = False, con: bool = False, fail_on_error: bool = False, logger=None)[source]

Run CMD with environment.

Parameters:

  • cmd (str) – Command to execute.

  • work_dir (str | None) – Working directory.

  • env (dict | None) – 2nd (current) env to update global ENV.

  • envs (dict | None) – 1st level of env to update global ENV.

  • genv (dict | None) – Global ENV (force in the end).

  • capture_output (bool) – False by default.

  • text_cmd (str) – Text prefix for command display.

  • timeout (int | None) – None by default. TBD: Current timeout doesn’t terminate subprocesses.

  • verbose (bool) – If True, print extra info.

  • hide_in_cmd (list | None) – List of keys in CMD to hide (for secrets).

  • save_script (str) – Save script for reproducibility.

  • run_script (bool) – Run created script (useful for pipes).

  • script_prefix (str) – Add prefix string to script.

  • skip_run (bool) – If True, skip run.

  • print_cmd (bool) – If True, force print CMD.

  • con (bool) – If True, enable console output.

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

  • logger – Optional logger for debug messages.

Returns:

Unified output with ‘return’, ‘returncode’, ‘stdout’, ‘stderr’.

Return type:

dict

cmeta.utils.sys.run_command_with_timeout_tree_kill_on_windows(cmd: str, capture_output: bool, cur_env: dict, timeout: float, shell: bool = True, text: bool = True)[source]

Run command on Windows with timeout and process tree termination.

Uses Windows Job Objects to ensure entire process tree is killed on timeout.

Parameters:

  • cmd (str) – Command string to execute.

  • capture_output (bool) – If True, capture stdout and stderr.

  • cur_env (dict) – Environment variables dictionary.

  • timeout (float) – Timeout in seconds.

  • shell (bool) – If True, run command through shell.

  • text (bool) – If True, decode output as text.

Returns:

(returncode, stdout, stderr).

Return type:

tuple

Raises:

OSError – If Windows API calls fail.