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)

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

Raises:

Exception – Propagated runtime errors, if any.

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

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

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.flush_input()

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

Clears any pending keyboard input from the stdin buffer.

Parameters:

None.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

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

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 = [])

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

Raises:

Exception – Propagated runtime errors, if any.

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

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

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.get_dir_size(path: str, binary: bool = False, unit: str = None, skip_datetime: bool = False)

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.

• skip_datetime (bool) – If True, skip datetime conversion fields in the result.

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

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.get_disk_space(path: str, nice: bool = False, binary: bool = False, unit: str = None, line: int = 0, self_time: bool = False, space='')

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’).

• line (int) – Prefix line index used for structured console output.

• self_time (bool) – If True, include self-timing information in console output.

• space – Optional indentation prefix for console output formatting.

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

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.get_func_properties(f)

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

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.get_min_arch_host_info()

Collect lightweight OS and architecture metadata.

Parameters:

None.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

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, space='')

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.

• line (int) – Prefix line index used for structured console output.

• self_time (bool) – If True, include self-timing information in console output.

• space – Optional indentation prefix for console output formatting.

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

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.get_min_raw_host_info()

Collect minimal host hardware information including CPU and memory.

Parameters:

None.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.load_module(module_path: str, module_cache: dict, fail_on_error: bool = False, init_class: str = None, cmeta=None, suffix: str = None, self_meta: dict = None)

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.

• init_class (str) – Class name to instantiate from the loaded module, if provided.

• self_meta (dict) – Optional metadata dictionary to attach to the initialized object.

Returns:

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

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

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.plus_env(env)

If key starts with + and value is not list, convert to list as path

Parameters:

env – Environment variable mapping.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

