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

atomicshop/on_exit.py

@@ -0,0 +1,205 @@
+import atexit
+import signal
+import sys
+import platform
+
+import win32api
+import win32con
+
+from .print_api import print_api
+from .wrappers.pywin32w import console
+
+
+EXIT_HANDLER_INSTANCE = None
+
+
+class ExitHandler:
+    """
+    This class is used to handle exit events: Closing the console, pressing 'CTRL+C', Killing the process.
+
+    Example:
+        from atomicshop import on_exit
+
+
+        def clean_up_function():
+            print("Cleaning up.")
+
+
+        on_exit.ExitHandler(clean_up_function).register_handlers()
+
+        # OR
+        on_exit.register_exit_handler(clean_up_function)
+    """
+    def __init__(
+            self,
+            cleanup_action: callable,
+            args: tuple = None,
+            kwargs: dict = None
+    ):
+        """
+        :param cleanup_action: The action to run when one of exit types is triggered.
+        :param args: The arguments to pass to the cleanup action.
+        :param kwargs: The keyword arguments to pass to the cleanup action.
+        """
+
+        if not callable(cleanup_action):
+            raise ValueError("The 'cleanup_action' must be a callable function.")
+
+        if args is None:
+            args = tuple()
+
+        if kwargs is None:
+            kwargs = dict()
+
+        self.cleanup_action: callable = cleanup_action
+        self.args: tuple = args
+        self.kwargs: dict = kwargs
+
+        self._called: bool = False
+        self._handler_hit: bool = False
+
+    def _run_cleanup(self):
+        if not self._called:
+            self._called = True
+            self.cleanup_action(*self.args, **self.kwargs)
+
+    def console_handler(self, event):
+        if event == win32con.CTRL_CLOSE_EVENT:
+
+            if not self._handler_hit:
+                self._handler_hit = True
+
+                print("Console close event.")
+                self._run_cleanup()
+
+            return True
+        return False
+
+    def atexit_handler(self):
+        if not self._handler_hit:
+            self._handler_hit = True
+
+            print("atexit_handler")
+            self._run_cleanup()
+
+    def signal_handler(self, signum, frame):
+        if not self._handler_hit:
+            self._handler_hit = True
+
+            print_api(f"Signal {signum}")
+            self._run_cleanup()
+            # Exit the process gracefully
+            raise SystemExit(0)
+
+    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(at_exit=at_exit, console_close=console_close, kill_signal=kill_signal)
+
+
+def restart_function(callable_function, *args, **kwargs):
+    """
+    This function will run the callable function with the given arguments and keyword arguments.
+    If the function raises an exception, the function will be restarted.
+
+    :param callable_function: The function to run.
+    :param args: The arguments to pass to the function.
+    :param kwargs: The keyword arguments to pass to the function.
+    :return: The return value of the function.
+    """
+    while True:
+        try:
+            return callable_function(*args, **kwargs)
+        except Exception as e:
+            print(f"ERROR: {e}")
+            continue
+
+
+def _ref_run_callable_on_exit_and_signals(
+        callable_function,
+        print_kwargs: dict = None,
+        *args,
+        **kwargs
+):
+    """
+    THIS IS FOR REFERENCE ONLY.
+
+    This function will run the callable function with the given arguments and keyword arguments.
+    If the function raises an exception, the function will be restarted.
+
+    :param callable_function: The function to run.
+    :param print_kwargs: print_api kwargs.
+    :param args: The arguments to pass to the function.
+    :param kwargs: The keyword arguments to pass to the function.
+    :return: The return value of the function.
+    """
+    def signal_handler(signum, frame):
+        print_api(f"Signal {signum} received, exiting.", **(print_kwargs or {}))
+        callable_function(*args, **kwargs)
+        sys.exit(0)
+
+    def exit_handler():
+        print_api("Exiting.", **(print_kwargs or {}))
+        callable_function(*args, **kwargs)
+        sys.exit(0)
+
+    signals = [signal.SIGINT, signal.SIGTERM]
+    if platform.system() != 'Windows':
+        signals.append(signal.SIGQUIT)
+        signals.append(signal.SIGHUP)
+    for sig in signals:
+        signal.signal(sig, signal_handler)
+
+    # signal.signal(signal.SIGINT, signal_handler)
+    # signal.signal(signal.SIGTERM, signal_handler)
+    atexit.register(exit_handler)
+
+    # Register console handler for Windows.
+    if platform.system() == 'Windows':
+        console_handler = console.ConsoleHandler(exit_handler, args, kwargs)
+        console_handler.register_handler()

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