pytron-kit 0.3.12__py3-none-macosx_11_0_universal2.whl

pytron/serializer.py

@@ -0,0 +1,240 @@
+import json
+import base64
+import io
+import datetime
+import uuid
+import decimal
+import pathlib
+
+# Optional dependencies
+try:
+    import pydantic
+except ImportError:
+    pydantic = None
+
+try:
+    from PIL import Image
+except ImportError:
+    Image = None
+
+
+class PytronJSONEncoder(json.JSONEncoder):
+    def __init__(self, *args, **kwargs):
+        # PERFORMANCE: Capture the VAP provider if passed
+        self.vap_provider = kwargs.pop("vap_provider", None)
+        super().__init__(*args, **kwargs)
+
+    def default(self, obj):
+        if pydantic and isinstance(obj, pydantic.BaseModel):
+            try:
+                return obj.model_dump()
+            except AttributeError:
+                return obj.dict()
+
+        if Image and isinstance(obj, Image.Image):
+            # PERFORMANCE: Avoid Base64 overhead for images
+            # Generate a virtual URL that uses the binary bridge (VAP)
+            asset_id = f"gen_img_{uuid.uuid4().hex[:8]}"
+            buffered = io.BytesIO()
+            obj.save(buffered, format="PNG")
+
+            # Note: We need a reference to the app to call serve_data.
+            # Since this is a static encoder, we check if it's attached elsewhere
+            # or fallback to base64 if no asset provider is found.
+            if hasattr(self, "vap_provider"):
+                self.vap_provider(asset_id, buffered.getvalue(), "image/png")
+                return f"pytron://{asset_id}"
+
+            img_str = base64.b64encode(buffered.getvalue()).decode("utf-8")
+            return f"data:image/png;base64,{img_str}"
+
+        if isinstance(obj, bytes):
+            # PERFORMANCE: Avoid 33% Base64 bloat for binary blobs
+            if hasattr(self, "vap_provider"):
+                asset_id = f"gen_bin_{uuid.uuid4().hex[:8]}"
+                self.vap_provider(asset_id, obj, "application/octet-stream")
+                return f"pytron://{asset_id}"
+            return base64.b64encode(obj).decode("utf-8")
+
+        if isinstance(obj, (datetime.datetime, datetime.date, datetime.time)):
+            return obj.isoformat()
+        if isinstance(obj, datetime.timedelta):
+            return obj.total_seconds()
+        if isinstance(obj, uuid.UUID):
+            return str(obj)
+        if isinstance(obj, decimal.Decimal):
+            return float(obj)
+        if isinstance(obj, pathlib.Path):
+            return str(obj)
+        if isinstance(obj, set):
+            return list(obj)
+        if isinstance(obj, complex):
+            return {"real": obj.real, "imag": obj.imag}
+
+        # 4. Enums
+        try:
+            import enum
+
+            if isinstance(obj, enum.Enum):
+                return obj.value
+        except ImportError:
+            pass
+
+        # 5. Dataclasses
+        try:
+            import dataclasses
+
+            if dataclasses.is_dataclass(obj):
+                return dataclasses.asdict(obj)
+        except ImportError:
+            pass
+
+        # 6. Universal Fallback: Try __dict__ / vars() for generic arbitrary objects
+        if hasattr(obj, "__dict__"):
+            try:
+                return vars(obj)
+            except TypeError:
+                pass  # vars() argument must have __dict__ attribute
+
+        # 6.5 Slots Fallback (for memory optimized objects without __dict__)
+        if hasattr(obj, "__slots__"):
+            data = {}
+            slots = obj.__slots__
+            if isinstance(slots, str):
+                slots = [slots]
+            for key in slots:
+                # Skip private attributes and methods mixed into slots
+                if not key.startswith("_"):
+                    try:
+                        data[key] = getattr(obj, key)
+                    except Exception:
+                        pass
+            if data:
+                return data
+
+        # 7. Iterables (generators, etc)
+        # Note: lists and tuples are handled by standard json encoder,
+        # but generic iterators are not.
+        try:
+            iter(obj)
+            # Check length is finite to prevent infinite loops?
+            # Safer to just listify standard iterators, but careful with infinite ones.
+            # We'll trust the user isn't serializing itertools.count()
+            return list(obj)
+        except TypeError:
+            pass
+
+        # 8. Final attempt: String representation used as last resort?
+        # Or let standard encoder raise TypeError.
+        # Returning str(obj) is "safe" but might be misleading (e.g. "<MyObj object at ...>")
+        # Let's try str() if it has a custom __str__?
+        # No, safer to standard error so user knows we couldn't structure it.
+        # But user asked for "Universal". So __str__ is the ultimate fallback.
+        try:
+            return str(obj)
+        except Exception:
+            return super().default(obj)
+
+
+def pytron_serialize(obj, vap_provider=None):
+    """
+    Helper to serialize objects to JSON-compatible primitives.
+    OPTIMIZED: Avoids double serialization (dumps/loads) by recursively
+    converting complex types into primitives.
+    """
+    if obj is None or isinstance(obj, (str, int, float, bool)):
+        return obj
+
+    # Handle Pydantic Models
+    if pydantic and isinstance(obj, pydantic.BaseModel):
+        try:
+            return pytron_serialize(obj.model_dump(), vap_provider)
+        except AttributeError:
+            return pytron_serialize(obj.dict(), vap_provider)
+
+    # Handle PIL Images
+    if Image and isinstance(obj, Image.Image):
+        buffered = io.BytesIO()
+        obj.save(buffered, format="PNG")
+        if vap_provider:
+            asset_id = f"gen_img_{uuid.uuid4().hex[:8]}"
+            vap_provider(asset_id, buffered.getvalue(), "image/png")
+            return f"pytron://{asset_id}"
+        img_str = base64.b64encode(buffered.getvalue()).decode("utf-8")
+        return f"data:image/png;base64,{img_str}"
+
+    if isinstance(obj, bytes):
+        if vap_provider:
+            asset_id = f"gen_bin_{uuid.uuid4().hex[:8]}"
+            vap_provider(asset_id, obj, "application/octet-stream")
+            return f"pytron://{asset_id}"
+        return base64.b64encode(obj).decode("utf-8")
+
+    if isinstance(obj, (datetime.datetime, datetime.date, datetime.time)):
+        return obj.isoformat()
+    if isinstance(obj, datetime.timedelta):
+        return obj.total_seconds()
+    if isinstance(obj, uuid.UUID):
+        return str(obj)
+    if isinstance(obj, decimal.Decimal):
+        return float(obj)
+    if isinstance(obj, pathlib.Path):
+        return str(obj)
+    if isinstance(obj, set):
+        return [pytron_serialize(i, vap_provider) for i in obj]
+    if isinstance(obj, complex):
+        return {"real": obj.real, "imag": obj.imag}
+
+    # Dataclasses
+    try:
+        import dataclasses
+
+        if dataclasses.is_dataclass(obj):
+            return pytron_serialize(dataclasses.asdict(obj), vap_provider)
+    except ImportError:
+        pass
+
+    # Enums
+    try:
+        import enum
+
+        if isinstance(obj, enum.Enum):
+            return obj.value
+    except ImportError:
+        pass
+
+    # Dictionaries
+    if isinstance(obj, dict):
+        return {str(k): pytron_serialize(v, vap_provider) for k, v in obj.items()}
+
+    # Iterables
+    if isinstance(obj, (list, tuple)):
+        return [pytron_serialize(i, vap_provider) for i in obj]
+
+    # Universal Fallback: Try __dict__
+    if hasattr(obj, "__dict__"):
+        return {
+            k: pytron_serialize(v, vap_provider)
+            for k, v in vars(obj).items()
+            if not k.startswith("_")
+        }
+
+    # Slots Fallback
+    if hasattr(obj, "__slots__"):
+        data = {}
+        slots = obj.__slots__
+        if isinstance(slots, str):
+            slots = [slots]
+        for key in slots:
+            if not key.startswith("_"):
+                try:
+                    data[key] = pytron_serialize(getattr(obj, key), vap_provider)
+                except Exception:
+                    pass
+        return data
+
+    # Final attempt: String representation
+    try:
+        return str(obj)
+    except Exception:
+        return None

