pytron-kit 0.3.12__py3-none-win_amd64.whl

pytron/apputils/config.py

@@ -0,0 +1,303 @@
+import os
+import sys
+import json
+import logging
+from ..utils import get_resource_path
+from ..exceptions import ConfigError
+
+
+class ConfigMixin:
+    def _setup_logging(self):
+        # If we use basicConfig, it might interfere with user's settings.
+        # But for a simple CLI tool, it's often preferred.
+        # Let's check if the root logger has any handlers already.
+        if not logging.root.handlers:
+            logging.basicConfig(
+                level=logging.INFO,
+                format="[Pytron] %(asctime)s - %(levelname)s - %(message)s",
+                datefmt="%H:%M:%S",
+            )
+        self.logger = logging.getLogger("Pytron")
+
+    def _check_deep_link(self):
+        self.state.launch_url = None
+        # Scan all args for a possible deep link (some OS pass it at different positions)
+        # or it might be preceded by flags.
+        for arg in sys.argv[1:]:
+            if arg.startswith("pytron:") or "://" in arg:
+                # Basic validation: ensure it's not a local file path with :// (unlikely on Win)
+                if ":" in arg and not os.path.exists(arg):
+                    self.logger.info(f"App launched via Deep Link: {arg}")
+                    self.state.launch_url = arg
+                    break
+                # Defer dispatch to run-time if needed, but since plugins/handlers
+                # might be registered AFTER init, we might need to handle this carefully.
+                # However, for now, we'll store it. The handlers usually aren't registered
+                # until the user script runs.
+                # So we should probably dispatch in app.run().
+
+    def _load_config(self, config_file):
+        self.config = {}
+        path = get_resource_path(config_file)
+        self.logger.debug(f"Resolved settings path: {path}")
+
+        if not os.path.exists(path):
+            path = os.path.abspath(config_file)
+
+        if os.path.exists(path):
+            try:
+                with open(path, "r") as f:
+                    self.config = json.load(f)
+
+                if self.config.get("debug", False):
+                    self.logger.setLevel(logging.DEBUG)
+                    for handler in logging.root.handlers:
+                        handler.setLevel(logging.DEBUG)
+                    self.logger.debug("Debug mode enabled.")
+
+                    dev_url = os.environ.get("PYTRON_DEV_URL")
+                    if dev_url:
+                        self.config["url"] = dev_url
+                        self.logger.info(f"Dev mode: Overriding URL to {dev_url}")
+
+                config_version = self.config.get("pytron_version")
+                if config_version:
+                    try:
+                        from .. import __version__
+
+                        if config_version != __version__:
+                            self.logger.warning(
+                                f"Version mismatch: Settings({config_version}) vs Installed({__version__})"
+                            )
+                    except ImportError:
+                        pass
+            except json.JSONDecodeError as e:
+                self.logger.error(f"Failed to parse settings.json: {e}")
+                raise ConfigError(f"Invalid JSON in settings file: {path}") from e
+            except Exception as e:
+                self.logger.error(f"Failed to load settings: {e}")
+                raise ConfigError(f"Could not load settings from {path}") from e
+        else:
+            self.logger.warning(
+                f"Settings file not found at {path}. Using default configuration."
+            )
+
+    def _setup_identity(self):
+        title = self.config.get("title", "Pytron App")
+        safe_title = "".join(
+            c if c.isalnum() or c in ("-", "_") else "_" for c in title
+        ).strip("_")
+        app_id = self._register_app_id(title, safe_title)
+
+        # Single Instance Guard
+        if self.config.get("single_instance", True):
+            self._setup_single_instance(app_id)
+
+        return title, safe_title
+
+    def _register_app_id(self, title, safe_title):
+        author = self.config.get("author", "PytronUser")
+        if not safe_title:
+            safe_title = (
+                "".join([c for c in (title or "Pytron") if c.isalnum()]) or "PytronApp"
+            )
+        app_id = f"{author}.{safe_title}.App"
+
+        if sys.platform == "win32" and getattr(sys, "frozen", False):
+            try:
+                from ..platforms.windows import WindowsImplementation
+
+                WindowsImplementation().set_app_id(app_id)
+                self.logger.debug(f"Set Windows AppUserModelID: {app_id}")
+            except Exception as e:
+                self.logger.debug(f"Failed to set App ID: {e}")
+        elif sys.platform == "linux":
+            try:
+                from ..platforms.linux import LinuxImplementation
+
+                LinuxImplementation().set_app_id(safe_title)
+            except Exception as e:
+                self.logger.debug(f"Failed to set Linux App ID: {e}")
+        elif sys.platform == "darwin":
+            try:
+                from ..platforms.darwin import DarwinImplementation
+
+                DarwinImplementation().set_app_id(title)
+            except Exception as e:
+                self.logger.debug(f"Failed to set Darwin App ID: {e}")
+        return app_id
+
+    def _setup_single_instance(self, app_id):
+        import socket
+        import hashlib
+        import threading
+        import os
+
+        # Skip during tests and development as they often require flexibility
+        if "PYTEST_CURRENT_TEST" in os.environ or not getattr(sys, "frozen", False):
+            return
+
+        # Generate a stable port between 10000-60000 based on app_id
+        # B324: Use SHA256 instead of MD5 for port generation stability
+        port = 10000 + (int(hashlib.sha256(app_id.encode()).hexdigest(), 16) % 50000)
+        self._instance_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+
+        try:
+            self._instance_socket.bind(("127.0.0.1", port))
+            self._instance_socket.listen(1)
+
+            def _listen_for_other_instances():
+                while True:
+                    try:
+                        conn, _ = self._instance_socket.accept()
+                        data = conn.recv(1024).decode("utf-8")
+                        if data:
+                            msg = json.loads(data)
+                            url = msg.get("url")
+                            if url:
+                                self.logger.info(
+                                    f"Received deep link from another instance: {url}"
+                                )
+                                # Update launch URL and show windows
+                                self.state.launch_url = url
+                                self.router.dispatch(url)
+                                for window in self.windows:
+                                    window.show()
+                                    window.emit("pytron:deep-link", {"url": url})
+                        conn.close()
+                    except Exception:
+                        break
+
+            t = threading.Thread(target=_listen_for_other_instances, daemon=True)
+            t.start()
+
+            @self.on_exit
+            def _close_instance_socket():
+                try:
+                    self._instance_socket.close()
+                except Exception as e:
+                    self.logger.debug(f"Error closing instance socket: {e}")
+
+        except socket.error:
+            # Instance already running!
+            self.logger.info(
+                "Another instance is already running. Forwarding launch URL and exiting."
+            )
+            try:
+                client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                client.connect(("127.0.0.1", port))
+                client.send(json.dumps({"url": self.state.launch_url}).encode("utf-8"))
+                client.close()
+            except Exception:
+                pass
+            # Critical: Use os._exit(0) instead of sys.exit(0)
+            # sys.exit() raises SystemExit, which can be caught by the bootstrap wrapper
+            # or Cython, leading to a false positive "Shield Error".
+            # os._exit() terminates immediately at the OS level, which is safe here
+            # because we want to vanish instantly after forwarding the intent.
+            os._exit(0)
+
+    def _setup_storage(self, safe_title):
+        if sys.platform == "win32":
+            base_path = os.environ.get("LOCALAPPDATA", os.path.expanduser("~"))
+        elif os.environ.get("PYTHON_PLATFORM") == "android":
+            python_home = os.environ.get("PYTHONHOME")
+            if python_home:
+                base_path = os.path.dirname(python_home)
+            else:
+                base_path = os.path.expanduser("~")
+        else:
+            base_path = os.path.expanduser("~/.config")
+
+        self.storage_path = os.path.join(base_path, safe_title)
+
+        if getattr(sys, "frozen", False):
+            self.app_root = os.path.dirname(os.path.abspath(sys.executable))
+        else:
+            # Better way to find app root than os.getcwd() which depends on where user ran Python
+            main_module = sys.modules.get("__main__")
+            if main_module and hasattr(main_module, "__file__"):
+                self.app_root = os.path.dirname(os.path.abspath(main_module.__file__))
+            else:
+                self.app_root = os.path.abspath(
+                    sys.path[0] if sys.path and sys.path[0] else os.getcwd()
+                )
+
+        try:
+            os.makedirs(self.storage_path, exist_ok=True)
+            if getattr(sys, "frozen", False):
+                os.chdir(self.storage_path)
+                self.logger.info(f"Changed Working Directory to: {self.storage_path}")
+            else:
+                self.logger.debug(
+                    f"Dev Mode: Storage directory ready at {self.storage_path}"
+                )
+        except Exception as e:
+            self.logger.warning(
+                f"Could not create storage directory at {self.storage_path}: {e}"
+            )
+
+    def _resolve_resources(self):
+        def resolve_resource(path):
+            if (
+                not path
+                or path.startswith(("http:", "https:", "file:"))
+                or os.path.isabs(path)
+            ):
+                return path
+
+            internal = os.path.join(self.app_root, "_internal", path)
+            if os.path.exists(internal):
+                return internal
+
+            candidate = os.path.join(self.app_root, path)
+            if os.path.exists(candidate):
+                return candidate
+
+            return get_resource_path(path)
+
+        if "url" in self.config:
+            self.config["url"] = resolve_resource(self.config["url"])
+
+        if "icon" in self.config:
+            orig_icon = self.config["icon"]
+            resolved_icon = resolve_resource(orig_icon)
+            if os.path.exists(resolved_icon):
+                self.config["icon"] = resolved_icon
+                self.logger.info(f"Resolved icon to: {resolved_icon}")
+            else:
+                self.logger.warning(f"Could not find icon at: {orig_icon}")
+
+    def _setup_key_value_store(self):
+        self._store_file = os.path.join(self.storage_path, "store.json")
+        self._kv_store = {}
+        if os.path.exists(self._store_file):
+            try:
+                with open(self._store_file, "r") as f:
+                    self._kv_store = json.load(f)
+            except Exception as e:
+                self.logger.warning(f"Failed to load persistent store: {e}")
+
+    def store_set(self, key, value):
+        """Sets a value in the persistent store."""
+        self._kv_store[key] = value
+        self._save_store()
+
+    def store_get(self, key, default=None):
+        """Gets a value from the persistent store."""
+        return self._kv_store.get(key, default)
+
+    def store_delete(self, key):
+        """Removes a key from the persistent store."""
+        if key in self._kv_store:
+            del self._kv_store[key]
+            self._save_store()
+            return True
+        return False
+
+    def _save_store(self):
+        try:
+            with open(self._store_file, "w") as f:
+                json.dump(self._kv_store, f)
+        except Exception as e:
+            self.logger.error(f"Failed to save persistent store: {e}")

