bootstack 0.2.0__tar.gz → 0.2.1__tar.gz

{bootstack-0.2.0/src/bootstack.egg-info → bootstack-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.2.0
+Version: 0.2.1
 Summary: Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate.
 Author-email: Israel Dryer <israel.dryer@gmail.com>
 License-Expression: MIT

{bootstack-0.2.0 → bootstack-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.2.0"
+version = "0.2.1"
 description = "Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -114,7 +114,7 @@ where = ["src"]
 ]
 
 [tool.bumpversion]
-current_version = "0.2.0"
+current_version = "0.2.1"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<pre>a|b|rc)(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}{pre}{pre_n}",

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/_runtime/base_window.py

@@ -34,14 +34,29 @@ def on_visibility_alpha(event: tkinter.Event) -> None:
     X11 requires alpha to be set after the window is visible, so we bind
     to the <Visibility> event and set alpha then, unbinding after first use.
 
+    Being woken by this event at all is what proves the precondition: X11
+    reports visibility only for a window that is already on screen, so the very
+    first delivery is a valid moment to apply alpha. Whether that first report
+    says obscured or unobscured makes no difference — opacity is a property of
+    the window, not of how much of it happens to be uncovered.
+
+    Alpha is therefore applied before the binding is released, so first use is
+    genuinely the last one needed. Applying first also means that if the request
+    itself fails, the binding is still in place and the next visibility change
+    tries again — the one failure where a retry could help (#398).
+
     Args:
         event: The visibility event containing the widget.
     """
     widget = event.widget
     if hasattr(widget, 'alpha') and hasattr(widget, 'alpha_bind'):
-        if widget.alpha_bind:
-            widget.unbind(widget.alpha_bind)
         widget.attributes("-alpha", widget.alpha)
+        if widget.alpha_bind:
+            # `alpha_bind` is the id `bind` returned, so it is the *funcid*
+            # argument — passing it as the sequence removes nothing at all and
+            # raises nothing either, which is how this stayed unnoticed (#398).
+            widget.unbind("<Visibility>", widget.alpha_bind)
+            widget.alpha_bind = None
 
 
 class BaseWindow:

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/_runtime/events.py

@@ -354,22 +354,56 @@ def _patched_unbind(
     what = ('bind', self._w, sequence)
     try:
         script = self.tk.call(what)
-        lines = str(script).split('\n')
-        # Must match what `_patched_bind` emits (and stock `Misc._bind`).
-        prefix = 'if {"[%s ' % funcid
-        keep = [line for line in lines if not line.startswith(prefix)]
-        if len(keep) == len(lines):
-            # This funcid is not bound to this widget and sequence, so it is
-            # not ours to delete — the live binding may be somewhere else, and
-            # deleting its command would orphan it. Leave everything alone.
-            return
-        remaining = '\n'.join(keep)
-        self.tk.call(*what, remaining if remaining.strip() else '')
+    except tk.TclError:
+        # Reading the script is the one step whose failure is expected: the
+        # widget is gone, and its bindings and commands went with it. Nothing
+        # to remove and nothing to leak.
+        return
+
+    lines = str(script).split('\n')
+    # Must match what `_patched_bind` emits (and stock `Misc._bind`).
+    prefix = 'if {"[%s ' % funcid
+    keep = [line for line in lines if not line.startswith(prefix)]
+    if len(keep) == len(lines):
+        # This funcid is not bound to this widget and sequence, so it is
+        # not ours to delete — the live binding may be somewhere else, and
+        # deleting its command would orphan it. Leave everything alone.
+        #
+        # Correct, but it means the command and its closure survive for the
+        # life of the interpreter, invisibly. Surface it in development so the
+        # drift that produced it can be found (#399).
+        #
+        # Reported, not warned. This runs inside event dispatch and on the
+        # teardown path behind `Subscription.cancel()` and its `__exit__`, both
+        # documented as safe to call on a dead or already-removed handler. A
+        # `warnings.warn` here becomes an exception out of both under
+        # `-W error`, which is a worse outcome than the leak it describes.
+        from bootstack._runtime.utility import debug_log
+        debug_log(
+            f"unbind({sequence!r}, {funcid!r}) on {self._w!r} matched no "
+            "binding, so its Tcl command cannot safely be released and will "
+            "leak. The usual cause is an unbind that targeted a different "
+            "widget than the bind did; hold the Subscription that bind() "
+            "returned instead of re-deriving the target."
+        )
+        return
+
+    remaining = '\n'.join(keep)
+    # Deliberately NOT guarded: if the rewrite fails the handler is still bound
+    # and still firing, and swallowing that would report a successful
+    # cancellation for a live handler — a silent wrong answer (#400).
+    self.tk.call(*what, remaining if remaining.strip() else '')
+
+    try:
         # Replace the command rather than deleting it, so an in-flight copy of
         # the concatenated script has something harmless to call.
         self.tk.createcommand(funcid, lambda *args: '')
     except tk.TclError:
-        return
+        # The binding line is already gone, so the handler is genuinely removed
+        # and an in-flight script would find the original command rather than a
+        # deleted one. Fall through to the deferred delete instead of returning,
+        # which would strand the command forever (#400).
+        pass
 
     def _delete_command() -> None:
         try:

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/_runtime/shortcuts.py

@@ -57,13 +57,21 @@ _WIN_NAMES = {
 }
 
 # Tkinter binding modifiers
+#
+# `command` and `option` are platform-mapped for the same reason `mod` and `alt`
+# are. Off macOS the toolkit resolves the words "Command" and "Option" to its
+# generic Mod1 and Mod2 slots, and Windows reports NumLock as Mod1 — so a
+# `Command+S` binding fired on a bare `s` for anyone with NumLock switched on,
+# while the menu beside it read "Ctrl+S". Naming the modifier the display has
+# always claimed keeps the two from disagreeing (#405, and the same trap as
+# #403).
 _BINDING_MODIFIERS = {
     'mod': 'Command' if IS_MAC else 'Control',
-    'command': 'Command',
+    'command': 'Command' if IS_MAC else 'Control',
     'ctrl': 'Control',
     'control': 'Control',
     'alt': 'Option' if IS_MAC else 'Alt',
-    'option': 'Option',
+    'option': 'Option' if IS_MAC else 'Alt',
     'shift': 'Shift',
 }
 

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/_runtime/utility.py

@@ -344,6 +344,28 @@ def _debug_enabled() -> bool:
     return str(os.environ.get("BOOTSTACK_DEBUG", "")).lower() in {"1", "true", "yes"}
 
 
+def debug_log(message: str) -> None:
+    """Print a diagnostic message if debug is enabled.
+
+    For reporting a condition that has no exception behind it. Use
+    `debug_log_exception` when there is one.
+
+    Never raises, and deliberately does not use `warnings.warn`: these fire from
+    inside event dispatch and teardown, where a warning filter set to `error`
+    would turn a diagnostic into a failure on a path documented as safe.
+
+    Args:
+        message: The text to print.
+    """
+    if not _debug_enabled():
+        return
+    try:
+        print(f"bootstack DEBUG: {message}")
+    except Exception:
+        # Never raise from debug logging
+        pass
+
+
 def debug_log_exception(message: str = "") -> None:
     """Print the current exception traceback if debug is enabled.
 

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/dialogs/_impl/colorchooser.py

@@ -15,7 +15,10 @@ from PIL import ImageColor
 from bootstack.constants import *
 from bootstack._core import colorutils
 from bootstack._core.colorutils import HEX, HSL, HUE, LUM, RGB, SAT
-from bootstack.dialogs._impl.dialog import Dialog
+from bootstack.events import Subscription
+from bootstack.dialogs._impl.dialog import (
+    DIALOG_RESULT, Dialog, emit_dialog_result, result_target,
+)
 from bootstack.i18n import MessageCatalog
 from bootstack._runtime import utility
 from bootstack.style.style import get_style, get_theme_color
@@ -554,35 +557,28 @@ class ColorChooserDialog:
         if not self._emitted_result:
             self._emit_result(confirmed=self.result is not None)
 
-    def on_dialog_result(self, callback: Callable[[Any], None]) -> Optional[str]:
-        """Bind a callback fired when the dialog produces a result."""
-        target = self._master or self._dialog.toplevel
+    def on_dialog_result(self, callback: Callable[[Any], None]) -> "Optional[Subscription]":
+        """Bind a callback fired when the dialog produces a result.
+
+        Returns:
+            A `Subscription`, or `None` if there is no widget to bind to.
+            Cancel it with `.cancel()`.
+        """
+        target = result_target(self._dialog, self._master)
         if target is None:
             return None
 
         def handler(event):
             callback(getattr(event, "data", None))
 
-        return target.bind("<<DialogResult>>", handler, add="+")
-
-    def off_dialog_result(self, funcid: str) -> None:
-        """Unbind a previously bound dialog result callback."""
-        target = self._master or self._dialog.toplevel
-        if target is None:
-            return
-        target.unbind("<<DialogResult>>", funcid)
+        # The Subscription remembers the widget it bound to — see #397.
+        bind_id = target.bind(DIALOG_RESULT, handler, add="+")
+        return Subscription(target, DIALOG_RESULT, bind_id)
 
     # helpers ------------------------------------------------------------------
     def _emit_result(self, confirmed: bool) -> None:
-        payload = {"result": self.result, "confirmed": confirmed}
-        target = self._master or self._dialog.toplevel
-        if not target:
-            return
-        try:
-            target.event_generate("<<DialogResult>>", data=payload)
-        except Exception:
-            try:
-                target.event_generate("<<DialogResult>>")
-            except Exception:
-                pass
+        emit_dialog_result(
+            result_target(self._dialog, self._master),
+            {"result": self.result, "confirmed": confirmed},
+        )
         self._emitted_result = True

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/dialogs/_impl/datedialog.py

@@ -14,7 +14,10 @@ from tkinter import Widget
 
 from bootstack.widgets._impl.primitives import Frame
 from bootstack.constants import BOTH, YES
-from bootstack.dialogs._impl.dialog import Dialog, DialogButton
+from bootstack.events import Subscription
+from bootstack.dialogs._impl.dialog import (
+    DIALOG_RESULT, Dialog, DialogButton, emit_dialog_result, result_target,
+)
 from bootstack._runtime.window_utilities import AnchorPoint
 from bootstack.widgets._impl.composites.calendar import Calendar
 
@@ -404,7 +407,7 @@ class DateDialog:
         """The selected date (single mode) or `(start, end)` tuple (range mode), or None if cancelled."""
         return self._dialog.result
 
-    def on_result(self, callback: Callable[[date], None]) -> Optional[str]:
+    def on_result(self, callback: Callable[[date], None]) -> Optional[Subscription]:
         """Bind a callback fired when a result is produced.
 
         The callback receives `event.data["result"]` (a `datetime.date`).
@@ -413,38 +416,23 @@ class DateDialog:
             callback: Callable that receives the selected `datetime.date`.
 
         Returns:
-            The Tk binding identifier, which can be used with `off_result`.
+            A `Subscription`, or `None` if there is no widget to bind to.
+            Cancel it with `.cancel()`.
         """
-        target = self._dialog.toplevel or self._master
+        target = result_target(self._dialog, self._master)
         if target is None:
             return None
 
         def handler(event: tkinter.Event) -> None:
             callback(getattr(event, "data", None))
 
-        return target.bind("<<DialogResult>>", handler, add="+")
-
-    def off_result(self, funcid: str) -> None:
-        """Unbind a previously bound `on_result` callback.
-
-        Args:
-            funcid: Binding identifier returned by `on_result`.
-        """
-        target = self._dialog.toplevel or self._master
-        if target is None:
-            return
-        target.unbind("<<DialogResult>>", funcid)
+        # The Subscription remembers the widget it bound to — see #397.
+        bind_id = target.bind(DIALOG_RESULT, handler, add="+")
+        return Subscription(target, DIALOG_RESULT, bind_id)
 
     def _emit_result(self, value: date, confirmed: bool) -> None:
         """Emit a virtual Tk event with the dialog result."""
-        target = self._dialog.toplevel or self._master
-        if not target:
-            return
-        payload = {"result": value, "confirmed": confirmed}
-        try:
-            target.event_generate("<<DialogResult>>", data=payload)
-        except Exception:
-            try:
-                target.event_generate("<<DialogResult>>")
-            except Exception:
-                pass
+        emit_dialog_result(
+            result_target(self._dialog, self._master),
+            {"result": value, "confirmed": confirmed},
+        )

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/dialogs/_impl/dialog.py

@@ -127,6 +127,58 @@ class ShowOptions(TypedDict, total=False):
     auto_flip: Union[bool, Literal['vertical', 'horizontal']]
 
 
+# --- Dialog result delivery -------------------------------------------------
+
+DIALOG_RESULT = "<<DialogResult>>"
+
+
+def result_target(dialog: "Dialog", master: Optional[tkinter.Misc]) -> Optional[tkinter.Misc]:
+    """The widget `<<DialogResult>>` is bound on and fired from.
+
+    Binding and firing both route through here so the two cannot resolve
+    differently. That mattered: `Dialog.toplevel` is `None` before `show()`
+    and a *destroyed* widget after it, because nothing resets `_toplevel`
+    when the modal wait ends. A target derived from it is therefore never
+    live at both ends — subscribers bound to the master while the result
+    fired at a dead toplevel, where `event_generate` raised and the error
+    was swallowed (#397).
+
+    `master` comes first for that reason: it outlives the dialog.
+
+    Args:
+        dialog: The dialog producing the result.
+        master: The dialog's master widget, if it has one.
+
+    Returns:
+        A live widget, or `None` when there is nothing left to fire on.
+    """
+    if master is not None:
+        return master
+    top = dialog.toplevel
+    if top is not None and top.winfo_exists():
+        return top
+    return None
+
+
+def emit_dialog_result(target: Optional[tkinter.Misc], payload: dict) -> None:
+    """Fire `<<DialogResult>>` on `target` with `payload` attached.
+
+    Args:
+        target: The widget from `result_target`, or `None` to do nothing.
+        payload: Mapping with `result` and `confirmed` keys.
+    """
+    if target is None:
+        return
+    try:
+        target.event_generate(DIALOG_RESULT, data=payload)
+    except tkinter.TclError:
+        # `result_target` hands back a live widget, so reaching here means it
+        # was destroyed in between. Nothing can receive the result; surface it
+        # in development rather than letting it vanish the way it used to.
+        from bootstack._runtime.utility import debug_log_exception
+        debug_log_exception(f"could not deliver {DIALOG_RESULT}")
+
+
 # --- Dialog ----------------------------------------------------------------
 
 class Dialog:

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/dialogs/_impl/message.py

@@ -10,7 +10,10 @@ from bootstack.widgets._impl.primitives import Frame, Label
 from bootstack._core.images import _ImageService
 from bootstack.constants import *
 from bootstack.i18n import MessageCatalog
-from .dialog import ButtonRole, Dialog, DialogButton
+from bootstack.events import Subscription
+from .dialog import (
+    DIALOG_RESULT, ButtonRole, Dialog, DialogButton, emit_dialog_result, result_target,
+)
 
 ttk = SimpleNamespace(Frame=Frame, Label=Label)
 
@@ -198,23 +201,17 @@ class MessageDialog:
             position: x and y coordinates to position the dialog. If None, centers on parent.
         """
         self._dialog.show(position=position, modal=True)
-        target = self._dialog.toplevel or self._master
-        if target:
-            payload = {"result": self._dialog.result, "confirmed": self._dialog.result is not None}
-            try:
-                target.event_generate("<<DialogResult>>", data=payload)
-            except Exception:
-                try:
-                    target.event_generate("<<DialogResult>>")
-                except Exception:
-                    pass
+        emit_dialog_result(
+            result_target(self._dialog, self._master),
+            {"result": self._dialog.result, "confirmed": self._dialog.result is not None},
+        )
 
     @property
     def result(self) -> Any:
         """The dialog result value (the text of the button pressed)."""
         return self._dialog.result
 
-    def on_dialog_result(self, callback: Callable[[Any], None]) -> Optional[str]:
+    def on_dialog_result(self, callback: Callable[[Any], None]) -> "Optional[Subscription]":
         """Bind a callback fired when the dialog produces a result.
 
         The callback receives `event.data["result"]` when available.
@@ -223,23 +220,22 @@ class MessageDialog:
             callback: Callable that receives the result payload.
 
         Returns:
-            Binding identifier for use with `off_dialog_result`.
+            A `Subscription`, or `None` if there is no widget to bind to.
+            Cancel it with `.cancel()`.
         """
-        target = self._dialog.toplevel or self._master
+        target = result_target(self._dialog, self._master)
         if target is None:
             return None
 
         def handler(event):
             callback(getattr(event, "data", None))
 
-        return target.bind("<<DialogResult>>", handler, add="+")
-
-    def off_dialog_result(self, funcid: str) -> None:
-        """Unbind a previously bound dialog result callback."""
-        target = self._dialog.toplevel or self._master
-        if target is None:
-            return
-        target.unbind("<<DialogResult>>", funcid)
+        # The Subscription remembers the widget it bound to. Resolving the
+        # target a second time to unbind would not: `_dialog.toplevel` is None
+        # until show(), so subscribing before and cancelling after resolved to
+        # two different widgets and the removal silently matched nothing (#397).
+        bind_id = target.bind(DIALOG_RESULT, handler, add="+")
+        return Subscription(target, DIALOG_RESULT, bind_id)
 
 
 class MessageBox:

{bootstack-0.2.0 → bootstack-0.2.1}/src/bootstack/dialogs/_impl/query.py

@@ -16,7 +16,10 @@ ttk = SimpleNamespace(
 )
 from bootstack.i18n import MessageCatalog
 from bootstack.dialogs._impl.datedialog import DateDialog
-from bootstack.dialogs._impl.dialog import Dialog, DialogButton
+from bootstack.events import Subscription
+from bootstack.dialogs._impl.dialog import (
+    DIALOG_RESULT, Dialog, DialogButton, emit_dialog_result, result_target,
+)
 from bootstack.dialogs._impl.fontdialog import FontDialog
 from bootstack.dialogs._impl.message import MessageBox
 from bootstack.widgets._impl.composites.textentry import TextEntry
@@ -264,23 +267,17 @@ class QueryDialog:
             position: x and y coordinates to position the dialog. If None, centers on parent.
         """
         self._dialog.show(position=position, modal=True)
-        target = self._dialog.toplevel or self._master
-        if target:
-            payload = {"result": self._dialog.result, "confirmed": self._dialog.result is not None}
-            try:
-                target.event_generate("<<DialogResult>>", data=payload)
-            except Exception:
-                try:
-                    target.event_generate("<<DialogResult>>")
-                except Exception:
-                    pass
+        emit_dialog_result(
+            result_target(self._dialog, self._master),
+            {"result": self._dialog.result, "confirmed": self._dialog.result is not None},
+        )
 
     @property
     def result(self) -> Any:
         """The dialog result value."""
         return self._dialog.result
 
-    def on_dialog_result(self, callback: Callable[[Any], None]) -> Optional[str]:
+    def on_dialog_result(self, callback: Callable[[Any], None]) -> "Optional[Subscription]":
         """Bind a callback fired when the dialog produces a result.
 
         The callback receives `event.data["result"]` when available.
@@ -289,23 +286,19 @@ class QueryDialog:
             callback: Callable that receives the result payload.
 
         Returns:
-            Binding identifier for use with `off_dialog_result`.
+            A `Subscription`, or `None` if there is no widget to bind to.
+            Cancel it with `.cancel()`.
         """
-        target = self._dialog.toplevel or self._master
+        target = result_target(self._dialog, self._master)
         if target is None:
             return None
 
         def handler(event):
             callback(getattr(event, "data", None))
 
-        return target.bind("<<DialogResult>>", handler, add="+")
-
-    def off_dialog_result(self, funcid: str) -> None:
-        """Unbind a previously bound dialog result callback."""
-        target = self._dialog.toplevel or self._master
-        if target is None:
-            return
-        target.unbind("<<DialogResult>>", funcid)
+        # The Subscription remembers the widget it bound to — see #397.
+        bind_id = target.bind(DIALOG_RESULT, handler, add="+")
+        return Subscription(target, DIALOG_RESULT, bind_id)
 
 
 class QueryBox:

bootstack-0.2.1/src/bootstack/events/_subscription.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import tkinter
+
+
+class Subscription:
+    """Handle returned by `widget.on(...)`. Cancels the binding when `.cancel()`
+    is called or the context manager exits.
+
+    Idempotent: calling `cancel()` more than once is a no-op.
+    """
+
+    __slots__ = ("_widget", "_sequence", "_bind_id", "_cancelled")
+
+    def __init__(self, widget: tkinter.Misc, sequence: str, bind_id: str) -> None:
+        self._widget = widget
+        self._sequence = sequence
+        self._bind_id = bind_id
+        self._cancelled = False
+
+    def cancel(self) -> None:
+        """Remove the binding. Safe to call more than once, and on a dead widget.
+
+        `cancelled` afterwards means the removal was carried out as far as this
+        handle can carry it — the handler will not be delivered to again through
+        this subscription.
+        """
+        if self._cancelled:
+            return
+        try:
+            self._widget.unbind(self._sequence, self._bind_id)
+        except tkinter.TclError:
+            # The removal failed partway, which leaves the handler bound and
+            # still firing. Swallowed so teardown never fails, but deliberately
+            # NOT marked cancelled: claiming otherwise made `cancelled` read
+            # True for a live handler (#400). A later cancel() may still succeed.
+            #
+            # A widget that is merely gone does not reach here — unbind absorbs
+            # that case itself, and rightly reports success, since a destroyed
+            # widget takes its bindings with it.
+            return
+        # Includes the case where unbind found nothing to remove: the handler is
+        # already unreachable through this widget and sequence, and no retry can
+        # change that, so reporting anything but cancelled would be both wrong
+        # and permanent. If it is unreachable here because it was bound
+        # somewhere else, that is drift rather than a completed cancel, and
+        # unbind reports it under BOOTSTACK_DEBUG (#399) — this handle has no
+        # way to tell the two apart.
+        self._cancelled = True
+
+    def __enter__(self) -> "Subscription":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.cancel()
+
+    @property
+    def cancelled(self) -> bool:
+        """Whether `cancel()` has completed for this subscription."""
+        return self._cancelled