pydux-store 0.1.0__py3-none-any.whl

pydux/__init__.py

@@ -0,0 +1,69 @@
+"""
+PyDux 3.0 — UI-Agnostic State Management for Python Desktop Applications.
+Supports modern Redux Toolkit style (create_slice, configure_store, create_async_thunk)
+with memoized selectors, zero redundant re-renders, and full Qyro/PySide/Tkinter/Kivy support.
+"""
+
+# Redux Toolkit style modern API
+from pydux.toolkit.slice import create_slice, Slice
+from pydux.toolkit.configure_store import configure_store, combine_reducers
+from pydux.toolkit.hot_reload import reconfigure_store
+from pydux.toolkit.async_thunk import create_async_thunk, create_thunk_middleware
+
+# Core Store & Selectors
+from pydux.core.store import Store
+from pydux.core.selector import create_selector, shallow_equal, deep_equal, is_identical
+from pydux.core.types import Action, Reducer, Selector, Middleware, Dispatch
+
+# DevTools & Time-Travel
+from pydux.devtools.tracker import PyDuxDevTools, devtools_middleware
+from pydux.devtools.inspector import PyDuxInspectorServer, start_inspector
+
+# UI Adapters & Framework Bridges
+from pydux.adapters.base import MainThreadBridge, ReactiveBinding, connect
+from pydux.adapters.qyro import Reactive, connect_qyro
+try:  # Optional: importing Pydux core does not require PSX.
+    from pydux.adapters.psx import StoreProvider, use_dispatch, use_selector
+except ModuleNotFoundError as exc:  # pragma: no cover - depends on installation extras
+    if exc.name != "psx":
+        raise
+
+__version__ = "3.0.0"
+__all__ = [
+    # Redux Toolkit API
+    "create_slice",
+    "configure_store",
+    "create_async_thunk",
+    "create_thunk_middleware",
+    "combine_reducers",
+    "reconfigure_store",
+    "Slice",
+
+    # Core Store & Selectors
+    "Store",
+    "create_selector",
+    "shallow_equal",
+    "deep_equal",
+    "is_identical",
+    "Action",
+    "Reducer",
+    "Selector",
+    "Middleware",
+    "Dispatch",
+
+    # DevTools
+    "PyDuxDevTools",
+    "devtools_middleware",
+    "PyDuxInspectorServer",
+    "start_inspector",
+
+    # Adapters
+    "MainThreadBridge",
+    "ReactiveBinding",
+    "connect",
+    "Reactive",
+    "connect_qyro",
+]
+
+if "StoreProvider" in globals():
+    __all__ += ["StoreProvider", "use_dispatch", "use_selector"]

pydux/adapters/base.py