pytron/apputils/deadmansswitch.py

@@ -0,0 +1,47 @@
+import time
+import os
+import threading
+import logging
+
+
+class DeadMansSwitch:
+    """
+    Ensures that if the UI process (Child) dies, the Backend (Parent) commits seppuku immediately.
+    Preventing zombie python processes in the background.
+    """
+
+    def __init__(self, ui_process):
+        """
+        ui_process: The subprocess.Popen object of electron.exe or webview
+        """
+        self.proc = ui_process
+        self.running = True
+        self.logger = logging.getLogger("Pytron.DeadMansSwitch")
+        self._thread = threading.Thread(target=self._monitor, daemon=True)
+        self._thread.start()
+
+    def _monitor(self):
+        while self.running:
+            try:
+                # 1. Check if Child (UI) is alive
+                if self.proc.poll() is not None:
+                    self.logger.warning(
+                        f"UI Process {self.proc.pid} died. Exiting backend..."
+                    )
+                    self.kill_backend()
+
+                # 2. Check if Parent (Launcher) is alive
+                # (Only needed if Pytron itself is launched by another tool)
+                # if os.getppid() == 1: # On Linux, adopted by init
+                #     self.kill_backend()
+
+                time.sleep(1)  # Low overhead polling
+            except Exception:
+                # If we can't poll, something is wrong
+                self.kill_backend()
+
+    def kill_backend(self):
+        self.running = False
+        self.logger.critical("Dead Man's Switch Triggered.")
+        # Hard exit to ensure we don't hang on cleanup
+        os._exit(0)

