atomicshop 2.15.11__py3-none-any.whl → 3.10.5__py3-none-any.whl

atomicshop/on_exit.py

@@ -91,25 +91,55 @@ class ExitHandler:
             # Exit the process gracefully
             raise SystemExit(0)
 
-    def register_handlers(self):
-        win32api.SetConsoleCtrlHandler(self.console_handler, True)
-        atexit.register(self.atexit_handler)
-        signal.signal(signal.SIGINT, self.signal_handler)
-        signal.signal(signal.SIGTERM, self.signal_handler)
-
-
-def register_exit_handler(clean_up_function, *args, **kwargs):
+    def register_handlers(
+            self,
+            at_exit: bool = True,
+            console_close: bool = True,
+            kill_signal: bool = True
+    ):
+        """
+        Register the exit handlers.
+
+        :param at_exit: Register the atexit handler.
+            Just remember that the atexit handler will be called right away on [Ctrl+C], meaning if you want to do
+            something specifically on KeyboardInterrupt, you should handle it separately and set this parameter to False.
+            Same goes for all the exceptions.
+        :param console_close: Register the console close handler.
+        :param kill_signal: Register the kill signal handler.
+        """
+        if at_exit:
+            atexit.register(self.atexit_handler)
+        if console_close:
+            win32api.SetConsoleCtrlHandler(self.console_handler, True)
+        if kill_signal:
+            signal.signal(signal.SIGINT, self.signal_handler)
+            signal.signal(signal.SIGTERM, self.signal_handler)
+
+
+def register_exit_handler(
+        clean_up_function,
+        at_exit: bool = True,
+        console_close: bool = True,
+        kill_signal: bool = True,
+        *args, **kwargs):
     """
     This function will register the exit handler to handle exit events: Closing the console, pressing 'CTRL+C',
     Killing the process.
 
     :param clean_up_function: The action to run when one of exit types is triggered.
+    :param at_exit: Register the atexit handler.
+        Just remember that the atexit handler will be called right away on [Ctrl+C], meaning if you want to do something
+        specifically on KeyboardInterrupt, you should handle it separately and set this parameter to False.
+        Same goes for all the exceptions.
+    :param console_close: Register the console close handler.
+    :param kill_signal: Register the kill signal handler.
+        Same problem as with atexit handler, it will be called right away on [Ctrl+C].
     :param args: The arguments to pass to the cleanup action.
     :param kwargs: The keyword arguments to pass to the cleanup action.
     """
     global EXIT_HANDLER_INSTANCE
     EXIT_HANDLER_INSTANCE = ExitHandler(clean_up_function, args, kwargs)
-    EXIT_HANDLER_INSTANCE.register_handlers()
+    EXIT_HANDLER_INSTANCE.register_handlers(at_exit=at_exit, console_close=console_close, kill_signal=kill_signal)
 
 
 def restart_function(callable_function, *args, **kwargs):

atomicshop/package_mains_processor.py

@@ -0,0 +1,84 @@
+"""Loading resources using stdlib importlib.resources APIs (Python 3.7+)
+https://docs.python.org/3/library/importlib.html#module-importlib.resources"""
+import importlib.resources
+from contextlib import redirect_stdout
+import io
+import subprocess
+import sys
+from typing import Callable
+
+
+class PackageMainsProcessor:
+    def __init__(
+            self,
+            script_file_stem: str = None
+    ):
+        self.script_file_stem: str = script_file_stem
+        self.resources_directory_name: str = 'a_mains'
+
+    def get_resource_path(self) -> str:
+        return f'{__package__}.{self.resources_directory_name}'
+
+    def read_script_file_to_string(self) -> str:
+        script_string = importlib.resources.read_text(self.get_resource_path(), f'{self.script_file_stem}.py')
+
+        return script_string
+
+    def execute_script_file(
+            self,
+            function_name: str = 'main',
+            args: tuple = None,
+            kwargs: dict = None,
+            get_printed_output: bool = False
+    ) -> str:
+        """
+        Execute a script file from the package resources and get result as string.
+
+        :param function_name: Name of the function to call within the script.
+        :param args: Tuple of positional arguments to pass to the function.
+        :param kwargs: Dictionary of keyword arguments to pass to the function.
+        :param get_printed_output: If True, captures and returns printed output instead of return value.
+
+        :return: Output of the script execution as a string.
+        """
+
+        if not args:
+            args = ()
+        if not kwargs:
+            kwargs = {}
+
+        module_name = f"{self.get_resource_path()}.{self.script_file_stem}"  # script_file_name WITHOUT ".py"
+
+        module = importlib.import_module(module_name)
+        callable_function: Callable = getattr(module, function_name)
+
+        if get_printed_output:
+            with io.StringIO() as buffer, redirect_stdout(buffer):
+                callable_function(*args, **kwargs)
+                result = buffer.getvalue()
+        else:
+            result = callable_function(*args, **kwargs)
+
+        return result
+
+    def execute_script_with_subprocess(
+            self,
+            arguments: list = None
+    ) -> tuple[str, str, int]:
+        """
+        Execute a script file from the package resources using subprocess and get result as string.
+        :param arguments: Dictionary of arguments to pass to the script.
+            Example: ['--port', '8080', '-v']
+        :return: Tuple containing (stdout, stderr, returncode).
+        """
+
+        # script_file_name WITHOUT ".py"
+        module_name = f"{self.get_resource_path()}.{self.script_file_stem}"
+
+        command = [sys.executable, "-m", module_name]
+        if arguments:
+            command.extend(arguments)
+
+        result = subprocess.run(command, capture_output=True, text=True)
+
+        return result.stdout, result.stderr, result.returncode

