bootstack 0.3.2__tar.gz → 0.4.0__tar.gz

{bootstack-0.3.2/src/bootstack.egg-info → bootstack-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.3.2
+Version: 0.4.0
 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.3.2 → bootstack-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.3.2"
+version = "0.4.0"
 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.3.2"
+current_version = "0.4.0"
 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.3.2 → bootstack-0.4.0}/src/bootstack/_core/__init__.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-from . import colorutils, publisher, capabilities
 from bootstack._core.exceptions import (
     ThemeError,
     NavigationError,
@@ -11,9 +10,6 @@ from bootstack._core.exceptions import (
 )
 
 __all__ = [
-    "colorutils",
-    "publisher",
-    "capabilities",
     "ThemeError",
     "NavigationError",
     "StyleBuilderError",

bootstack-0.4.0/src/bootstack/_core/mixins/widget.py

@@ -0,0 +1,387 @@
+from __future__ import annotations
+
+from typing import Mapping, Any, Callable, TypedDict, Unpack, Self
+
+
+class ClipboardKwargs(TypedDict, total=False):
+    """Keyword options accepted by clipboard operations."""
+
+    displayof: Any
+    """Widget or window whose display to target. Omit for the main application display."""
+    type: str
+    """Clipboard type name (e.g., `'STRING'`, `'UTF8_STRING'`). Platform-dependent."""
+    format: str
+    """Data format for representing selection data to the X server (e.g., `'STRING'`). Platform-dependent."""
+
+
+class GridKwargs(TypedDict, total=False):
+    """Keyword options for `grid()` and `grid_configure()`."""
+
+    row: int
+    """Row index (0-based). Defaults to the next available row."""
+    column: int
+    """Column index (0-based). Defaults to 0."""
+    rowspan: int
+    """Number of rows to span. Defaults to 1."""
+    columnspan: int
+    """Number of columns to span. Defaults to 1."""
+    sticky: str
+    """How the widget expands within its cell (e.g., `'nsew'`, `'ew'`, `'n'`). Defaults to `''`."""
+    padx: int | tuple[int, int]
+    """Horizontal external padding in pixels. A tuple sets (left, right) independently."""
+    pady: int | tuple[int, int]
+    """Vertical external padding in pixels. A tuple sets (top, bottom) independently."""
+    ipadx: int
+    """Horizontal internal padding in pixels."""
+    ipady: int
+    """Vertical internal padding in pixels."""
+    in_: Any
+    """Parent widget to grid into (rarely needed — defaults to the widget's own master)."""
+
+
+class GridRowColumnKwargs(TypedDict, total=False):
+    """Keyword options for `grid_rowconfigure()` and `grid_columnconfigure()`."""
+
+    weight: int
+    """How extra space is distributed among rows/columns. 0 means no expansion. Defaults to 0."""
+    minsize: int
+    """Minimum row/column size in pixels. Defaults to 0."""
+    pad: int
+    """Extra padding added to the row/column in pixels. Defaults to 0."""
+    uniform: str
+    """Group name — rows/columns sharing a group are given equal size."""
+
+
+class PackKwargs(TypedDict, total=False):
+    """Keyword options for `pack()` and `pack_configure()`."""
+
+    side: str
+    """Side to pack against — `'top'`, `'bottom'`, `'left'`, or `'right'`. Defaults to `'top'`."""
+    fill: str
+    """How to fill extra space — `'x'`, `'y'`, `'both'`, or `'none'`. Defaults to `'none'`."""
+    expand: bool | int
+    """If True/1, the widget expands to fill extra space in the packing direction. Defaults to False."""
+    anchor: str
+    """Where to place the widget when it does not fill available space (e.g., `'center'`, `'nw'`). Defaults to `'center'`."""
+    padx: int | tuple[int, int]
+    """Horizontal external padding in pixels. A tuple sets (left, right) independently."""
+    pady: int | tuple[int, int]
+    """Vertical external padding in pixels. A tuple sets (top, bottom) independently."""
+    ipadx: int
+    """Horizontal internal padding in pixels."""
+    ipady: int
+    """Vertical internal padding in pixels."""
+    before: Any
+    """Pack this widget immediately before the given widget."""
+    after: Any
+    """Pack this widget immediately after the given widget."""
+    in_: Any
+    """Parent widget to pack into (rarely needed — defaults to the widget's own master)."""
+
+
+class WidgetCapabilitiesMixin:
+    """Common widget API surface (tk + ttk).
+
+    This mixin aggregates documented capability mixins into a single interface
+    suitable for both Tk and ttk widgets, plus a small set of commonly used
+    widget operations (configure/cget/destroy, stacking order, etc.).
+    """
+
+    # -------------------------------------------------------------------------
+    # Lifecycle
+    # -------------------------------------------------------------------------
+
+    def destroy(self) -> None:
+        """Destroy this widget and release its Tk resources."""
+        return super().destroy()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Configuration
+    # -------------------------------------------------------------------------
+
+    def configure(self, cnf: Mapping[str, Any] | None = None, **kw: Any) -> Any:
+        """Configure widget options.
+
+        Args:
+            cnf: Optional mapping of option values.
+            **kw: Option values as keyword arguments.
+
+        Returns:
+            Tk returns configuration details when called with no args; otherwise
+            the return value is implementation-dependent.
+        """
+        if cnf is None:
+            return super().configure(**kw)  # type: ignore[misc]
+        return super().configure(cnf, **kw)  # type: ignore[misc]
+
+    config = configure
+
+    def cget(self, key: str) -> Any:
+        """Return the current value for an option.
+
+        Args:
+            key: Option name (with or without a leading dash).
+
+        Returns:
+            The option value.
+        """
+        return super().cget(key)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Stacking order
+    # -------------------------------------------------------------------------
+
+    def lift(self, aboveThis: Any | None = None) -> None:
+        """Raise this widget above its siblings.
+
+        Args:
+            aboveThis: Optional sibling widget to raise above.
+        """
+        return super().lift(aboveThis)  # type: ignore[misc]
+
+    tkraise = lift
+
+    def lower(self, belowThis: Any | None = None) -> None:
+        """Lower this widget below its siblings.
+
+        Args:
+            belowThis: Optional sibling widget to lower below.
+        """
+        return super().lower(belowThis)  # type: ignore[misc]
+
+    def after_repeat(
+        self, ms: int, func: Callable[..., Any], *args: Any
+    ) -> Callable[[], None]:
+        """Call `func` repeatedly every `ms` milliseconds.
+
+        This helper schedules `func` and then automatically reschedules it after
+        each run. It returns a `cancel()` function you can call to stop repetition.
+
+        Args:
+            ms: Interval in milliseconds.
+            func: Callback to run each interval.
+            *args: Arguments to pass to `func`.
+
+        Returns:
+            A `cancel()` callable. Call it to stop the repeating schedule.
+
+        Examples:
+            >>> cancel = widget.after_repeat(250, tick)
+            >>> cancel()
+        """
+        cancelled = False
+        token: str | None = None
+
+        def _run():
+            nonlocal token
+            if cancelled:
+                return
+            func(*args)
+            token = self.after(ms, _run)
+
+        token = self.after(ms, _run)
+
+        def cancel() -> None:
+            nonlocal cancelled, token
+            cancelled = True
+            if token is not None:
+                try:
+                    self.after_cancel(token)
+                except Exception:
+                    pass
+                token = None
+
+        return cancel
+
+    def bindtags_prepend(self, tag: str) -> tuple[str, ...]:
+        """Prepend a tag to the bindtags list.
+
+        This increases the tag's priority (it will be processed earlier).
+
+        Args:
+            tag: Tag name to prepend.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        if tag not in current:
+            current.insert(0, tag)
+            self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_append(self, tag: str) -> tuple[str, ...]:
+        """Append a tag to the bindtags list.
+
+        This decreases the tag's priority (it will be processed later).
+
+        Args:
+            tag: Tag name to append.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        if tag not in current:
+            current.append(tag)
+            self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_remove(self, tag: str) -> tuple[str, ...]:
+        """Remove a tag from the bindtags list.
+
+        Args:
+            tag: Tag name to remove.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = [t for t in self.bindtags() if t != tag]
+        self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_replace(self, old: str, new: str) -> tuple[str, ...]:
+        """Replace a bindtag with another tag.
+
+        Args:
+            old: Existing tag name.
+            new: Replacement tag name.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        try:
+            idx = current.index(old)
+        except ValueError:
+            return tuple(current)
+        current[idx] = new
+        self.bindtags(current)
+        return tuple(current)
+
+    def clipboard_set(self, text: str, **kw: Unpack[ClipboardKwargs]) -> None:
+        """Replace clipboard contents with *text*.
+
+        Convenience wrapper for `clipboard_clear()` + `clipboard_append()`.
+
+        Args:
+            text: Text to set on the clipboard.
+            **kw: See `ClipboardKwargs`. Forwarded to both clear and append.
+        """
+        self.clipboard_clear(**kw)
+        self.clipboard_append(text, **kw)
+
+    def grid(self, cnf: dict[str, Any] | None = None, **kw: Unpack[GridKwargs]) -> Self:
+        """Position this widget using the grid geometry manager.
+
+        Args:
+            cnf: Optional dict of grid options (same keys as `GridKwargs`).
+            **kw: See `GridKwargs`.
+
+        Returns:
+            Self for method chaining.
+        """
+        options = cnf or {}
+        options.update(kw)
+
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, "_on_child_grid"):
+            parent._on_child_grid(self, **options)
+        else:
+            super().grid(**options)  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def grid_configure(
+        self, cnf: dict[str, Any] | None = None, **kw: Unpack[GridKwargs]
+    ) -> Self:
+        """Alias for `grid()`.
+
+        Args:
+            cnf: Optional dict of grid options.
+            **kw: See `GridKwargs`.
+
+        Returns:
+            Self for method chaining.
+        """
+        return self.grid(cnf, **kw)
+
+    def grid_forget(self) -> Self:
+        """Unmap this widget and forget its grid configuration.
+
+        The widget is removed from the layout, and its previous grid options
+        are discarded.
+
+        Returns:
+            Self for method chaining.
+        """
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, "_on_child_grid_forget"):
+            parent._on_child_grid_forget(self)
+        else:
+            super().grid_forget()  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def grid_remove(self) -> Self:
+        """Unmap this widget but remember its grid configuration.
+
+        Use `grid()` with no args to restore it to its previous grid location.
+
+        Returns:
+            Self for method chaining.
+        """
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, "_on_child_grid_remove"):
+            parent._on_child_grid_remove(self)
+        else:
+            super().grid_remove()  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def pack(self, cnf: dict[str, Any] | None = None, **kw: Unpack[PackKwargs]) -> Self:
+        """Position this widget using the pack geometry manager.
+
+        Args:
+            cnf: Optional dict of pack options (same keys as `PackKwargs`).
+            **kw: See `PackKwargs`.
+
+        Returns:
+            Self for method chaining.
+        """
+        options = cnf or {}
+        options.update(kw)
+
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, "_on_child_pack"):
+            parent._on_child_pack(self, **options)
+        else:
+            super().pack(**options)  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def pack_configure(
+        self, cnf: dict[str, Any] | None = None, **kw: Unpack[PackKwargs]
+    ) -> Self:
+        """Alias for `pack()`.
+
+        Args:
+            cnf: Optional dict of pack options.
+            **kw: See `PackKwargs`.
+
+        Returns:
+            Self for method chaining.
+        """
+        return self.pack(cnf, **kw)
+
+    def pack_forget(self) -> Self:
+        """Unmap this widget and forget its pack configuration.
+
+        The widget is removed from the layout, and its previous pack options
+        are discarded.
+
+        Returns:
+            Self for method chaining.
+        """
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, "_on_child_pack_forget"):
+            parent._on_child_pack_forget(self)
+        else:
+            super().pack_forget()  # type: ignore[misc]
+        return self  # type: ignore[return-value]