pytron/apputils/extras.py

@@ -0,0 +1,76 @@
+import os
+from ..tray import SystemTray
+
+
+class ExtrasMixin:
+    def load_plugin(self, manifest_path):
+        from ..plugin import Plugin, PluginError
+
+        try:
+            plugin = Plugin(manifest_path)
+            plugin.check_dependencies()
+            plugin.load(self)
+            self.plugins.append(plugin)
+            self.logger.info(f"Loaded plugin: {plugin.name} v{plugin.version}")
+        except PluginError as e:
+            self.logger.error(f"Failed to load plugin from {manifest_path}: {e}")
+        except Exception as e:
+            self.logger.error(
+                f"Unexpected error loading plugin from {manifest_path}: {e}"
+            )
+
+    def setup_tray(self, title=None, icon=None):
+        if not title:
+            title = self.config.get("title", "Pytron")
+        if not icon and "icon" in self.config:
+            icon = self.config["icon"]
+        if icon and not os.path.isabs(icon):
+            icon = os.path.join(self.app_root, icon)
+        self.tray = SystemTray(title, icon)
+        return self.tray
+
+    def setup_tray_standard(self, title=None, icon=None):
+        # Native Engine Check
+        if hasattr(self, "engine") and self.engine == "native":
+            # We assume window 0 is main.
+            # If windows aren't created yet, we can't create tray on native easily unless we cache it.
+            # But setup_tray is usually called before run().
+            # The native tray requires the event loop (which starts in run()).
+            # So we should queue this creation?
+            # Or we leverage the fact that user calls `app.setup_tray` then `app.run`.
+            # `app.run` calls `self.windows[0].start()`.
+            # `webview.py` start connects bindings.
+
+            # The best way is to let `webview.create_tray` happen AFTER run starts?
+            # No, `create_tray` sends an event. If loop not started, event is lost or queued?
+            # `EventLoopProxy` can send events before run? Yes, usually.
+
+            if not title:
+                title = self.config.get("title", "Pytron")
+            if not icon:
+                icon = self.config.get("icon")
+            if icon and not os.path.isabs(icon):
+                icon = os.path.join(self.app_root, icon)
+
+            # We defer this to the first window's initialization if possible, or sets a config?
+            # Actually, if we just call it on the window instance, and the window exists...
+            # app.windows is empty at setup time usually?
+            # In `app.py`: `app = App(...)`, `app.create_window(...)`, `app.setup_tray...`
+            # If create_window already added to self.windows, then yes.
+
+            if self.windows:
+                try:
+                    self.windows[0].create_tray(icon, title)
+                    self.logger.info("Used Native Tray integration.")
+                    # Enable Close-to-Tray for standard tray setup
+                    self.windows[0].config["close_to_tray"] = True
+                    return None
+                except Exception as e:
+                    self.logger.warning(f"Native Tray failed, falling back: {e}")
+
+        tray = self.setup_tray(title, icon)
+        tray.add_item("Show App", self.show)
+        tray.add_item("Hide App", self.hide)
+        tray.add_separator()
+        tray.add_item("Quit", self.quit)
+        return tray