atomicshop/permissions/permissions.py

@@ -0,0 +1,22 @@
+import os
+import ctypes
+
+
+def is_admin() -> bool:
+    """
+    Function checks on Windows or POSIX OSes if the script is executed under Administrative Privileges.
+    :return: True / False.
+    """
+
+    if os.name == 'nt':
+        if ctypes.windll.shell32.IsUserAnAdmin() == 0:
+            result = False
+        else:
+            result = True
+    else:
+        if 'SUDO_USER' in os.environ and os.geteuid() == 0:
+            result = True
+        else:
+            result = False
+
+    return result

atomicshop/permissions/ubuntu_permissions.py

@@ -0,0 +1,239 @@
+import os
+import stat
+import contextlib
+import subprocess
+import getpass
+
+# Import pwd only on linux.
+if os.name == 'posix':
+    import pwd
+
+
+def get_sudo_executer_username() -> str:
+    """
+    Function gets the username of the user who executed the script with sudo.
+    :return: str, username.
+    """
+
+    if 'SUDO_USER' in os.environ:
+        return os.environ['SUDO_USER']
+    else:
+        return ''
+
+
+def detect_current_user(
+        optional_env_user_var: str = 'CUSTOM_SCRIPTED_USER'
+) -> str:
+    """
+    Try to robustly determine the 'real' installing user.
+
+    Priority:
+      1. FDB_INSTALL_USER env var (explicit override).
+      2. If running as root with sudo: use SUDO_USER.
+      3. Otherwise: use effective uid.
+      4. Fallbacks: getpass.getuser() / $USER.
+
+    :param optional_env_user_var: str, name of the environment variable that can override the user detection.
+    :return: str, username.
+    """
+
+    # 1. Explicit override for weird environments (CI, containers, etc.)
+    env_user = os.getenv(optional_env_user_var)
+    if env_user:
+        return env_user
+
+    # 2. If we are root, prefer the sudo caller if any
+    try:
+        euid = os.geteuid()
+    except AttributeError:  # non-POSIX, very unlikely here
+        euid = None
+
+    if euid == 0:
+        sudo_user = os.environ.get("SUDO_USER")
+        if sudo_user:
+            return sudo_user
+
+    # 3. Normal case: effective uid -> username
+    if euid is not None:
+        try:
+            return pwd.getpwuid(euid).pw_name
+        except Exception:
+            pass
+
+    # 4. Fallbacks that don’t depend on utmp/tty
+    try:
+        return getpass.getuser()
+    except Exception:
+        return os.environ.get("USER", "unknown")
+
+
+def set_executable(file_path: str):
+    """
+    Function sets the executable permission on a file.
+    Equivalent to: chmod +x <file_path>
+
+    :param file_path: str, path to the file.
+    :return:
+    """
+
+    # os.chmod(file_path, os.stat(file_path).st_mode | 0o111)
+    os.chmod(file_path, os.stat(file_path).st_mode | stat.S_IXUSR)
+
+
+def set_trusted_executable(file_path: str):
+    """
+    Function sets the executable permission on a file and marks it as trusted.
+    :param file_path: str, path to the file.
+    :return:
+    """
+
+    # Check if the file exists
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"The file does not exist: {file_path} ")
+
+    # Execute the `gio set` command
+    subprocess.run(
+        ["gio", "set", file_path, "metadata::trusted", "true"],
+        check=True
+    )
+
+
+def set_xfce_exe_checksum(desktop_file_path):
+    # Expand `~` to the full home directory path
+    desktop_file_path = os.path.expanduser(desktop_file_path)
+
+    # Ensure the file exists
+    if not os.path.exists(desktop_file_path):
+        raise FileNotFoundError(f"The file does not exist: {desktop_file_path} ")
+
+    # Calculate the SHA256 checksum of the file
+    result = subprocess.run(
+        ["sha256sum", desktop_file_path],
+        stdout=subprocess.PIPE,
+        check=True,
+        text=True
+    )
+    checksum = result.stdout.split()[0]
+
+    # Set the metadata::xfce-exe-checksum attribute using `gio`
+    subprocess.run(
+        ["gio", "set", "-t", "string", desktop_file_path, "metadata::xfce-exe-checksum", checksum],
+        check=True
+    )
+
+
+def change_file_owner(file_path: str, username: str):
+    """
+    Function changes the owner of the file to the specified user.
+    :param file_path: str, path to the file.
+    :param username: str, username of the new owner.
+    :return:
+    """
+
+    uid = pwd.getpwnam(username).pw_uid
+    os.chown(file_path, uid, -1)
+
+
+def is_executable(file_path: str) -> bool:
+    """
+    Function checks if the file has the executable permission.
+    Equivalent to: stat -c "%a %n" <file_path>
+
+    :param file_path: str, path to the file.
+    :return: bool, True / False.
+    """
+
+    return bool(os.stat(file_path).st_mode & stat.S_IXUSR)
+
+
+def run_as_root(command):
+    subprocess.check_call(['sudo'] + command)
+
+
+@contextlib.contextmanager
+def temporary_regular_permissions():
+    """
+    This function is used to temporarily change the effective user and group ID to the original user's.
+    This is used to run commands with the original user's permissions.
+    If you executed a script with 'sudo' and wanted certain action to execute as regular user and not root.
+
+    Example:
+        with temporary_regular_permissions():
+            # Do something with regular permissions.
+            pass
+
+    :return:
+    """
+    # Save the current effective user and group ID
+    original_euid, original_egid = os.geteuid(), os.getegid()
+
+    try:
+        # Get the original user's UID and GID
+        orig_uid = int(os.environ.get('SUDO_UID', os.getuid()))
+        orig_gid = int(os.environ.get('SUDO_GID', os.getgid()))
+
+        # Set the effective user and group ID to the original user's
+        os.setegid(orig_gid)
+        os.seteuid(orig_uid)
+
+        # Provide the context to do something with these permissions
+        yield
+    finally:
+        # Revert to the original effective user and group ID
+        os.seteuid(original_euid)
+        os.setegid(original_egid)
+
+
+def expand_user_path(user_name, path):
+    pwnam = pwd.getpwnam(user_name)
+    home_dir = pwnam.pw_dir
+    return path.replace("~", home_dir)
+
+
+def set_folder_permissions(
+        folder_path: str,
+        username: str = None,
+        logged_in_non_sudo_user: bool = False
+):
+    """
+    Set ownership and permissions for an existing folder.
+
+    :param folder_path: Path to the folder (must already exist)
+    :param username: Username to assign ownership to (ignored if non_sudo_user=True)
+    :param logged_in_non_sudo_user: If True, use the current logged-in user unless running under sudo
+    """
+
+    if not username and not logged_in_non_sudo_user:
+        raise ValueError("A username must be provided, or 'non_sudo_user' must be set to True.")
+
+    # Handle non_sudo_user case
+    if logged_in_non_sudo_user:
+        # Get the current logged-in user
+        username = pwd.getpwuid(os.getuid())[0]
+
+    # Get the UID and GID of the specified user
+    user_info = pwd.getpwnam(username)
+    user_uid = user_info.pw_uid
+    user_gid = user_info.pw_gid
+
+    # Change ownership of the folder to the specified user
+    # print(f"Changing ownership of {folder_path} to user '{username}'...")
+    os.chown(folder_path, user_uid, user_gid)
+
+    # Set appropriate permissions (read, write, execute for the owner)
+    # print(f"Setting permissions for {folder_path}...")
+    os.chmod(folder_path, 0o755)  # Owner rwx, group r-x, others r-x
+
+    # print(f"Ownership and permissions updated for folder: '{folder_path}'")
+
+
+def is_directory_owner(directory_path: str, username: str) -> bool:
+    """
+    Function checks if the directory is owned by the specified user.
+    :param directory_path: str, path to the directory.
+    :param username: str, username of the user.
+    :return: bool, True / False.
+    """
+
+    uid = pwd.getpwnam(username).pw_uid
+    return os.stat(directory_path).st_uid == uid