{bootstack-0.3.2 → bootstack-0.4.0}/src/bootstack/_runtime/app.py

@@ -19,7 +19,6 @@ from typing_extensions import Unpack
 from bootstack.constants import *
 from bootstack.i18n.intl_format import detect_locale
 from bootstack.i18n.msgcat import MessageCatalog
-from bootstack._core.publisher import Publisher
 from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
 from bootstack._runtime.base_window import BaseWindow
 from bootstack._runtime.utility import enable_high_dpi_awareness
@@ -156,7 +155,6 @@ def apply_class_bindings(window: tkinter.Widget | App) -> None:
 def apply_all_bindings(window: tkinter.Widget | App) -> None:
     """Add bindings to all widgets in the application"""
     window.bind_all('<Map>', on_map_child, '+')
-    window.bind_all('<Destroy>', lambda e: Publisher.unsubscribe(e.widget))
 
 
 def on_disabled_readonly_state(event: tkinter.Event) -> None:
@@ -382,10 +380,6 @@ class App(BaseWindow, WidgetCapabilitiesMixin, tkinter.Tk):
     """The primary application window and entry point.
 
     App adds theming, localization, and platform setup on top of `tkinter.Tk`.
-
-    The standard widget API (events, scheduling, clipboard, geometry managers,
-    winfo, etc.) is documented under bootstack capabilities and is available
-    on App via inheritance.
     """
 
     def __init__(

{bootstack-0.3.2 → bootstack-0.4.0}/src/bootstack/_runtime/base_window.py

@@ -5,9 +5,6 @@ window management functionality used by both the main App and Toplevel classes.
 This eliminates code duplication and ensures consistent behavior across all
 window types.
 
-Standard widget APIs (events, scheduling, clipboard, geometry managers, winfo) are documented under capabilities and are
- available through normal Tk/Ttk inheritance.”
-
 The BaseWindow mixin provides:
 - Window manager (wm) pass-throughs with modern docstrings
 - Window configuration (size, position, constraints)

bootstack-0.4.0/src/bootstack/_runtime/grab.py

@@ -0,0 +1,109 @@
+"""Modal grab capture and restore, shared by the dialog and window paths.
+
+Tk releases a grab when the window holding it is destroyed, but it does NOT
+restore the grab that window displaced. Anything that takes a modal grab has to
+hand back what it found, or the window underneath is left on screen, still
+blocking its caller, holding nothing (#440 for dialogs, #444 for windows).
+
+These live here rather than beside the dialogs because the import direction runs
+dialogs -> _runtime: `dialogs/_impl/dialog.py` imports `Toplevel` from this
+package, so `_runtime` reaching back the other way would be a cycle.
+"""
+from __future__ import annotations
+
+import tkinter
+from typing import Any
+
+def capture_grab(widget: Any) -> tuple[Any, str | None] | None:
+    """Record who holds the modal grab and HOW, for `restore_grab` to hand back.
+
+    Returns `None` when nothing holds the grab — the outermost case, which needs
+    no restore. Otherwise returns the holder paired with its grab KIND.
+
+    ⚠ Call this BEFORE taking the grab. Once another window grabs, the previous
+    holder's `grab_status()` reads `None`, so a kind read afterwards is always
+    wrong — measured, and the reason this pairing exists as one function rather
+    than two steps a caller has to sequence correctly.
+
+    The kind matters because Tk has two: `bs.Window(modal="app")` takes a GLOBAL
+    grab, and restoring that as a local one silently narrows the window's
+    modality (it would block only this application). Reading the kind back from
+    Tk rather than assuming it keeps this correct on every window system without
+    a platform branch — whatever Tk reported, we hand back.
+
+    A holder this cannot ADDRESS reads the same as no holder at all. Resolving
+    who holds the grab goes through a name lookup that raises for a window the
+    toolkit created on its own — a posted combobox popdown is one — and there is
+    nothing to hand back to a window we cannot name. This runs on the SETUP path,
+    where a raise would escape into the application, so it degrades to `None` and
+    logs rather than propagating.
+    """
+    try:
+        holder = widget.grab_current()
+    except (AttributeError, KeyError, tkinter.TclError):
+        _log_grab_failure("could not identify the current grab holder")
+        return None
+    if holder is None:
+        return None
+    try:
+        kind = holder.grab_status()
+    except (AttributeError, tkinter.TclError):
+        # Fall back to the narrower grab rather than guessing global.
+        kind = "local"
+    return (holder, kind)
+
+
+def restore_grab(previous: tuple[Any, str | None] | None) -> None:
+    """Hand the modal grab back to whatever held it before the caller took it.
+
+    Tk releases a grab when the window holding it is destroyed, but it does NOT
+    restore the grab that window displaced. So a modal opened from inside
+    another modal — `bs.alert()` from a dialog button command, or a
+    `bs.Window(modal=True)` opened from a dialog's "Advanced..." button — took
+    the grab over and then dropped it on the floor when it closed. The OUTER
+    window was left on screen and still blocking its caller, yet holding no
+    grab at all: the user could click straight back into the main window and
+    drive the app underneath it, against something that was modal in appearance
+    only (issue #440 for dialogs, #444 for windows).
+
+    Pass the token `capture_grab()` returned. `None` means nothing held the
+    grab, which is the outermost case and needs no restore.
+
+    A failure here is deliberately swallowed. This runs on a teardown path,
+    where the previous holder may itself have been destroyed while the inner
+    window was up, or the whole interpreter may be going down — and something
+    that has already closed must not raise on its way out. It is LOGGED rather
+    than passed over in silence, because a failed restore is the very defect
+    this function exists to prevent: the outer window stays on screen holding
+    nothing.
+
+    ⚠ A global restore can fail where a local one cannot — `grab set -global`
+    is the call Tk's viewability rule guards, and on X11 it can also lose to
+    another client. That is the one way this is riskier than always restoring
+    a local grab, so a failed global restore DEGRADES TO LOCAL rather than to
+    nothing: modal within the application is imperfect, but it is not the #440
+    symptom.
+    """
+    if previous is None:
+        return
+    holder, kind = previous
+    try:
+        if not holder.winfo_exists():
+            return
+        if kind == "global":
+            try:
+                holder.grab_set_global()
+            except tkinter.TclError:
+                _log_grab_failure("could not restore a global grab; falling back to local")
+                holder.grab_set()
+        else:
+            holder.grab_set()
+    except (AttributeError, tkinter.TclError):
+        _log_grab_failure("could not restore the previous grab holder")
+
+
+def _log_grab_failure(message: str) -> None:
+    """Report a grab failure without ever raising from a teardown path."""
+    from bootstack._runtime.utility import debug_log_exception
+
+    debug_log_exception(message)

{bootstack-0.3.2 → bootstack-0.4.0}/src/bootstack/_runtime/toplevel.py

@@ -7,6 +7,7 @@ from typing import Any, Callable, Literal, Optional, Tuple
 
 from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
 from bootstack._runtime.base_window import BaseWindow
+from bootstack._runtime.grab import capture_grab, restore_grab
 
 
 class Toplevel(BaseWindow, WidgetCapabilitiesMixin, tkinter.Toplevel):
@@ -15,10 +16,6 @@ class Toplevel(BaseWindow, WidgetCapabilitiesMixin, tkinter.Toplevel):
     This class wraps `tkinter.Toplevel` and adds bootstack window conveniences
     (title/geometry helpers, centering, alpha/topmost/toolwindow helpers, etc.).
 
-    The standard widget API (events, scheduling, clipboard, geometry managers,
-    winfo, etc.) is available through inheritance and is documented under
-    bootstack capabilities.
-
     For additional information on the underlying Tk/Tkinter behavior, see:
         - Tcl/Tk `toplevel` command documentation
         - Python `tkinter.Toplevel` documentation
@@ -107,6 +104,10 @@ class Toplevel(BaseWindow, WidgetCapabilitiesMixin, tkinter.Toplevel):
         # modal level — stored for use in show()
         self._modal = modal
 
+        # Grab handed back when this window is destroyed; see show().
+        self._previous_grab: tuple[Any, str | None] | None = None
+        self._grab_restore_bound = False
+
         # Apply Aqua MacWindowStyle BEFORE any setup that might pump the
         # event loop (icons, geometry, update_idletasks). Tk's docs require
         # the style to be set on a freshly-created, never-mapped window;
@@ -223,15 +224,60 @@ class Toplevel(BaseWindow, WidgetCapabilitiesMixin, tkinter.Toplevel):
         """Show the window and apply modal grab if configured."""
         super().show()
         if self._modal:
+            # Remember who held the grab, and how, so it can be handed back when
+            # this window goes away. Tk drops a grab on destroy but never
+            # restores the one it displaced, so a modal opened from inside
+            # another modal used to leave its opener on screen, still blocking
+            # its caller, holding nothing at all (#444 — #440 fixed the same
+            # defect on the dialog path). Captured BEFORE the grab: once another
+            # window grabs, the previous holder's grab_status() reads None.
+            #
+            # Captured ONCE. show() is re-callable — show(anchor_to=) re-anchors
+            # an open window and block_until_closed() shows it itself — and a
+            # later capture finds this window already holding the grab, so it
+            # would record the window as its own previous holder.
+            if not self._grab_restore_bound:
+                self._previous_grab = capture_grab(self)
             try:
                 if self._modal == "app":
                     self.grab_set_global()
                 else:
                     self.grab_set()
+            except tkinter.TclError:
+                pass
+            else:
+                # Owed because the grab was TAKEN, so bound off the grab alone —
+                # focus gets its own guard rather than standing between the two.
+                self._bind_grab_restore()
+            try:
                 self.focus_set()
             except tkinter.TclError:
                 pass
 
+    def _bind_grab_restore(self) -> None:
+        """Hand the displaced grab back when this window is destroyed.
+
+        Bound on destroy rather than paired around `block_until_closed()`,
+        because a modal window does not have to block — `show()` followed by a
+        later `destroy()` is an ordinary path, and pairing on the blocking one
+        alone would leave it unfixed. Measured before choosing it: the restore
+        wins its race with Tk's own grab release, so `grab_current()` reads the
+        opener again once the dust settles
+        (`development/probe_444_grab_restore_ordering.py`).
+        """
+        if self._grab_restore_bound:
+            return
+        self._grab_restore_bound = True
+
+        def _restore(event: Any) -> None:
+            # <Destroy> fires for every descendant, not just the window.
+            if event.widget is not self:
+                return
+            restore_grab(self._previous_grab)
+            self._previous_grab = None
+
+        self.bind("<Destroy>", _restore, add="+")
+
     # -------------------------------------------------------------------------
     # result property + block_until_closed()
     # -------------------------------------------------------------------------