cmeta.utils.sys.run(cmd: str, work_dir: str = None, env: dict = None, envs: dict = None, genv: dict = None, os_env: dict = environ({'ADVISOR_2025_DIR': 'D:\\Program Files (x86)\\Intel\\oneAPI\\advisor\\2025.5', 'ALLUSERSPROFILE': 'C:\\ProgramData', 'AL_OMNIVERSE_CONNECTOR_PATH': 'C:\\Program Files\\AnyLogic 8.9 Personal Learning Edition\\omniverse-connector\\AnyLogicOmniverseConnector.exe', 'APPDATA': 'C:\\Users\\grigo\\AppData\\Roaming', 'CHOCOLATEYINSTALL': 'C:\\ProgramData\\chocolatey', 'CHOCOLATEYLASTPATHUPDATE': '133917805810214276', 'CLASSPATH': 'D:\\!FGG\\Progs\\!fu', 'CMETA_AUTHORS': 'Grigori Fursin', 'CMETA_COPYRIGHT': 'Copyright (C) 2026 Grigori Fursin. All rights reserved.', 'CMETA_HOME2': 'D:\\!FGG_Repos', 'CMETA_INTERNAL_REPO_PATH': 'D:\\!FGG_Repos\\fgg\\fgg.project\\cMeta\\cmeta\\cmeta\\internal-repo', 'CMETA_TOOL_EXTRA_PATHS': 'C:\\!Progs\\**', 'CMETA_VERBOSE': 'true', 'CMX_HOME': 'D:\\Work1\\CM', 'CM_AUTOMATION_CK_CMD': 'Far {PATH}', 'CM_AUTOMATION_CK_EXTRA_TAGS': 'grigori,fursin,cknowledge,ctuning', 'CM_AUTOMATION_CK_REPO': 'fgg', 'CM_AUTOMATION_WORK_CMD': 'Far {PATH}', 'CM_AUTOMATION_WORK_EXTRA_TAGS': 'grigori,fursin,cknowledge,ctuning', 'CM_AUTOMATION_WORK_REPO': 'fgg', 'CM_REPOS': 'D:\\Work1\\CM', 'CM_SET_VENV_SHELL': 'Far "CM_SET_VENV_WORK"', 'COMMONPROGRAMFILES': 'C:\\Program Files\\Common Files', 'COMMONPROGRAMFILES(X86)': 'C:\\Program Files (x86)\\Common Files', 'COMMONPROGRAMW6432': 'C:\\Program Files\\Common Files', 'COMPUTERNAME': 'FGG-LENOVO-P14S', 'COMSPEC': 'C:\\WINDOWS\\system32\\cmd.exe', 'CSERVER_CM_PRINT_HOST_INFO': 'yes', 'CUDA_PATH': 'C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.2', 'CUDA_PATH_V13_2': 'C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.2', 'DOKANLIBRARY1': 'C:\\Program Files\\Dokan\\Dokan Library-1.5.1\\', 'DOKANLIBRARY1_LIBRARYPATH_X64': 'C:\\Program Files\\Dokan\\Dokan Library-1.5.1\\lib\\', 'DOKANLIBRARY1_LIBRARYPATH_X86': 'C:\\Program Files\\Dokan\\Dokan Library-1.5.1\\x86\\lib\\', 'DRIVERDATA': 'C:\\Windows\\System32\\Drivers\\DriverData', 'EFC_14632_1262719628': '1', 'EFC_14632_1592913036': '1', 'EFC_14632_2283032206': '1', 'EFC_14632_2775293581': '1', 'EFC_14632_3789132940': '1', 'FARHOME': 'C:\\Program Files\\Far Manager', 'FARLANG': 'English', 'FARLOCALPROFILE': 'C:\\Users\\grigo\\AppData\\Local\\Far Manager\\Profile', 'FARPROFILE': 'C:\\Users\\grigo\\AppData\\Roaming\\Far Manager\\Profile', 'FPS_BROWSER_APP_PROFILE_STRING': 'Internet Explorer', 'FPS_BROWSER_USER_PROFILE_STRING': 'Default', 'GIT_SSH_COMMAND': 'ssh.exe', 'GOPATH': 'C:\\Users\\grigo\\go', 'HOMEDRIVE': 'C:', 'HOMEPATH': '\\Users\\grigo', 'IGCCSVC_DB': 'AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAglO2eHcZU0a1H/CJjerikAQAAAACAAAAAAAQZgAAAAEAACAAAACetjSOFOZXdSxqkfUN9gb1BxI93OtdYlQsr65TfJkJiAAAAAAOgAAAAAIAACAAAAAR3OgqpFHHyk5PhIeuJwfcKS8QQbNJSMg4EaRm56AvLGAAAAAPlQiecXmGfeDOFLgaAyBCfLci0kqjK8YsjW0RcRT5CaJgukXNmYlZsWk3OskYIbBhMZJtYB2m8Cs++9dN1mSeF9xWj25ds0qjKRPQM21j/ZWfqbmqj3jIo0x5DiRLqedAAAAAjw73ubtYSDtiv2ezEeq1Bwwr0GzmeafUpOnQ/h+akvQxdMK2/jCmqlRK6ub7xX1fmv6hpRYLHzlPOu8zrdiG0Q==', 'LOCALAPPDATA': 'C:\\Users\\grigo\\AppData\\Local', 'LOGONSERVER': '\\\\FGG-LENOVO-P14S', 'NUMBER_OF_PROCESSORS': '16', 'OCULUSBASE': 'C:\\Program Files\\Oculus\\', 'ONEDRIVE': 'C:\\Users\\grigo\\OneDrive - cTuning foundation', 'OS': 'Windows_NT', 'PATH': 'D:\\!FGG_Repos\\fgg\\fgg.project\\cMeta\\cmeta\\.venv\\Scripts;C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.2\\bin\\x64;C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.2\\bin;C:\\Program Files\\GitHub CLI\\;C:\\!Progs\\Python3.14.0\\Scripts;C:\\!Progs\\Python3.14.0\\;D:\\!FGG\\Progs\\!fu;D:\\!FGG\\Progs\\!Misc;C:\\Program Files\\Oculus\\Support\\oculus-runtime;C:\\Program Files\\WinRar;C:\\!Progs\\jdk-21.0.7+6-windows-build\\bin;C:\\!Progs\\MiKTeX\\miktex\\bin\\x64\\;C:\\Program Files\\Graphviz\\bin;C:\\Program Files\\dotnet\\;C:\\WINDOWS\\system32;C:\\WINDOWS;C:\\WINDOWS\\System32\\Wbem;C:\\WINDOWS\\System32\\WindowsPowerShell\\v1.0\\;C:\\WINDOWS\\System32\\OpenSSH\\;C:\\Program Files (x86)\\HP\\HP OCR\\DB_Lib\\;C:\\Program Files\\HP\\Common\\HPDestPlgIn\\;C:\\Program Files (x86)\\HP\\Common\\HPDestPlgIn\\;C:\\ProgramData\\chocolatey\\bin;C:\\Program Files\\RedHat\\Podman\\;C:\\Program Files (x86)\\Incredibuild;C:\\Program Files\\TortoiseGit\\bin;C:\\Program Files\\Tailscale\\;C:\\Program Files\\Microsoft SQL Server\\170\\Tools\\Binn\\;C:\\Program Files\\Microsoft SQL Server\\Client SDK\\ODBC\\170\\Tools\\Binn\\;C:\\Program Files\\Git\\cmd;C:\\Program Files\\PowerToys\\DSCModules\\;C:\\Program Files (x86)\\AOMEI\\AOMEI Backupper\\8.2.0;C:\\Program Files\\Docker\\Docker\\resources\\bin;C:\\Program Files\\IrfanView;C:\\Users\\grigo\\AppData\\Local\\Microsoft\\WindowsApps;C:\\Users\\grigo\\AppData\\Local\\Programs\\Microsoft VS Code\\bin;C:\\Users\\grigo\\AppData\\Local\\Google\\Cloud SDK\\google-cloud-sdk\\bin;C:\\Users\\grigo\\AppData\\Local\\GitHubDesktop\\bin;C:\\Users\\grigo\\AppData\\Local\\Microsoft\\WinGet\\Links;C:\\Program Files\\HP\\Common\\HPDestPlgIn\\;C:\\Program Files (x86)\\HP\\Common\\HPDestPlgIn\\;C:\\Users\\grigo\\AppData\\Local\\Programs\\cursor\\resources\\app\\bin;C:\\Users\\grigo\\AppData\\Local\\Microsoft\\WinGet\\Packages\\Google.PlatformTools_Microsoft.Winget.Source_8wekyb3d8bbwe\\platform-tools;C:\\Users\\grigo\\.dotnet\\tools;C:\\Users\\grigo\\AppData\\Local\\Microsoft\\WindowsApps;', 'PATHEXT': '.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.CPL', 'PROCESSOR_ARCHITECTURE': 'AMD64', 'PROCESSOR_IDENTIFIER': 'Intel64 Family 6 Model 186 Stepping 2, GenuineIntel', 'PROCESSOR_LEVEL': '6', 'PROCESSOR_REVISION': 'ba02', 'PROGRAMDATA': 'C:\\ProgramData', 'PROGRAMFILES': 'C:\\Program Files', 'PROGRAMFILES(X86)': 'C:\\Program Files (x86)', 'PROGRAMW6432': 'C:\\Program Files', 'PROMPT': '$P$G', 'PSEXECUTIONPOLICYPREFERENCE': 'Bypass', 'PSMODULEPATH': 'C:\\Users\\grigo\\Documents\\WindowsPowerShell\\Modules;C:\\Users\\grigo\\AppData\\Local\\Google\\Cloud SDK\\google-cloud-sdk\\platform\\PowerShell;C:\\Program Files\\WindowsPowerShell\\Modules;C:\\WINDOWS\\system32\\WindowsPowerShell\\v1.0\\Modules', 'PS_SCRIPT': 'D:\\!FGG_Repos\\fgg\\fgg.project\\cMeta\\cmeta\\_build_docs.ps1', 'PUBLIC': 'C:\\Users\\Public', 'SCRIPT_DIR': 'D:\\!FGG_Repos\\fgg\\fgg.project\\cMeta\\cmeta', 'SCRIPT_NAME': '_build_docs', 'SESSIONNAME': 'Console', 'SYSTEMDRIVE': 'C:', 'SYSTEMROOT': 'C:\\WINDOWS', 'TEMP': 'c:\\Temp', 'TMP': 'c:\\Temp', 'USERDOMAIN': 'FGG-LENOVO-P14S', 'USERDOMAIN_ROAMINGPROFILE': 'FGG-LENOVO-P14S', 'USERNAME': 'grigo', 'USERPROFILE': 'C:\\Users\\grigo', 'UV': 'C:\\Users\\grigo\\AppData\\Local\\Microsoft\\WinGet\\Links\\uv.exe', 'UV_RUN_RECURSION_DEPTH': '1', 'VIRTUAL_ENV': 'D:\\!FGG_Repos\\fgg\\fgg.project\\cMeta\\cmeta\\.venv', 'VTUNE_PROFILER_2025_DIR': 'D:\\Program Files (x86)\\Intel\\oneAPI\\vtune\\2025.10', 'WINDIR': 'C:\\WINDOWS', 'ZES_ENABLE_SYSMAN': '1', 'DOCUTILSCONFIG': 'D:\\!FGG_Repos\\fgg\\fgg.project\\cMeta\\cmeta\\docs\\en\\docutils.conf'}), capture_output: bool = False, text_cmd: str = 'RUN', timeout: int = None, verbose: bool = False, hide_in_cmd: list = None, hide_in_env: list = 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, space='', capture_env: bool = False, print_env_keys: list = None, print_extra_line: bool = False, print_cur_dir: bool = False, open_shell: bool = False, pack_existing_env_values: bool = False, print_env_with_os_sep_on_new_lines: bool = True, skip_print_env: bool = False)

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).

• hide_in_env (list | None) – List of keys in ENV 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.

• os_env (dict) – Environment variables to inject into the subprocess.

• space – Optional indentation prefix for console output formatting.

• capture_env (bool) – If True, capture and return environment changes produced by the command.

• print_env_keys (list) – Environment variable keys to print after execution.

• print_extra_line (bool) – If True, print an extra blank line in console output.

• print_cur_dir (bool) – If True, print current directory before running command

Returns:

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

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

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)

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.