atomicshop/permissions/win_permissions.py

@@ -0,0 +1,33 @@
+import subprocess
+
+
+def unblock_file_windows(file_path):
+    """
+    Unblock a file on Windows. This is used to unblock files downloaded from the internet.
+    When you Right-click then navigate to Properties, you will see the Unblock checkbox.
+    :param file_path:
+    :return:
+    """
+    try:
+        subprocess.run(["powershell", "-Command", f"Unblock-File -Path '{file_path}'"], check=True)
+        print(f"Successfully unblocked the file: {file_path}")
+    except subprocess.CalledProcessError as e:
+        print(f"Failed to unblock the file: {file_path}\nError: {e}")
+
+
+def get_command_to_run_as_admin_windows(command: str) -> str:
+    """
+    Function returns the command to run a command as administrator on Windows.
+    NOTE: When you run something this way, the parent will be the powershell.exe process.
+        If you need a status result directly of the executed command, you need to use subprocess.run() instead.
+
+    :param command: str, command to run.
+    :return: str, command to run as administrator.
+    """
+
+    executable = command.split()[0]
+    command = (
+        f"powershell -Command "
+        f"\"Start-Process {executable} -ArgumentList '{' '.join(command.split()[1:])}' -Verb RunAs\"")
+
+    return command

atomicshop/print_api.py