pytron/apputils/native.py

@@ -0,0 +1,148 @@
+import sys
+import os
+from typing import Optional
+
+
+class NativeMixin:
+    """
+    Mixin class to handle native system interactions.
+    """
+
+    def set_start_on_boot(self, enable=True):
+        """
+        Enables or disables automatic application startup on system boot.
+        """
+        app_name = self.config.get("title", "PytronApp")
+        # Sanitize for registry key
+        safe_name = "".join(c if c.isalnum() else "_" for c in app_name)
+
+        if not getattr(sys, "frozen", False):
+            self.logger.info("Skipping Start-on-Boot registration in Development Mode.")
+            return False
+
+        exe_path = f'"{sys.executable}"'  # Quote for safety
+
+        # We need a platform instance.
+        # Since App doesn't hold it, we instantiate temporarily or grab from first window
+        if self.windows:
+            # Best effort
+            try:
+                return self.windows[0]._platform.set_launch_on_boot(
+                    safe_name, exe_path, enable
+                )
+            except Exception as e:
+                self.logger.debug(f"Failed to set start on boot via window: {e}")
+
+        # Fallback if no window yet or needed
+        try:
+            import platform
+
+            sys_plat = platform.system()
+            impl = None
+            if sys_plat == "Windows":
+                from ..platforms.windows import WindowsImplementation
+
+                impl = WindowsImplementation()
+            elif sys_plat == "Linux":
+                from ..platforms.linux import LinuxImplementation
+
+                impl = LinuxImplementation()
+            elif sys_plat == "Darwin":
+                from ..platforms.darwin import DarwinImplementation
+
+                impl = DarwinImplementation()
+
+            if impl:
+                return impl.set_launch_on_boot(safe_name, exe_path, enable)
+        except Exception as e:
+            self.logger.warning(f"Could not set start on boot: {e}")
+
+    def message_box(self, title, message, style=0):
+        """
+        Shows a native message box.
+        Styles: 0=OK, 1=OK/Cancel, 2=Abort/Retry/Ignore, 3=Yes/No/Cancel, 4=Yes/No, 5=Retry/Cancel
+        Returns: 1=OK, 2=Cancel, 6=Yes, 7=No
+        """
+        if self.windows:
+            return self.windows[0].message_box(title, message, style)
+        return 0
+
+    def dialog_save_file(
+        self, title="Save File", default_path=None, default_name=None, file_types=None
+    ):
+        """Opens a native save file dialog. Returns the selected path or None."""
+        if self.windows:
+            return self.windows[0].dialog_save_file(
+                title, default_path, default_name, file_types
+            )
+        return None
+
+    def dialog_open_file(self, title="Open File", default_path=None, file_types=None):
+        """Opens a native file selection dialog. Returns the selected path or None."""
+        if self.windows:
+            return self.windows[0].dialog_open_file(title, default_path, file_types)
+        return None
+
+    def dialog_open_folder(self, title="Select Folder", default_path=None):
+        """Opens a native folder selection dialog. Returns the selected path or None."""
+        if self.windows:
+            return self.windows[0].dialog_open_folder(title, default_path)
+        return None
+
+    def system_notification(self, title: Optional[str] = None, message: str = ""):
+        """Sends a system-level (tray/toast) notification via the OS."""
+        if not title:
+            title = self.config.get("author", self.config.get("title", "Pytron"))
+
+        icon = self.config.get("icon")
+
+        if self.windows:
+            for window in self.windows:
+                try:
+                    window.system_notification(title, message, icon=icon)
+                    break
+                except Exception as e:
+                    self.logger.debug(
+                        f"Failed to send notification via window {window}: {e}"
+                    )
+
+    def copy_to_clipboard(self, text: str):
+        """Copies text to the system clipboard."""
+        if self.windows:
+            return self.windows[0]._platform.set_clipboard_text(text)
+        return False
+
+    def get_clipboard_text(self):
+        """Returns text from the system clipboard."""
+        if self.windows:
+            return self.windows[0]._platform.get_clipboard_text()
+        return None
+
+    def get_system_info(self):
+        """Returns hardware and OS information."""
+        if self.windows:
+            return self.windows[0]._platform.get_system_info()
+
+        # Fallback if no window
+        import platform
+
+        return {"os": platform.system(), "arch": platform.machine()}
+
+    def store_set(self, key: str, value):
+        """Persists a value to the app's local storage."""
+        # Fix recursion: This was incorrectly calling self.store_set instead of the ConfigMixin implementation
+        if hasattr(super(), "store_set"):
+            return super().store_set(key, value)
+        return False
+
+    def store_get(self, key: str, default=None):
+        """Retrieves a persisted value from the app's local storage."""
+        if hasattr(super(), "store_get"):
+            return super().store_get(key, default)
+        return default
+
+    def store_delete(self, key: str):
+        """Removes a persisted value."""
+        if hasattr(super(), "store_delete"):
+            return super().store_delete(key)
+        return False

