qyro-engine 1.0.0a1__py3-none-any.whl

qyro/__init__.py

@@ -0,0 +1,71 @@
+"""
+Qyro.
+Clean Architecture runtime engine and lifecycle framework for Python desktop GUI apps.
+Decoupled from CLI tools, independent and multi-toolkit ready.
+"""
+
+from qyro.client.context import ApplicationContext
+from qyro.client.component import Component
+from qyro.container import EngineContainer
+from qyro.adapters.platform.detector import PlatformDetector
+from qyro.domain.entities import PlatformType, ExecutionMode, AppMetadata
+from qyro.domain.errors import (
+    QyroEngineError,
+    ResourceNotFoundError,
+    SettingsNotFoundError,
+    FrameworkNotAvailableError,
+)
+
+__version__ = "0.1.0"
+
+# Module-level singleton container for quick procedural usage
+_default_container: EngineContainer | None = None
+
+
+def _get_default_container() -> EngineContainer:
+    global _default_container
+    app_container = ApplicationContext._global_container
+    if app_container is not None:
+        _default_container = app_container
+        return app_container
+
+    if _default_container is None:
+        _default_container = EngineContainer()
+    return _default_container
+
+
+def get_resource(*segments: str, required: bool = True) -> str:
+    """Convenience helper to resolve resource path without manually creating ApplicationContext."""
+    container = _get_default_container()
+    return str(container.resolve_resource_use_case.execute(*segments, required=required))
+
+
+def load_build_settings() -> dict:
+    """Convenience helper to load build settings dictionary."""
+    container = _get_default_container()
+    return container.load_settings_use_case.execute().raw_settings
+
+
+def is_frozen() -> bool:
+    """Convenience helper to check if running in a frozen executable."""
+    container = _get_default_container()
+    return container.env_adapter.is_frozen()
+
+
+
+__all__ = [
+    "ApplicationContext",
+    "Component",
+    "EngineContainer",
+    "PlatformDetector",
+    "PlatformType",
+    "ExecutionMode",
+    "AppMetadata",
+    "QyroEngineError",
+    "ResourceNotFoundError",
+    "SettingsNotFoundError",
+    "FrameworkNotAvailableError",
+    "get_resource",
+    "load_build_settings",
+    "is_frozen",
+]

qyro/adapters/__init__.py

@@ -0,0 +1,22 @@
+"""
+Qyro - Adapters Layer.
+Concrete implementations of application ports.
+"""
+
+from .environment.system_environment import SystemEnvironmentAdapter
+from .settings.json_settings import JsonSettingsAdapter
+from .resources.filesystem_resources import FileSystemResourceAdapter
+from .telemetry.console_hook import ConsoleExceptionHookAdapter
+from .telemetry.sentry_hook import SentryExceptionHookAdapter
+from .platform.detector import PlatformDetector
+from .frameworks.factory import FrameworkFactory
+
+__all__ = [
+    "SystemEnvironmentAdapter",
+    "JsonSettingsAdapter",
+    "FileSystemResourceAdapter",
+    "ConsoleExceptionHookAdapter",
+    "SentryExceptionHookAdapter",
+    "PlatformDetector",
+    "FrameworkFactory",
+]

qyro/adapters/environment/__init__.py

@@ -0,0 +1,3 @@
+from .system_environment import SystemEnvironmentAdapter
+
+__all__ = ["SystemEnvironmentAdapter"]

qyro/adapters/environment/system_environment.py