@@ -0,0 +1,113 @@
+"""
+UI-Agnostic Reactive Binding & Thread Dispatcher.
+Decouples PyDux from any concrete GUI library while providing
+rock-solid main thread synchronization.
+"""
+
+from typing import (
+    Callable,
+    Any,
+    Optional,
+    Protocol,
+    TypeVar,
+    Dict,
+)
+from pydux.core.store import Store
+from pydux.core.types import Selector, Unsubscribe, EqualityFn
+
+T = TypeVar("T")
+
+
+class MainThreadBridge(Protocol):
+    """
+    Protocol to safely schedule a callable onto the GUI's main thread.
+    Required by desktop frameworks (Qt, Tkinter, Kivy) to avoid threading crashes.
+    """
+
+    def schedule_on_main_thread(self, fn: Callable[[], None]) -> None:
+        ...
+
+
+class DirectThreadBridge:
+    """Default fallback bridge for pure synchronous execution or tests."""
+
+    def schedule_on_main_thread(self, fn: Callable[[], None]) -> None:
+        fn()
+
+
+class ReactiveBinding:
+    """
+    Connects a specific PyDux selector to any widget setter or callback.
+    Automatically handles main-thread dispatching.
+    
+    Example:
+        ReactiveBinding(
+            store=store,
+            selector=lambda s: s["user"]["name"],
+            target=lambda name: label.config(text=name),
+            bridge=TkinterBridge(root)
+        )
+    """
+
+    def __init__(
+        self,
+        store: Store[Any],
+        selector: Selector[Any, T],
+        target: Callable[[T], None],
+        equality_fn: Optional[EqualityFn] = None,
+        bridge: Optional[MainThreadBridge] = None,
+    ):
+        self._bridge = bridge or DirectThreadBridge()
+        self._target = target
+
+        def safe_listener(value: T):
+            self._bridge.schedule_on_main_thread(lambda: self._target(value))
+
+        self._unsubscribe = store.select(
+            selector=selector,
+            listener=safe_listener,
+            equality_fn=equality_fn,
+            fire_immediately=True,
+        )
+
+    def dispose(self) -> None:
+        """Tears down the subscription."""
+        if self._unsubscribe:
+            self._unsubscribe()
+            self._unsubscribe = None
+
+
+def connect(
+    store: Store[Any],
+    map_state_to_props: Optional[Callable[[Any], Dict[str, Any]]] = None,
+    bridge: Optional[MainThreadBridge] = None,
+):
+    """
+    Class decorator for framework-agnostic component state injection.
+    """
+    def decorator(cls):
+        orig_init = cls.__init__
+
+        def new_init(self, *args, **kwargs):
+            orig_init(self, *args, **kwargs)
+            self._pydux_unsubscribers = []
+            active_bridge = bridge or getattr(self, "_pydux_bridge", DirectThreadBridge())
+
+            if map_state_to_props:
+                def on_state_slice(props: Dict[str, Any]):
+                    for prop_name, prop_val in props.items():
+                        setattr(self, prop_name, prop_val)
+                    if hasattr(self, "on_props_changed") and callable(self.on_props_changed):
+                        self.on_props_changed()
+
+                unsub = store.select(
+                    selector=map_state_to_props,
+                    listener=lambda p: active_bridge.schedule_on_main_thread(lambda: on_state_slice(p)),
+                    fire_immediately=True,
+                )
+                self._pydux_unsubscribers.append(unsub)
+
+        cls.__init__ = new_init
+        return cls
+
+    return decorator

pydux/adapters/kivy.py

@@ -0,0 +1,24 @@
+"""
+Kivy Adapter for PyDux 3.0.
+Schedules state updates via Kivy's Clock.schedule_once.
+"""
+
+from typing import Callable, Any
+from pydux.adapters.base import MainThreadBridge
+
+
+class KivyBridge:
+    """Ensures Kivy widgets and canvas instructions update on the Kivy Clock loop."""
+
+    def __init__(self):
+        try:
+            from kivy.clock import Clock
+            self._clock = Clock
+        except ImportError:
+            self._clock = None
+
+    def schedule_on_main_thread(self, fn: Callable[[], None]) -> None:
+        if self._clock:
+            self._clock.schedule_once(lambda dt: fn(), 0)
+        else:
+            fn()

pydux/adapters/psx.py