@@ -1,17 +1,18 @@
 import sys
+import logging
+from typing import Any
 
-from .basics.ansi_escape_codes import ColorsBasic, get_colors_basic_dict
+from .basics import ansi_escape_codes
 from .basics import tracebacks
 
 
-# noinspection PyUnusedLocal,PyIncorrectDocstring
 def print_api(
-        message: any,
-        color: any = None,
+        message: Any,
+        color: Any = None,
         print_end: str = '\n',
         rtl: bool = False,
         error_type: bool = False,
-        logger: object = None,
+        logger: logging.Logger = None,
         logger_method: str = 'info',
         stdout: bool = True,
         stderr: bool = True,
@@ -19,8 +20,6 @@ def print_api(
         traceback_string: bool = False,
         oneline: bool = False,
         oneline_end: str = '',
-        # raise_exception: bool = True,
-        # exit_on_error: bool = False,
         **kwargs: object) -> None:
     """
     Function of custom api that is responsible for printing messages to console.
@@ -82,18 +81,26 @@ def print_api(
 
         # This section takes care of different types of string manipulations for message.
 
-        # If 'exit_on_error' is set to 'True', we'll add 'exit_message' on new line after 'message'.
-        # if error_type and exit_on_error and raise_exception:
-        #     message = message + '\n' + exit_message
-
         # If 'rtl' is set to 'True', we'll add Right-To-Left text conversion to 'message'.
         if rtl:
-            # Lazy importing of 'bidi' library. It's not a problem since python caches the library after first import.
-            # Off-course, it will be imported from the cache each time this section is triggered.
             # pip install python-bidi
             from bidi.algorithm import get_display
             message = get_display(message)
 
+        if logger_method == 'error' or logger_method == 'critical':
+            error_type = True
+
+        # If exception was raised and 'stderr=True'.
+        if sys.exc_info()[0] is not None and stderr and traceback_string:
+            # If 'traceback' is set to 'True', we'll output traceback of exception.
+            if traceback_string:
+                if message:
+                    message = f'{message}\n{tracebacks.get_as_string()}{message}'
+                else:
+                    message = tracebacks.get_as_string()
+
+            color = 'red'
+
         # If 'stdcolor' is 'True', the console output will be colored.
         if stdcolor:
             # If 'logger.error' should be outputted to console, and 'color' wasn't selected, then set color to 'yellow'.
@@ -103,19 +110,8 @@ def print_api(
             elif logger_method == 'critical' and not color:
                 color = 'red'
 
-            if color:
-                message = get_colors_basic_dict(color) + message + ColorsBasic.END
-
-        if logger_method == 'error' or logger_method == 'critical':
-            error_type = True
-
-        # If exception was raised and 'stderr=True'.
-        if sys.exc_info()[0] is not None and stderr:
-            # If 'traceback' is set to 'True', we'll output traceback of exception.
-            if traceback_string:
-                message = f'{message} | Exception: {tracebacks.get_as_string()}'
-
-            color = 'red'
+            if color is not None:
+                message = ansi_escape_codes.get_colors_basic_dict(color) + message + ansi_escape_codes.ColorsBasic.END
 
         # If 'online' is set to 'True', we'll output message as oneline.
         if oneline:
@@ -130,14 +126,14 @@ def print_api(
             if print_end == '\n':
                 # Use logger to output message.
                 getattr(logger, logger_method)(message)
+            else:
+                raise ValueError("Logger can't output messages with 'print_end' other than '\\n'.")
         # If logger wasn't passed.
         else:
             # Use print to output the message.
             print(message, end=print_end)
 
     # = Main Section with printing cases ===============================================================================
-    # exit_message: str = 'Exiting...'
-
     # Convert message to string.
     message = str(message)
 
@@ -151,20 +147,6 @@ def print_api(
         if error_type:
             print_or_logger()
 
-    # ==================================
-    # This section is responsible for ending the script.
-
-    # Check if we're inside exception. In this case each of 3 entries in 'sys.exc_info()' tuple will not equal
-    # to 'None', so picked only the first one.
-    # if sys.exc_info()[0] and not exit_on_error:
-    #     # If 'raise_exception' is set to 'True', we'll end the script with exception.
-    #     if pass_exception:
-    #         pass
-
-    # If 'exit_on_error' is set to 'True', we'll end the script.
-    # if exit_on_error and error_type:
-    #     sys.exit()
-
 
 def print_status(
         prefix_string: str,

atomicshop/process.py

@@ -82,7 +82,18 @@ def execute_with_live_output(
     :return: Boolean, If execution was successful, return True, if not - False.
     """
 
-    cmd = _execution_parameters_processing(cmd, wsl)
+    if isinstance(cmd, str):
+        shell = True
+    elif isinstance(cmd, list):
+        shell = False
+    else:
+        raise TypeError(f'cmd must be a string or list, not {type(cmd)}')
+
+    if wsl:
+        if isinstance(cmd, str):
+            cmd = 'wsl ' + cmd
+        elif isinstance(cmd, list):
+            cmd = ['wsl'] + cmd
 
     # Needed imports:
     # from subprocess import Popen, PIPE, STDOUT
@@ -103,7 +114,7 @@ def execute_with_live_output(
     #   The buffer size is system-dependent and usually chosen by the underlying implementation to optimize performance.
     #   # bufsize=0: This means no buffering.
     #   The I/O is unbuffered, and data is written or read from the stream immediately.
-    with subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, bufsize=1, text=True) as process:
+    with subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, bufsize=1, text=True, shell=shell) as process:
         # We'll count the number of lines from 'process.stdout'.
         counter: int = 0
         # And also get list of all the lines.
