bootstack 0.1.0__py3-none-any.whl

bootstack/_core/publisher.py

@@ -0,0 +1,149 @@
+"""Publisher-Subscriber pattern implementation for bootstack.
+
+This module implements a simple publisher-subscriber (pub-sub) pattern used
+for theme change notifications and widget updates throughout bootstack.
+
+The Publisher class manages subscribers on different channels and broadcasts
+messages to all subscribers when events occur (like theme changes).
+
+Classes:
+    Channel: Enum defining subscriber channels (STD for tk, TTK for ttk)
+    Subscriber: Data class storing subscriber information
+    Publisher: Manages subscriptions and publishes messages to subscribers
+
+Example:
+    ```python
+    from bootstack.publisher import Publisher, Channel
+
+    # Subscribe a function to theme changes
+    def on_theme_change():
+        print("Theme changed!")
+
+    Publisher.subscribe(
+        func=on_theme_change,
+        channel=Channel.TTK
+    )
+
+    # Publish a message to all TTK subscribers
+    Publisher.publish(Channel.TTK)
+    ```
+"""
+from enum import Enum
+
+
+class Channel(Enum):
+    """A grouping for Publisher subscribers. Indicates whether the
+    widget is a legacy `STD` tk widget or a styled `TTK` widget.
+
+    Attributes:
+
+        STD (1):
+            Legacy tkinter widgets.
+
+        TTK (2):
+            Themed tkinter widgets.
+    """
+
+    STD = 1
+    TTK = 2
+
+
+class Subscriber:
+    """A subscriber data class used to store information about a specific
+    subscriber to the `Publisher`."""
+
+    def __init__(self, name, func, channel):
+        """Create a subscriber.
+
+        Parameters:
+
+            name (str):
+                The name of the subscriber
+
+            func (Callable):
+                The function to call when messaging.
+
+            channel (Channel):
+                The subscription channel.
+        """
+        self.name = name
+        self.func = func
+        self.channel = channel
+
+
+class Publisher:
+    """Publish events to subscribed widgets for theme changes or configuration updates."""
+
+    __subscribers = {}
+
+    @staticmethod
+    def subscriber_count():
+        return len(Publisher.__subscribers)
+
+    @staticmethod
+    def subscribe(name, func, channel):
+        """Subscribe to an event.
+
+        Parameters:
+
+            name (str):
+                The widget's tkinter/tcl name.
+
+            func (Callable):
+                A function to call when passing a message.
+
+            channel (Channel):
+                Indicates the channel grouping the subscribers.
+        """
+        subs = Publisher.__subscribers
+        subs[name] = Subscriber(name, func, channel)
+
+    @staticmethod
+    def unsubscribe(name):
+        """Remove a subscriber.
+
+        Parameters:
+
+            name (str):
+                The widget's tkinter/tcl name.
+        """
+        subs = Publisher.__subscribers
+        try:
+            del subs[str(name)]
+        except:
+            pass
+
+    def get_subscribers(channel):
+        """Return a list of subscribers.
+
+        Returns:
+
+            List:
+                List of key-value tuples
+        """
+        subs = Publisher.__subscribers.values()
+        channel_subs = [s for s in subs if s.channel == channel]
+        return channel_subs
+
+    def publish_message(channel, *args, **kwargs):
+        """Publish a message to all subscribers.
+
+        Parameters:
+
+            channel (Channel):
+                The name of the channel to subscribe.
+
+            **args:
+                optional positional arguments to pass to the subscribers.
+
+            **kwargs:
+                optional keyword arguments to pass to the subscribers.
+        """
+        subs: list[Subscriber] = Publisher.get_subscribers(channel)
+        for sub in subs:
+            sub.func(*args, **kwargs)
+
+    @staticmethod
+    def clear_subscribers():
+        """Reset all subscriptions."""
+        Publisher.__subscribers.clear()

bootstack/_core/variables.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import ast
+import tkinter
+
+
+class SetVar(tkinter.Variable):
+    """
+    A tkinter variable that holds a set of values.
+
+    This variable serializes a Python set into its string representation
+    for storage and deserializes it back into a set on retrieval.
+    """
+
+    def __init__(self, master=None, value: set | None = None, name: str | None = None):
+        """
+        Initialize the SetVar.
+
+        Args:
+            master (Widget, optional): The parent widget. Defaults to None.
+            value (set, optional): The initial value. Defaults to an empty set.
+            name (str, optional): The name of the variable. Defaults to None.
+        """
+        if value is None:
+            value = set()
+        super().__init__(master, value, name)
+
+    def set(self, value: set | frozenset):
+        """
+        Set the variable to a new value.
+
+        The value is converted to its string representation for storage.
+
+        Args:
+            value (set | frozenset): The new value. Should be a set or frozenset.
+        """
+        if not isinstance(value, (set, frozenset)):
+            raise TypeError(f"Expected set or frozenset, got {type(value).__name__}")
+        super().set(repr(value))
+
+    def get(self) -> set:
+        """
+        Return the value of the variable as a Python set.
+
+        The string representation is deserialized back into a set.
+
+        Returns:
+            set: The current value of the variable.
+        """
+        value_str = super().get()
+        if not value_str:
+            return set()
+
+        try:
+            # Use literal_eval for safe evaluation of the string representation
+            deserialized_value = ast.literal_eval(value_str)
+            if isinstance(deserialized_value, (set, frozenset)):
+                return set(deserialized_value)
+            else:
+                return set()
+        except (ValueError, SyntaxError):
+            return set()

bootstack/_runtime/__init__.py

@@ -0,0 +1,3 @@
+"""Runtime integration layer (Tk/tcl interop, assets, scaling)."""
+
+# Placeholder for future runtime utilities.