@@ -0,0 +1,57 @@
+"""
+System Environment Adapter.
+Implements IEnvironmentPort for PyInstaller, cx_Freeze, and Source environments.
+"""
+
+import sys
+from pathlib import Path
+from qyro.application.ports.environment import IEnvironmentPort
+from qyro.domain.entities import ExecutionMode, PlatformType
+from qyro.adapters.platform.detector import PlatformDetector
+
+
+class SystemEnvironmentAdapter(IEnvironmentPort):
+    """Detects runtime execution specifics across operating systems."""
+
+    def __init__(self, custom_root: Path | None = None) -> None:
+        self._custom_root = custom_root
+
+    def is_frozen(self) -> bool:
+        return getattr(sys, "frozen", False)
+
+    def get_execution_mode(self) -> ExecutionMode:
+        if self.is_frozen():
+            if hasattr(sys, "_MEIPASS"):
+                return ExecutionMode.FROZEN_PYINSTALLER
+            return ExecutionMode.FROZEN_GENERIC
+        return ExecutionMode.SOURCE
+
+    def get_platform(self) -> PlatformType:
+        return PlatformDetector.get_platform()
+
+    def get_root_dir(self) -> Path:
+        if self._custom_root:
+            return self._custom_root
+
+        if self.is_frozen():
+            # Executable directory
+            return Path(sys.executable).resolve().parent
+
+        # Source mode: find project root containing pyproject.toml or src/
+        cwd = Path.cwd()
+        for parent in [cwd] + list(cwd.parents):
+            if (parent / "pyproject.toml").exists() or (parent / "src").exists():
+                return parent
+        return cwd
+
+    def get_bundle_dir(self) -> Path:
+        if self.is_frozen() and hasattr(sys, "_MEIPASS"):
+            return Path(getattr(sys, "_MEIPASS")).resolve()
+
+        # macOS bundle check
+        if self.is_frozen() and sys.platform == "darwin":
+            mac_resources = Path(sys.executable).resolve().parent.parent / "Resources"
+            if mac_resources.exists():
+                return mac_resources
+
+        return self.get_root_dir()

qyro/adapters/frameworks/__init__.py

@@ -0,0 +1,21 @@
+from .base import BaseUIFrameworkAdapter
+from .qt_base import BaseQtAdapter
+from .pyside6_adapter import PySide6Adapter
+from .pyqt6_adapter import PyQt6Adapter
+from .pyside2_adapter import PySide2Adapter
+from .pyqt5_adapter import PyQt5Adapter
+from .kivy_adapter import KivyAdapter
+from .tkinter_adapter import TkinterAdapter
+from .factory import FrameworkFactory
+
+__all__ = [
+    "BaseUIFrameworkAdapter",
+    "BaseQtAdapter",
+    "PySide6Adapter",
+    "PyQt6Adapter",
+    "PySide2Adapter",
+    "PyQt5Adapter",
+    "KivyAdapter",
+    "TkinterAdapter",
+    "FrameworkFactory",
+]

qyro/adapters/frameworks/base.py

@@ -0,0 +1,20 @@
+"""
+Base UI Framework Adapter.
+Common abstract implementation for GUI toolkits.
+"""
+
+from abc import abstractmethod
+from typing import Any, List, Optional
+from qyro.application.ports.ui_framework import IUIFrameworkPort
+
+
+class BaseUIFrameworkAdapter(IUIFrameworkPort):
+    """Base framework adapter storing app reference and lifecycle state."""
+
+    def __init__(self) -> None:
+        self._app: Any = None
+        self._is_running: bool = False
+
+    @property
+    def app_instance(self) -> Any:
+        return self._app

qyro/adapters/frameworks/factory.py