pytron/apputils/shell.py

@@ -0,0 +1,73 @@
+import os
+import subprocess
+import platform
+
+import shutil
+
+
+class Shell:
+    """
+    Native OS Shell utilities for Pytron.
+    """
+
+    @staticmethod
+    def _resolve_bin(bin_name):
+        return shutil.which(bin_name) or bin_name
+
+    @staticmethod
+    def open_external(url: str):
+        """
+        Opens a URL or file path in the default system browser/handler.
+        """
+        if platform.system() == "Windows":
+            os.startfile(url)
+        elif platform.system() == "Darwin":
+            bin_path = Shell._resolve_bin("open")
+            subprocess.run([bin_path, url])
+        else:
+            bin_path = Shell._resolve_bin("xdg-open")
+            subprocess.run([bin_path, url])
+
+    @staticmethod
+    def show_item_in_folder(path: str):
+        """
+        Opens the folder containing the file and selects it.
+        """
+        path = os.path.abspath(path)
+        if platform.system() == "Windows":
+            bin_path = Shell._resolve_bin("explorer")
+            subprocess.run([bin_path, "/select,", path])
+        elif platform.system() == "Darwin":
+            bin_path = Shell._resolve_bin("open")
+            subprocess.run([bin_path, "-R", path])
+        else:
+            # Linux doesn't have a universal 'select' but we can open the dir
+            bin_path = Shell._resolve_bin("xdg-open")
+            subprocess.run([bin_path, os.path.dirname(path)])
+
+    @staticmethod
+    def trash_item(path: str):
+        """
+        Moves a file to the system trash/recycle bin.
+        Requires 'send2trash' library if available, else fails.
+        """
+        try:
+            import logging
+
+            logger = logging.getLogger("Pytron.Shell")
+            from send2trash import send2trash
+
+            send2trash(path)
+            return True
+        except ImportError:
+            import logging
+
+            logging.getLogger("Pytron.Shell").warning(
+                "send2trash is not installed. File cannot be moved to trash."
+            )
+            return False
+        except Exception as e:
+            import logging
+
+            logging.getLogger("Pytron.Shell").error(f"Failed to trash item: {e}")
+            return False