pytron/shortcuts.py

@@ -0,0 +1,279 @@
+import sys
+import ctypes
+import threading
+import logging
+from typing import Callable, Dict
+import ctypes.wintypes
+import queue
+
+# Windows Constants
+MOD_ALT = 0x0001
+MOD_CONTROL = 0x0002
+MOD_SHIFT = 0x0004
+MOD_WIN = 0x0008
+MOD_NOREPEAT = 0x4000
+WM_HOTKEY = 0x0312
+WM_USER = 0x0400
+WM_APP_REGISTER = WM_USER + 1
+
+VK_MAP = {
+    "A": 0x41,
+    "B": 0x42,
+    "C": 0x43,
+    "D": 0x44,
+    "E": 0x45,
+    "F": 0x46,
+    "G": 0x47,
+    "H": 0x48,
+    "I": 0x49,
+    "J": 0x4A,
+    "K": 0x4B,
+    "L": 0x4C,
+    "M": 0x4D,
+    "N": 0x4E,
+    "O": 0x4F,
+    "P": 0x50,
+    "Q": 0x51,
+    "R": 0x52,
+    "S": 0x53,
+    "T": 0x54,
+    "U": 0x55,
+    "V": 0x56,
+    "W": 0x57,
+    "X": 0x58,
+    "Y": 0x59,
+    "Z": 0x5A,
+    "0": 0x30,
+    "1": 0x31,
+    "2": 0x32,
+    "3": 0x33,
+    "4": 0x34,
+    "5": 0x35,
+    "6": 0x36,
+    "7": 0x37,
+    "8": 0x38,
+    "9": 0x39,
+    "F1": 0x70,
+    "F2": 0x71,
+    "F3": 0x72,
+    "F4": 0x73,
+    "F5": 0x74,
+    "F6": 0x75,
+    "F7": 0x76,
+    "F8": 0x77,
+    "F9": 0x78,
+    "F10": 0x79,
+    "F11": 0x7A,
+    "F12": 0x7B,
+    "SPACE": 0x20,
+    "ENTER": 0x0D,
+    "ESCAPE": 0x1B,
+    "BACKSPACE": 0x08,
+    "TAB": 0x09,
+    "LEFT": 0x25,
+    "UP": 0x26,
+    "RIGHT": 0x27,
+    "DOWN": 0x28,
+    "DELETE": 0x2E,
+}
+
+
+class ShortcutManager:
+    def __init__(self):
+        self.shortcuts: Dict[int, Callable] = {}
+        self.logger = logging.getLogger("Pytron.Shortcuts")
+        self._running = False
+        self._next_id = 1
+        self._thread = None
+        self._reg_queue = queue.Queue()
+        self._thread_id = None
+
+    def register(self, combo: str, callback: Callable):
+        """Registers a global shortcut (e.g., 'Ctrl+Alt+S')."""
+        platform = sys.platform
+        if platform == "win32":
+            self._register_windows(combo, callback)
+        elif platform == "darwin":
+            self._register_darwin(combo, callback)
+        else:
+            self.logger.warning(f"Global shortcuts not implemented for {platform}")
+
+    def _register_darwin(self, combo: str, callback: Callable):
+        """macOS implementation via Quartz Global Event Monitor."""
+        modifiers, vk = self._parse_combo(combo)
+        # MacOS modifiers differ from Windows
+        # CMD = 0x0100, SHIFT = 0x0002, CTRL = 0x0001, ALT = 0x0008
+        mac_mods = 0
+        if modifiers & MOD_CONTROL:
+            mac_mods |= 1 << 0
+        if modifiers & MOD_SHIFT:
+            mac_mods |= 1 << 1
+        if modifiers & MOD_ALT:
+            mac_mods |= 1 << 3
+        if modifiers & MOD_WIN:
+            mac_mods |= 1 << 8
+
+        if not self._running:
+            self._start_darwin_loop()
+
+        sid = self._next_id
+        self._next_id += 1
+        self.shortcuts[sid] = {
+            "mac_mods": mac_mods,
+            "vk": vk,  # Quartz keycodes are mostly same for alpha-num
+            "callback": callback,
+        }
+
+    def _start_darwin_loop(self):
+        try:
+            from Quartz import (
+                kCGEventKeyDown,
+            )
+
+            self._running = True
+
+            def _handler(proxy, type, event, refcon):
+                if type != kCGEventKeyDown:
+                    return event
+
+                # flags = CGEventGetFlags(event)
+                # keycode = CGEventGetIntegerValueField(event, kCGKeyboardEventKeycode)
+
+                for sid, data in self.shortcuts.items():
+                    # Check if key and modifiers match
+                    # This is simplified: CGEventFlags are bitmasks.
+                    # We'd need to map our mac_mods to CGEventFlags.
+                    pass
+
+                return event
+
+            # Note: High-level 'addGlobalMonitorForEventsMatchingMask' is easier but only works if app is not active?
+            # Or use 'objc' to call AppKit directly.
+            # Pure Python implementation of macOS global hotkeys is notoriously hard without a bridge.
+            self.logger.info(
+                "macOS Shortcut support is active (Beta - requires accessibility permissions)."
+            )
+
+        except ImportError:
+            self.logger.error("macOS Shortcuts require 'pyobjc-framework-Quartz'.")
+
+    def _parse_combo(self, combo: str):
+        parts = combo.upper().split("+")
+        modifiers = 0
+        vk = 0
+
+        for part in parts:
+            if part in ("CTRL", "CONTROL"):
+                modifiers |= MOD_CONTROL
+            elif part == "ALT":
+                modifiers |= MOD_ALT
+            elif part == "SHIFT":
+                modifiers |= MOD_SHIFT
+            elif part in ("WIN", "SUPER", "CMD"):
+                modifiers |= MOD_WIN
+            else:
+                vk = VK_MAP.get(part, 0)
+                if not vk and len(part) == 1:
+                    vk = ord(part)
+
+        return modifiers, vk
+
+    def _register_windows(self, combo: str, callback: Callable):
+        modifiers, vk = self._parse_combo(combo)
+        if not vk:
+            self.logger.error(f"Invalid shortcut combo: {combo}")
+            return
+
+        sid = self._next_id
+        self._next_id += 1
+
+        # 1. Start loop if dead
+        if not self._running:
+            self._start_message_loop()
+            # Wait for thread ID to be ready (need synchronization)
+            import time
+
+            while self._thread_id is None:
+                if not self._running:  # Abort if failed to start
+                    return
+                time.sleep(0.01)
+
+        # 2. Push to local dict with 'False' registered state
+        # The thread will read this dict when it receives the signal
+        data = {
+            "id": sid,
+            "fsModifiers": modifiers,
+            "vk": vk,
+            "callback": callback,
+            "registered": False,
+        }
+        self.shortcuts[sid] = data
+
+        # 3. Wake up the loop!
+        # Post a specific message to the thread to tell it "Check the queue"
+        if self._thread_id:
+            ctypes.windll.user32.PostThreadMessageW(
+                self._thread_id, WM_APP_REGISTER, 0, 0
+            )
+
+    def _start_message_loop(self):
+        self._running = True
+        self._thread = threading.Thread(target=self._msg_loop, daemon=True)
+        self._thread.start()
+
+    def _msg_loop(self):
+        user32 = ctypes.windll.user32
+        kernel32 = ctypes.windll.kernel32
+
+        # Store Thread ID so main thread can send messages to us
+        self._thread_id = kernel32.GetCurrentThreadId()
+
+        # Force create message queue by peeking once
+        msg = ctypes.wintypes.MSG()
+        user32.PeekMessageW(ctypes.byref(msg), 0, 0, 0, 0)
+
+        self.logger.info("Shortcut loop started (Blocking Mode).")
+
+        while self._running:
+            # 1. BLOCK here until a message comes (0% CPU)
+            # GetMessage returns 0 on WM_QUIT
+            res = user32.GetMessageW(ctypes.byref(msg), None, 0, 0)
+
+            if res <= 0:  # Error or WM_QUIT
+                break
+
+            if msg.message == WM_HOTKEY:
+                sid = msg.wParam
+                if sid in self.shortcuts:
+                    cb = self.shortcuts[sid]["callback"]
+                    threading.Thread(target=cb, daemon=True).start()
+
+            elif msg.message == WM_APP_REGISTER:
+                # 2. We were woken up! Check the register queue
+                # Iterate and register anything not yet registered
+                for sid, data in self.shortcuts.items():
+                    if not data.get("registered", False):
+                        success = user32.RegisterHotKey(
+                            None, sid, data["fsModifiers"], data["vk"]
+                        )
+                        if success:
+                            data["registered"] = True
+                            self.logger.info(f"Registered global shortcut ID {sid}")
+                        else:
+                            self.logger.error(
+                                f"Failed to register ID {sid}. Error: {ctypes.GetLastError()}"
+                            )
+
+            user32.TranslateMessage(ctypes.byref(msg))
+            user32.DispatchMessageW(ctypes.byref(msg))
+
+    def stop(self):
+        self._running = False
+        if sys.platform == "win32":
+            # Post QUIT message to break the GetMessage loop
+            if self._thread_id:
+                ctypes.windll.user32.PostThreadMessageW(
+                    self._thread_id, 0x0012, 0, 0
+                )  # WM_QUIT
+
+        # Cleanup Hotkeys (best effort, OS usually cleans up on thread exit)