@@ -305,14 +316,21 @@ def kill_process_by_filename_pattern(pattern: str):
         processes.kill_process_by_pid(running_processes[0]['pid'])
 
 
-def run_powershell_command(command):
+def run_powershell_command(
+        command: str
+):
     try:
         result = subprocess.run(["powershell", "-Command", command], capture_output=True, text=True, check=True)
-        print_api(result.stdout)
+        if result.stdout:
+            print_api(result.stdout)
+        if result.stderr:  # PS can write warnings to stderr even on success
+            print_api(result.stderr, color='yellow')
         return result.stdout
     except subprocess.CalledProcessError as e:
-        print_api(f"An error occurred: {e}", color='red', error_type=True)
-        return e
+        # e.stderr and e.stdout are populated because capture_output=True
+        msg = (e.stderr or e.stdout or f"PowerShell exited with code {e.returncode}")
+        print_api(msg, color='red', error_type=True)
+        return msg
 
 
 """

atomicshop/process_poller/process_pool.py

@@ -3,7 +3,6 @@ import multiprocessing
 import time
 from typing import Literal, Union
 
-from ..print_api import print_api
 from .tracers import sysmon_etw, event_log
 from .pollers import psutil_pywin32wmi_dll
 from ..wrappers.pywin32w.win_event_log.subscribes import process_terminate