ae.shell

shell execution and environment helpers

Hint

this module is designed to provide a comprehensive set of constants and helper functions for executing and managing external shell commands.

debug_or_verbose(): checks if the application is running in debug or verbose mode.
get_domain_user_var(): retrieves an OS environment variable value for a specific domain and/or user.
hint(): provides a hint message based on the provided arguments.
in_os_env(): context manager to temporarily add environment variables from the dotenv files that not exist in os.environ to it.
mask_token(): hide/mask tokens in a text block, to prevent to show them in logs or error messages.
sh_exec(): generic/fundamental function for all other shell execution helpers.
sh_exit_if_exec_err(): extended version of sh_exec() with automatically checks for errors after a command is executed and handles application termination gracefully.
STDERR_BEG_MARKER: marker used in the console output for the beginning of stderr output.
STDERR_END_MARKER: marker used in the console output for the end of stderr output.

Module Attributes

`STDERR_BEG_MARKER`	`ae.shell.sh_exec.lines_output` begin stderr lines
`STDERR_END_MARKER`	end stderr lines in `ae.shell.sh_exec.lines_output`

Functions

`debug_or_verbose`([app_obj])	determine if the current app runs in debug\|verbose mode, while preventing early .get_option() call an app init.
`get_domain_user_var`(variable_name[, domain, ...])	determine the value of an OS environment variable for a specific domain and/or username.
`hint`(command, action[, message_suffix])	return hint string in debug/verbose mode, to be appended onto a shell/console output.
`in_os_env`([start_dir])	temporarily add environment variables from the dotenv files that not exist in os.environ to it.
`mask_token`(text)
`sh_exec`(command_line[, extra_args, ...])	execute command in the current working directory of the OS console/shell.
`sh_exit_if_exec_err`(err_code, command_line)	execute command in the current working directory of the OS console/shell, dump error, and exit app if needed.

STDERR_BEG_MARKER = 'vvv STDERR vvv': ae.shell.sh_exec.lines_output begin stderr lines

STDERR_END_MARKER = '^^^ STDERR ^^^': end stderr lines in ae.shell.sh_exec.lines_output

debug_or_verbose(app_obj=None)[source]

determine if the current app runs in debug|verbose mode, while preventing early .get_option() call an app init.

Parameters:: app_obj¶ (Optional[ConsoleApp]) – optional ConsoleApp instance (def=main_app_instance()).
Return type:: bool
Returns:: a boolean False when the main app debug level is DEBUG_LEVEL_DISABLED and the app option ‘more_verbose’ is not specified (in cfg-file or at the command line), else True.

Note

the return value on app startup/initialization, before the command line parsing, is always True.

Hint

the debug mode can be activated via the ConsoleApp option debug_level, specified either in a config file or via the command line options. the verbose mode get activated via the more_verbose option.

get_domain_user_var(variable_name, domain='', user='')[source]

determine the value of an OS environment variable for a specific domain and/or username.

Parameters:

variable_name¶ (str) – name of the config variable.
domain¶ (str) – name of the domain.
user¶ (str) – name/id of the user to get a user-specific value of.

Return type:

Any

Returns:

domain/user-specific value of the specified config variable.

hint(command, action, message_suffix='')[source]

return hint string in debug/verbose mode, to be appended onto a shell/console output.

Parameters:

command¶ (str) – shell command.
action¶ (Union[Callable, str]) – shell command action function/method.
message_suffix¶ (str) – extra message text, added to the end of the returned console output string.

Return type:

str

Returns:

in debug/verbose mode return a string with leading line feed to be sent to console output, else return an empty string.

in_os_env(start_dir='')[source]

temporarily add environment variables from the dotenv files that not exist in os.environ to it.

Parameters:: start_dir¶ (str) – path to the folder where the first dotenv file (with the highest priority) is stored.
Return type:: Iterator[MutableMapping[str, str]]
Returns:: yielding the os env variables that got added to os.environ in this temporary context.

mask_token(text)[source]

Overloads:

text (str) → str
text (list[str]) → list[str]

hide most parts of any Codeberg/GitHub/GitHub URL tokens found in the specified text/-lines.

Parameters:: text¶ (Union[str, list[str]]) – text, specified either as str object or as a list of str objects (lines), each str/line get searched for URL tokens, to hide/mask the most part of them.
Returns:: text with masked URL tokens (only leaving the first/last 3 token characters unmasked).

Note

see also ae.base.mask_url() of a more generic way to hide passwords and tokens in URLs.

sh_exec(command_line, extra_args=(), console_input='', lines_output=None, app_obj=None, shell=False, env_vars=None)[source]

execute command in the current working directory of the OS console/shell.

Parameters:

command_line¶ (str) – command line string to execute on the console/shell. could contain command line args separated by whitespace characters (alternatively use extra_args).
extra_args¶ (Iterable[str]) – optional sequence of extra command line arguments.
console_input¶ (str) – optional string to be sent to the stdin stream of the console/shell.
lines_output¶ (Optional[list[str]]) – optional list to be extended with the lines printed to stdout/stderr on execution. by passing an empty list, the stdout and stderr streams/pipes will be separated, resulting in having the stderr output lines at the end of the list, enclosed by the list items STDERR_BEG_MARKER and STDERR_END_MARKER.
app_obj¶ (Optional[AppBase]) – optional AppBase/ConsoleApp instance, used for logging. if not specified or None and if main_app_instance() returns None then the Python print() function is used. specify UNSET to suppress any printing/logging output.
shell¶ (bool) – pass True to execute command in the default OS shell (see subprocess.run()).
env_vars¶ (Optional[dict[str, str]]) – OS shell environment variables to be used instead of the console/bash defaults.

Return type:

int

Returns:

return code of the executed command or 126 if execution raised any other exception.

sh_exit_if_exec_err(err_code, command_line, extra_args=(), lines_output=None, exit_on_err=True, exit_msg='', app_obj=None, shell=False, env_vars=None)[source]

execute command in the current working directory of the OS console/shell, dump error, and exit app if needed.

Parameters:

err_code¶ (int) – error code to pass to the console as exit code if exit_on_err is True.
command_line¶ (str) – command line string to execute on the console/shell. could contain command line args separated by whitespace characters (alternatively use extra_args).
extra_args¶ (Iterable[str]) – optional iterable of extra command line arguments.
lines_output¶ (Optional[list[str]]) – optional list to return the lines printed to stdout/stderr on execution. by passing an empty list, the stdout and stderr streams/pipes will be separated, resulting in having the stderr output lines at the end of the list. specify at least on list item to merge-in the stderr output (into the stdout output and return).
exit_on_err¶ (bool) – pass False to not exit the app on error (exit_msg has then to be empty).
exit_msg¶ (str) – additional text to print on stdout/console if the app debug level is greater or equal to 1 or if an error occurred and exit_on_err is True.
app_obj¶ (Optional[ConsoleApp]) – ConsoleApp instance, used for logging/force-ignorable error.
shell¶ (bool) – pass True to execute command in the default OS shell (see subprocess.run()).
env_vars¶ (Optional[dict[str, str]]) – OS shell environment variables to be used instead of the console/bash defaults.

Return type:

int

Returns:

0 on success or the error number if an error occurred.