@@ -0,0 +1,62 @@
+"""
+Framework Factory.
+Detects available UI toolkits or instantiates the user's requested engine backend.
+"""
+
+from typing import Optional
+from qyro.application.ports.ui_framework import IUIFrameworkPort
+from qyro.domain.errors import FrameworkNotAvailableError
+from .pyside6_adapter import PySide6Adapter
+from .pyqt6_adapter import PyQt6Adapter
+from .pyside2_adapter import PySide2Adapter
+from .pyqt5_adapter import PyQt5Adapter
+from .kivy_adapter import KivyAdapter
+from .tkinter_adapter import TkinterAdapter
+from .headless_adapter import HeadlessAdapter
+
+
+class FrameworkFactory:
+    """Instantiates framework adapters based on preference or automatic detection."""
+
+    _FRAMEWORK_REGISTRY = {
+        "pyside6": PySide6Adapter,
+        "pyqt6": PyQt6Adapter,
+        "pyside2": PySide2Adapter,
+        "pyqt5": PyQt5Adapter,
+        "kivy": KivyAdapter,
+        "tkinter": TkinterAdapter,
+        "headless": HeadlessAdapter,
+    }
+
+    @classmethod
+    def create(cls, name: Optional[str] = None) -> IUIFrameworkPort:
+        if name:
+            normalized = name.strip().lower()
+            adapter_cls = cls._FRAMEWORK_REGISTRY.get(normalized)
+            if not adapter_cls:
+                raise FrameworkNotAvailableError(
+                    name,
+                    f"Supported frameworks: {', '.join(cls._FRAMEWORK_REGISTRY.keys())}"
+                )
+            adapter = adapter_cls()
+            if not adapter.is_available():
+                raise FrameworkNotAvailableError(adapter.framework_name)
+            return adapter
+
+        # Auto-detect in order of preference
+        preference = [
+            PySide6Adapter,
+            PyQt6Adapter,
+            PySide2Adapter,
+            PyQt5Adapter,
+            KivyAdapter,
+            TkinterAdapter,
+            HeadlessAdapter,
+        ]
+        for candidate_cls in preference:
+            candidate = candidate_cls()
+            if candidate.is_available():
+                return candidate
+
+        return HeadlessAdapter()
+

qyro/adapters/frameworks/headless_adapter.py