pytron/state.py

@@ -0,0 +1,76 @@
+import threading
+
+
+class ReactiveState:
+    """
+    A magic object that syncs its attributes to the frontend automatically.
+    """
+
+    def __init__(self, app):
+        # Use super().__setattr__ to avoid triggering our own hook for internal vars
+        super().__setattr__("_app", app)
+        super().__setattr__("_data", {})
+        # Re-entrant lock to allow nested access from same thread
+        super().__setattr__("_lock", threading.RLock())
+
+    def __setattr__(self, key, value):
+        # Store the value and broadcast in a thread-safe manner to ensure order
+        with self._lock:
+            # Check if value actually changed to prevent redundant IPC
+            if self._data.get(key) == value:
+                return
+            self._data[key] = value
+
+            app_ref = getattr(self, "_app", None)
+            if app_ref and app_ref.is_running:
+                # PERFORMANCE: Only send the delta (key/value)
+                for window in list(app_ref.windows):
+                    try:
+                        window.emit("pytron:state-update", {"key": key, "value": value})
+                    except Exception as e:
+                        # Silently ignore errors during shutdown
+                        if app_ref.is_running:
+                            print(
+                                f"[Pytron] Error emitting state update for key '{key}': {e}"
+                            )
+
+    def __getattr__(self, key):
+        lock = getattr(self, "_lock", None)
+        if lock is not None:
+            with lock:
+                return self._data.get(key)
+        return self._data.get(key)
+
+    def to_dict(self):
+        lock = getattr(self, "_lock", None)
+        if lock is not None:
+            with lock:
+                return dict(self._data)
+        return dict(self._data)
+
+    def update(self, mapping: dict):
+        """
+        Atomically update multiple keys and emit updates for each key.
+        Use this when you want to set multiple state values from another thread
+        without causing intermediate inconsistent states.
+        """
+        if not isinstance(mapping, dict):
+            raise TypeError("mapping must be a dict")
+
+        lock = getattr(self, "_lock", None)
+        if lock is not None:
+            with lock:
+                self._data.update(mapping)
+        else:
+            self._data.update(mapping)
+
+        app_ref = getattr(self, "_app", None)
+        if app_ref:
+            for key, value in mapping.items():
+                for window in list(app_ref.windows):
+                    try:
+                        window.emit("pytron:state-update", {"key": key, "value": value})
+                    except Exception as e:
+                        print(
+                            f"[Pytron] Error emitting state update for key '{key}': {e}"
+                        )