@@ -0,0 +1,97 @@
+"""Optional Pydux state hooks for declarative PSX component trees."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+from psx import component
+from psx.core.errors import PSXError
+from psx.core.hooks import provide_context, use_context, use_effect, use_state
+from psx.core.vnode import VNode
+
+TState = TypeVar("TState")
+TSelected = TypeVar("TSelected")
+_STORE_CONTEXT = object()
+
+
+def StoreProvider(store: object, child: VNode) -> VNode:
+    """Provide exactly one existing Pydux store to a PSX subtree."""
+    _validate_store(store)
+    return _StoreProvider(child, store=store)
+
+
+@component
+def _StoreProvider(store: object, children: tuple[object, ...]) -> VNode:
+    provide_context(_STORE_CONTEXT, store)
+    use_effect(lambda: _lease_inspector(store), [store])
+    if len(children) != 1 or not isinstance(children[0], VNode):
+        raise TypeError("StoreProvider requires exactly one VNode child.")
+    return children[0]
+
+
+def use_dispatch() -> Callable[[object], object]:
+    """Return the dispatch method of the nearest explicit StoreProvider."""
+    store = _store_from_context()
+    return cast(Callable[[object], object], getattr(store, "dispatch"))
+
+
+def use_selector(
+    selector: Callable[[TState], TSelected],
+    equality_fn: Callable[[TSelected, TSelected], bool] | None = None,
+) -> TSelected:
+    """Subscribe the current PSX component to a selected Pydux slice."""
+    store = _store_from_context()
+    initial = selector(cast(TState, store.get_state()))
+    selected, set_selected = use_state(lambda: initial)
+
+    def subscribe() -> Callable[[], None]:
+        def on_change(value: TSelected) -> None:
+            set_selected(value)
+
+        return store.select(
+            selector=selector,
+            listener=on_change,
+            equality_fn=equality_fn,
+            fire_immediately=True,
+        )
+
+    use_effect(subscribe, [store, selector, equality_fn])
+    return cast(TSelected, selected)
+
+
+def _store_from_context() -> Any:
+    try:
+        store = use_context(_STORE_CONTEXT)
+    except LookupError as exc:
+        raise PSXError("use_selector() and use_dispatch() require an ancestor StoreProvider.") from exc
+    _validate_store(store)
+    return store
+
+
+def _validate_store(store: object) -> None:
+    required = ("get_state", "dispatch", "select")
+    missing = [name for name in required if not callable(getattr(store, name, None))]
+    if missing:
+        raise TypeError(f"StoreProvider expected a Pydux-compatible store; missing {', '.join(missing)}.")
+
+
+def _lease_inspector(store: object) -> Callable[[], None]:
+    """Stop an auto-started inspector after its last provider unmounts."""
+    leases = int(getattr(store, "_pydux_psx_inspector_leases", 0)) + 1
+    setattr(store, "_pydux_psx_inspector_leases", leases)
+
+    def release() -> None:
+        remaining = max(0, int(getattr(store, "_pydux_psx_inspector_leases", 1)) - 1)
+        setattr(store, "_pydux_psx_inspector_leases", remaining)
+        if remaining:
+            return
+        inspector = getattr(store, "inspector", None)
+        stop = getattr(inspector, "stop", None)
+        if callable(stop):
+            stop()
+
+    return release
+
+
+__all__ = ["StoreProvider", "use_dispatch", "use_selector"]

pydux/adapters/qt.py

@@ -0,0 +1,29 @@
+"""
+Qt Adapter for PySide6, PySide2, PyQt5, and PyQt6.
+Uses Qt MetaObject and QTimer.singleShot safely on the Qt event loop,
+without locking PyDux core to Qt dependencies.
+"""
+
+from typing import Callable, Any, Optional
+from pydux.adapters.base import MainThreadBridge
+
+
+class QtMainThreadBridge:
+    """Dispatches calls onto the Qt GUI event loop safely."""
+
+    def __init__(self):
+        # Auto-detect Qt binding
+        self._qtimer = None
+        for mod_name in ("PySide6.QtCore", "PyQt6.QtCore", "PySide2.QtCore", "PyQt5.QtCore"):
+            try:
+                mod = __import__(mod_name, fromlist=["QTimer"])
+                self._qtimer = getattr(mod, "QTimer")
+                break
+            except ImportError:
+                continue
+
+    def schedule_on_main_thread(self, fn: Callable[[], None]) -> None:
+        if self._qtimer:
+            self._qtimer.singleShot(0, fn)
+        else:
+            fn()

pydux/adapters/qyro.py

@@ -0,0 +1,227 @@
+"""
+Qyro Framework Adapter for PyDux 3.0.
+Works seamlessly with qyro.ui.component.Component and qyro.ApplicationContext.
+Automatically handles subscription on mount and unsubscription on unmount!
+"""
+
+import sys
+import logging
+from typing import Callable, Any, Optional, Dict, List
+from pydux.core.store import Store
+from pydux.core.types import Selector, EqualityFn, Unsubscribe
+
+
+def _is_kivy_widget(component: Any) -> bool:
+    """Return whether a component is running inside an already-loaded Kivy app."""
+    # Do not import Kivy merely to identify another UI framework: its import
+    # initializes Kivy's logger and window providers inside Qt applications.
+    if not any(name == "kivy" or name.startswith("kivy.") for name in sys.modules):
+        return False
+
+    try:
+        from kivy.uix.widget import Widget  # type: ignore
+
+        return isinstance(component, Widget)
+    except Exception:
+        return False
+
+
+def _get_qt_single_shot() -> Optional[Callable[[int, Callable[[], None]], None]]:
+    """Resolve QTimer.singleShot from the active Qt binding, if available."""
+    for module_name in ("PySide6.QtCore", "PyQt6.QtCore", "PySide2.QtCore", "PyQt5.QtCore"):
+        module = sys.modules.get(module_name)
+
+        if module is None:
+            try:
+                module = __import__(module_name, fromlist=["QTimer"])
+            except ImportError:
+                continue
+
+        qtimer = getattr(module, "QTimer", None)
+        if qtimer is not None and hasattr(qtimer, "singleShot"):
+            return qtimer.singleShot
+
+    return None
+
+
+def _schedule_on_ui_tick(component: Any, fn: Callable[[], None]) -> bool:
+    """Schedule callback on the active UI framework tick (Qt, Tkinter, or Kivy)."""
+    # Kivy applications can be installed alongside a Qt binding. Detect a
+    # real Kivy widget before probing Qt so updates stay on Kivy's event loop.
+    if _is_kivy_widget(component):
+        try:
+            from kivy.clock import Clock  # type: ignore
+
+            Clock.schedule_once(lambda _dt: fn(), 0)
+            return True
+        except Exception:
+            return False
+
+    # Tk widgets expose ``after``. Check this before probing/importing Qt:
+    # environments used for Qyro demos commonly include PySide6 as well, and
+    # a QTimer without a Qt event loop can crash at Tk's native teardown.
+    tk_after = getattr(component, "after", None)
+    if callable(tk_after):
+        tk_after(0, fn)
+        return True
+
+    single_shot = _get_qt_single_shot()
+    if single_shot is not None:
+        single_shot(0, fn)
+        return True
+
+    return False
+
+
+def _select_with_deferred_initial(
+    component: Any,
+    store: Store[Any],
+    selector: Selector[Any, Any],
+    on_change: Callable[[Any], None],
+    equality_fn: Optional[EqualityFn] = None,
+) -> Unsubscribe:
+    """Subscribe without immediate fire and dispatch initial value in the UI tick."""
+    delivered = {"called": False}
+
+    def tracked_on_change(value: Any) -> None:
+        delivered["called"] = True
+        on_change(value)
+
+    unsub = store.select(
+        selector=selector,
+        listener=tracked_on_change,
+        equality_fn=equality_fn,
+        fire_immediately=False,
+    )
+
+    def emit_initial_value() -> None:
+        if delivered["called"]:
+            return
+
+        try:
+            tracked_on_change(selector(store.get_state()))
+        except Exception:
+            logging.getLogger("pydux").exception(
+                "Error while dispatching initial Qyro selector value"
+            )
+
+    if _schedule_on_ui_tick(component, emit_initial_value):
+        return unsub
+
+    # Last-resort fallback when no known UI scheduler is available.
+    # This keeps non-framework test contexts functional.
+    emit_initial_value()
+
+    return unsub
+
+
+class Reactive:
+    """
+    Mixin for Qyro Component classes.
+    Integrates seamlessly into Qyro's lifecycle:
+    - component_will_mount
+    - render
+    - component_will_unmount
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._qyro_store_subscriptions: List[Unsubscribe] = []
+
+    def bind_selector(
+        self,
+        store: Store[Any],
+        selector: Selector[Any, Any],
+        on_change: Callable[[Any], None],
+        equality_fn: Optional[EqualityFn] = None,
+    ) -> Unsubscribe:
+        """
+        Subscribes to a store slice. The subscription is tracked and
+        will be automatically cleaned up when the Qyro component unmounts.
+
+        The first callback is deferred to the next Qt tick so components can
+        subscribe during component_will_mount without touching widgets that are
+        created later in render().
+        """
+        if not hasattr(self, "_qyro_store_subscriptions"):
+            self._qyro_store_subscriptions = []
+
+        unsub = _select_with_deferred_initial(
+            component=self,
+            store=store,
+            selector=selector,
+            on_change=on_change,
+            equality_fn=equality_fn,
+        )
+        self._qyro_store_subscriptions.append(unsub)
+
+        return unsub
+
+    def component_will_unmount(self):
+        """Lifecycle hook: clean up all PyDux subscriptions to prevent leaks."""
+        if not hasattr(self, "_qyro_store_subscriptions"):
+            self._qyro_store_subscriptions = []
+
+        for unsub in self._qyro_store_subscriptions:
+            unsub()
+        self._qyro_store_subscriptions.clear()
+
+        # Call super if parent component defines component_will_unmount
+        if hasattr(super(), "component_will_unmount"):
+            super().component_will_unmount()
+
+
+def connect_qyro(store: Store[Any], selectors: Dict[str, Selector[Any, Any]]):
+    """
+    Decorator for Qyro components that automatically maps selectors to component properties.
+    """
+    def decorator(cls):
+        orig_mount = getattr(cls, "component_will_mount", None)
+        orig_unmount = getattr(cls, "component_will_unmount", None)
+
+        def new_component_will_mount(self):
+            if not hasattr(self, "_qyro_unsubs"):
+                self._qyro_unsubs = []
+            if not hasattr(self, "_qyro_connected_props"):
+                self._qyro_connected_props = {}
+
+            for attr_name, selector in selectors.items():
+                def make_listener(name: str):
+                    def listener(val: Any) -> None:
+                        setattr(self, name, val)
+                        self._qyro_connected_props[name] = val
+
+                        on_state_change = getattr(self, "on_state_change", None)
+                        if callable(on_state_change):
+                            on_state_change(dict(self._qyro_connected_props))
+
+                    return listener
+
+                unsub = _select_with_deferred_initial(
+                    component=self,
+                    store=store,
+                    selector=selector,
+                    on_change=make_listener(attr_name),
+                )
+                self._qyro_unsubs.append(unsub)
+
+            if orig_mount:
+                orig_mount(self)
+
+        def new_component_will_unmount(self):
+            if hasattr(self, "_qyro_unsubs"):
+                for unsub in self._qyro_unsubs:
+                    unsub()
+                self._qyro_unsubs.clear()
+            if orig_unmount:
+                orig_unmount(self)
+
+        cls.component_will_mount = new_component_will_mount
+        cls.component_will_unmount = new_component_will_unmount
+        return cls
+
+    return decorator
+
+
+# Backward-compatible alias for projects already using @pydux(...)
+pydux = connect_qyro

pydux/adapters/tkinter.py

@@ -0,0 +1,20 @@
+"""
+Tkinter Adapter for PyDux 3.0.
+Schedules state updates via Tkinter's event loop (widget.after / after_idle).
+"""
+
+from typing import Callable, Any
+from pydux.adapters.base import MainThreadBridge
+
+
+class TkinterBridge:
+    """Ensures Tkinter widgets are only mutated on the Tk main thread."""
+
+    def __init__(self, root_or_widget: Any):
+        self._widget = root_or_widget
+
+    def schedule_on_main_thread(self, fn: Callable[[], None]) -> None:
+        try:
+            self._widget.after_idle(fn)
+        except Exception:
+            fn()