@@ -0,0 +1,57 @@
+"""
+Headless Framework Adapter for CI, tests, and headless environments.
+"""
+
+from typing import Any, List, Optional
+from qyro.application.ports.ui_framework import IUIFrameworkPort
+
+
+class HeadlessApplication:
+    """Mock GUI application instance for headless environments."""
+
+    def __init__(self, argv: Optional[List[str]] = None) -> None:
+        self.argv = argv or []
+
+    def exec(self) -> int:
+        return 0
+
+    def exec_(self) -> int:
+        return 0
+
+
+class HeadlessAdapter(IUIFrameworkPort):
+    """Fallback adapter when running in headless mode or without GUI libraries installed."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.applied_app_icon: Optional[str] = None
+        self.applied_window_icons: dict = {}
+        self.applied_window_titles: dict = {}
+
+    @property
+    def framework_name(self) -> str:
+        return "Headless"
+
+    def is_available(self) -> bool:
+        return True
+
+    def create_application(self, argv: Optional[List[str]] = None) -> Any:
+        return HeadlessApplication(argv)
+
+    def run(self) -> int:
+        return 0
+
+    def exit(self, code: int = 0) -> None:
+        pass
+
+    def set_application_icon(self, icon_path: str) -> bool:
+        self.applied_app_icon = icon_path
+        return True
+
+    def set_window_icon(self, window: Any, icon_path: str) -> bool:
+        self.applied_window_icons[window] = icon_path
+        return True
+
+    def set_window_title(self, window: Any, title: str) -> bool:
+        self.applied_window_titles[window] = title
+        return True

qyro/adapters/frameworks/kivy_adapter.py

@@ -0,0 +1,79 @@
+"""
+Kivy and Tkinter Framework Adapters for Qyro.
+Supports cross-platform desktop/mobile (Kivy) and lightweight builtin (Tkinter) runtimes.
+"""
+
+import sys
+from typing import Any, List, Optional
+from .base import BaseUIFrameworkAdapter
+
+
+class KivyAdapter(BaseUIFrameworkAdapter):
+    """Kivy toolkit adapter for multi-touch and mobile/desktop apps."""
+
+    @property
+    def framework_name(self) -> str:
+        return "Kivy"
+
+    def is_available(self) -> bool:
+        try:
+            import kivy  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def create_application(self, argv: Optional[List[str]] = None) -> Any:
+        try:
+            from kivy.app import App
+            running = App.get_running_app()
+            if running:
+                self._app = running
+                return self._app
+        except Exception:
+            pass
+        return None
+
+    def run(self) -> int:
+        if not self._app:
+            try:
+                from kivy.app import App
+                self._app = App.get_running_app()
+            except Exception:
+                pass
+        if not self._app:
+            from kivy.app import App
+
+            class GenericKivyApp(App):
+                pass
+
+            self._app = GenericKivyApp()
+
+        self._is_running = True
+        self._app.run()
+        return 0
+
+    def exit(self, code: int = 0) -> None:
+        if self._app and hasattr(self._app, "stop"):
+            self._app.stop()
+        self._is_running = False
+
+    def set_application_icon(self, icon_path: str) -> bool:
+        if self._app and hasattr(self._app, "icon"):
+            self._app.icon = icon_path
+            return True
+        return False
+
+    def set_window_icon(self, window: Any, icon_path: str) -> bool:
+        if window and hasattr(window, "icon"):
+            window.icon = icon_path
+            return True
+        return self.set_application_icon(icon_path)
+
+    def set_window_title(self, window: Any, title: str) -> bool:
+        if window and hasattr(window, "title"):
+            window.title = title
+            return True
+        if self._app and hasattr(self._app, "title"):
+            self._app.title = title
+            return True
+        return False

qyro/adapters/frameworks/pyqt5_adapter.py

@@ -0,0 +1,23 @@
+from .qt_base import BaseQtAdapter
+
+
+class PyQt5Adapter(BaseQtAdapter):
+    """PyQt5 toolkit adapter for Qt 5."""
+
+    def __init__(self) -> None:
+        qapp = None
+        if self.is_available():
+            from PyQt5.QtWidgets import QApplication
+            qapp = QApplication
+        super().__init__(qapp_class=qapp, is_qt6=False)
+
+    @property
+    def framework_name(self) -> str:
+        return "PyQt5"
+
+    def is_available(self) -> bool:
+        try:
+            import PyQt5.QtWidgets  # noqa: F401
+            return True
+        except ImportError:
+            return False

qyro/adapters/frameworks/pyqt6_adapter.py

@@ -0,0 +1,35 @@
+"""
+PyQt6 Adapter.
+Riverbank PyQt6 binding implementation for Qyro.
+"""
+
+from typing import Any, List, Optional
+from .qt_base import BaseQtAdapter
+
+
+class PyQt6Adapter(BaseQtAdapter):
+    """PyQt6 toolkit adapter."""
+
+    def __init__(self) -> None:
+        qapp = None
+        if self.is_available():
+            from PyQt6.QtWidgets import QApplication
+            qapp = QApplication
+        super().__init__(qapp_class=qapp, is_qt6=True)
+
+    @property
+    def framework_name(self) -> str:
+        return "PyQt6"
+
+    def is_available(self) -> bool:
+        try:
+            import PyQt6.QtWidgets  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def create_application(self, argv: Optional[List[str]] = None) -> Any:
+        if not self._qapp_class and self.is_available():
+            from PyQt6.QtWidgets import QApplication
+            self._qapp_class = QApplication
+        return super().create_application(argv)

qyro/adapters/frameworks/pyside2_adapter.py

@@ -0,0 +1,28 @@
+"""
+PySide2 and PyQt5 Legacy Adapters for Qt 5.
+"""
+
+from .qt_base import BaseQtAdapter
+
+
+class PySide2Adapter(BaseQtAdapter):
+    """PySide2 toolkit adapter for Qt 5."""
+
+    def __init__(self) -> None:
+        qapp = None
+        if self.is_available():
+            from PySide2.QtWidgets import QApplication
+            qapp = QApplication
+        super().__init__(qapp_class=qapp, is_qt6=False)
+
+    @property
+    def framework_name(self) -> str:
+        return "PySide2"
+
+    def is_available(self) -> bool:
+        try:
+            import PySide2.QtWidgets  # noqa: F401
+            return True
+        except ImportError:
+            return False
+

qyro/adapters/frameworks/pyside6_adapter.py

@@ -0,0 +1,35 @@
+"""
+PySide6 Adapter.
+Official Qt 6 binding implementation for Qyro.
+"""
+
+from typing import Any, List, Optional
+from .qt_base import BaseQtAdapter
+
+
+class PySide6Adapter(BaseQtAdapter):
+    """PySide6 toolkit adapter."""
+
+    def __init__(self) -> None:
+        qapp = None
+        if self.is_available():
+            from PySide6.QtWidgets import QApplication
+            qapp = QApplication
+        super().__init__(qapp_class=qapp, is_qt6=True)
+
+    @property
+    def framework_name(self) -> str:
+        return "PySide6"
+
+    def is_available(self) -> bool:
+        try:
+            import PySide6.QtWidgets  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def create_application(self, argv: Optional[List[str]] = None) -> Any:
+        if not self._qapp_class and self.is_available():
+            from PySide6.QtWidgets import QApplication
+            self._qapp_class = QApplication
+        return super().create_application(argv)

qyro/adapters/frameworks/qt_base.py

@@ -0,0 +1,107 @@
+"""
+Base Qt Adapter for PySide and PyQt bindings.
+Encapsulates common QApplication creation, high-DPI attributes, and event loop execution.
+"""
+
+import sys
+from typing import Any, List, Optional
+from .base import BaseUIFrameworkAdapter
+
+
+class BaseQtAdapter(BaseUIFrameworkAdapter):
+    """Shared implementation details across PyQt and PySide versions."""
+
+    def __init__(self, qapp_class: Any, is_qt6: bool = True) -> None:
+        super().__init__()
+        self._qapp_class = qapp_class
+        self._is_qt6 = is_qt6
+
+    def create_application(self, argv: Optional[List[str]] = None) -> Any:
+        if self._qapp_class.instance():
+            self._app = self._qapp_class.instance()
+            return self._app
+
+        args = argv if argv is not None else sys.argv
+        self._app = self._qapp_class(args)
+        return self._app
+
+    def run(self) -> int:
+        if not self._app:
+            self.create_application()
+
+        self._is_running = True
+        # Qt 6 uses app.exec(), Qt 5 used app.exec_()
+        if hasattr(self._app, "exec"):
+            return self._app.exec()
+        return self._app.exec_()
+
+    def exit(self, code: int = 0) -> None:
+        if self._app:
+            self._app.exit(code)
+        self._is_running = False
+
+    @property
+    def binding_package(self) -> str:
+        """Determines the exact Qt package name associated with this adapter instance."""
+        if self._qapp_class and hasattr(self._qapp_class, "__module__"):
+            return self._qapp_class.__module__.split(".")[0]
+        return self.framework_name
+
+    def _create_qicon(self, icon_path: str, target: Optional[Any] = None) -> Optional[Any]:
+        """
+        Dynamically imports QIcon strictly from the adapter's matching Qt binding.
+        Avoids cross-importing other installed Qt bindings (e.g. PySide6 when running PyQt5),
+        which causes macOS duplicate symbol warnings, QPixmap crashes, and SIGABRT.
+        """
+        pkg = None
+        if target is not None:
+            for cls in getattr(type(target), "__mro__", []):
+                mod = getattr(cls, "__module__", "")
+                if mod:
+                    root = mod.split(".")[0]
+                    if root in ("PyQt5", "PySide6", "PyQt6", "PySide2"):
+                        pkg = root
+                        break
+
+        if not pkg:
+            pkg = self.binding_package
+
+        if pkg:
+            try:
+                mod = __import__(f"{pkg}.QtGui", fromlist=["QIcon"])
+                QIcon = getattr(mod, "QIcon", None)
+                if QIcon:
+                    return QIcon(icon_path)
+            except Exception:
+                pass
+        return None
+
+    def set_application_icon(self, icon_path: str) -> bool:
+        if not self._app:
+            return False
+        qicon = self._create_qicon(icon_path, target=self._app)
+        if qicon and hasattr(self._app, "setWindowIcon"):
+            self._app.setWindowIcon(qicon)
+            return True
+        return False
+
+    def set_window_icon(self, window: Any, icon_path: str) -> bool:
+        if not window:
+            return False
+        qicon = self._create_qicon(icon_path, target=window)
+        if qicon and hasattr(window, "setWindowIcon"):
+            try:
+                window.setWindowIcon(qicon)
+                return True
+            except (RuntimeError, Exception):
+                return False
+        return False
+
+    def set_window_title(self, window: Any, title: str) -> bool:
+        if window and hasattr(window, "setWindowTitle"):
+            try:
+                window.setWindowTitle(title)
+                return True
+            except (RuntimeError, Exception):
+                return False
+        return False