backlogops-gui 0.1__py3-none-any.whl

backlogops_gui/backlog_window.py

@@ -0,0 +1,435 @@
+#! /usr/local/bin/python3
+"""A window that shows one backlog and its releases as two tables.
+
+The window shows the backlog and the releases as two read-only tables and
+carries a menu with the actions that can be done to the backlog. The
+backlog table fills the window, while the releases table, which has only a
+few columns, is kept narrow so its columns are not spread out. The first
+version offers saving to a file and closing the window. Saving is kept in a
+module function so it can be tested without a display.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import tkinter as tk
+from datetime import timedelta
+from tkinter import messagebox, ttk
+from typing import Callable, Optional, TextIO
+from tableio import ValueFmt
+from backlogops import (
+    AvailableTeams, BacklogReleases, OutputFormatConfig, ReleaseChanges,
+    ReleaseDateChanges, format_content_changes, format_date_changes,
+    get_keys_in_order, write_content_changes, write_date_changes,
+    write_key_list)
+from backlogops_gui.backlog_io import write_backlog
+from backlogops_gui.io_dialogs import (
+    ask_buffer_days, ask_dep_options, ask_keys, ask_levels, ask_start_date,
+    ask_write_options, choose_changes_output, choose_key_list_output,
+    choose_output_file, show_change_list)
+from backlogops_gui.table_view import (
+    backlog_table, make_table, release_table)
+
+WRITE_ERRORS = (ValueError, TypeError, KeyError, OSError)
+ACTION_ERRORS = (ValueError, TypeError, KeyError, RuntimeError, OSError)
+RELEASE_COLUMN_WIDTH = 110
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def save_backlog(parent: tk.Misc, data: BacklogReleases,
+                 presets: Optional[dict[str, OutputFormatConfig]],
+                 sink: TextIO, on_error: Callable[[str, str], None],
+                 on_info: Callable[[str, str], None]) -> None:
+    """Ask where and how to save a backlog and write it.
+
+    Args:
+        parent: The window the dialogs are shown over.
+        data: The backlog and releases to write.
+        presets: Named output presets, or None when none are configured.
+        sink: Stream that receives low-level write diagnostics.
+        on_error: Callback used to report a write failure.
+        on_info: Callback used to report a successful write.
+    """
+    path = choose_output_file(parent)
+    if path is None:
+        return
+    names = sorted(presets) if presets else None
+    options = ask_write_options(parent, names)
+    if options is None:
+        return
+    try:
+        write_backlog(data, path, options.config_value, presets,
+                      options.releases_first, sink)
+    except WRITE_ERRORS as error:
+        on_error('Could not write file', str(error))
+        return
+    on_info('Wrote file', f'Wrote {path}')
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def _apply_change(change: Callable[[], None], refresh: Callable[[], None],
+                  on_error: Callable[[str, str], None],
+                  on_info: Callable[[str, str], None], fail_title: str,
+                  ok_title: str, ok_message: str) -> None:
+    """Run a backlog change, refresh the view and report the outcome.
+
+    A change that raises one of the known data errors is reported through
+    ``on_error`` and leaves the view unchanged. A successful change
+    refreshes the view and is reported through ``on_info``.
+    """
+    try:
+        change()
+    except ACTION_ERRORS as error:
+        on_error(fail_title, str(error))
+        return
+    refresh()
+    on_info(ok_title, ok_message)
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def order_by_keys(parent: tk.Misc, data: BacklogReleases, sink: TextIO,
+                  refresh: Callable[[], None],
+                  on_error: Callable[[str, str], None],
+                  on_info: Callable[[str, str], None]) -> None:
+    """Ask for leading keys and move those items to the front."""
+    keys = ask_keys(parent, sink)
+    if keys is None:
+        return
+    _apply_change(lambda: data.move_keys_first(keys, sink), refresh, on_error,
+                  on_info, 'Could not order by keys', 'Ordered backlog',
+                  'Moved the keys to the front.')
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def order_by_deps(parent: tk.Misc, data: BacklogReleases, sink: TextIO,
+                  refresh: Callable[[], None],
+                  on_error: Callable[[str, str], None],
+                  on_info: Callable[[str, str], None]) -> None:
+    """Ask for the options and order the backlog by dependencies."""
+    options = ask_dep_options(parent)
+    if options is None:
+        return
+    later, mode = options.later, options.mode
+    space = options.space_around
+
+    def change() -> None:
+        """Order the backlog by dependencies with the chosen options."""
+        data.order_by_dependencies(later=later, mode=mode, space_around=space,
+                                   stderr_file=sink)
+    _apply_change(change, refresh, on_error, on_info,
+                  'Could not order by dependencies', 'Ordered backlog',
+                  'Ordered the backlog by dependencies.')
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def save_changes(parent: tk.Misc,
+                 write_changes: Optional[Callable[[str], None]],
+                 on_error: Callable[[str, str], None],
+                 on_info: Callable[[str, str], None]) -> None:
+    """Ask for a file and write the change list to it.
+
+    A ``write_changes`` of None means there are no changes, so nothing is
+    written and that is reported through ``on_info`` instead.
+    """
+    if write_changes is None:
+        on_info('No changes', 'There are no changes to write.')
+        return
+    path = choose_changes_output(parent)
+    if path is None:
+        return
+    try:
+        write_changes(path)
+    except WRITE_ERRORS as error:
+        on_error('Could not write file', str(error))
+        return
+    on_info('Wrote file', f'Wrote {path}')
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def show_changes(parent: tk.Misc, title: str, text: str,
+                 write_changes: Optional[Callable[[str], None]],
+                 on_error: Callable[[str, str], None],
+                 on_info: Callable[[str, str], None]) -> None:
+    """Show the change listing in a pop-up that can save it to a file."""
+    show_change_list(parent, title, text,
+                     lambda: save_changes(parent, write_changes, on_error,
+                                          on_info))
+
+
+def _date_report(changes: ReleaseDateChanges, sink: TextIO
+                 ) -> tuple[str, Optional[Callable[[str], None]]]:
+    """Return the date change listing and a writer, None when empty."""
+    writer = None if not changes else \
+        (lambda path: write_date_changes(changes, path, sink))
+    return format_date_changes(changes), writer
+
+
+def _content_report(changes: ReleaseChanges, sink: TextIO
+                    ) -> tuple[str, Optional[Callable[[str], None]]]:
+    """Return the content change listing and a writer, None when empty."""
+    writer = None if not changes else \
+        (lambda path: write_content_changes(changes, path, sink))
+    return format_content_changes(changes), writer
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def _run_change(parent: tk.Misc,
+                change: Callable[[], tuple[str,
+                                           Optional[Callable[[str], None]]]],
+                refresh: Callable[[], None],
+                on_error: Callable[[str, str], None],
+                on_info: Callable[[str, str], None], fail_title: str,
+                title: str) -> None:
+    """Run a change returning a report, refresh, then show the pop-up.
+
+    A change that raises one of the known data errors is reported and
+    leaves the view unchanged. A successful change refreshes the view and
+    shows the change listing in a pop-up that can save it to a file.
+    """
+    try:
+        text, write_changes = change()
+    except ACTION_ERRORS as error:
+        on_error(fail_title, str(error))
+        return
+    refresh()
+    show_changes(parent, title, text, write_changes, on_error, on_info)
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def estimate_date(parent: tk.Misc, data: BacklogReleases,
+                  teams: Optional[AvailableTeams], sink: TextIO,
+                  refresh: Callable[[], None],
+                  on_error: Callable[[str, str], None],
+                  on_info: Callable[[str, str], None]) -> None:
+    """Ask for the start date and estimate the ready dates."""
+    if teams is None:
+        on_error('No configuration',
+                 'There is no teams configuration to estimate from.')
+        return
+    choice = ask_start_date(parent)
+    if choice is None:
+        return
+    ready_teams, start = teams, choice.start_date
+
+    def change() -> tuple[str, Optional[Callable[[str], None]]]:
+        """Estimate the dates and return the release date change report."""
+        changes = data.estimate_ready_date(ready_teams, start, sink)
+        return _date_report(changes, sink)
+    _run_change(parent, change, refresh, on_error, on_info,
+                'Could not estimate ready date', 'Release date changes')
+
+
+def set_plan(data: BacklogReleases, sink: TextIO, refresh: Callable[[], None],
+             on_error: Callable[[str, str], None],
+             on_info: Callable[[str, str], None]) -> None:
+    """Copy the estimated ready dates to the planned ready dates."""
+    _apply_change(lambda: data.set_plan_from_estimate(sink), refresh, on_error,
+                  on_info, 'Could not set planned date', 'Set planned date',
+                  'Copied the estimated dates to the planned dates.')
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def adjust_content(parent: tk.Misc, data: BacklogReleases, sink: TextIO,
+                   refresh: Callable[[], None],
+                   on_error: Callable[[str, str], None],
+                   on_info: Callable[[str, str], None]) -> None:
+    """Ask for a buffer and adjust the release content to the estimate."""
+    days = ask_buffer_days(parent)
+    if days is None:
+        return
+
+    def change() -> tuple[str, Optional[Callable[[str], None]]]:
+        """Adjust the release content and return the change report."""
+        changes = data.adjust_release_content(timedelta(days=days), sink)
+        return _content_report(changes, sink)
+    _run_change(parent, change, refresh, on_error, on_info,
+                'Could not adjust release content', 'Release content changes')
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments
+def plan_dates(parent: tk.Misc, data: BacklogReleases, sink: TextIO,
+               refresh: Callable[[], None],
+               on_error: Callable[[str, str], None],
+               on_info: Callable[[str, str], None]) -> None:
+    """Ask for a buffer and set planned release dates from the estimate."""
+    days = ask_buffer_days(parent)
+    if days is None:
+        return
+
+    def change() -> tuple[str, Optional[Callable[[str], None]]]:
+        """Set the planned release dates and return the change report."""
+        changes = data.release_plan_on_estimate(timedelta(days=days), sink)
+        return _date_report(changes, sink)
+    _run_change(parent, change, refresh, on_error, on_info,
+                'Could not set planned release dates', 'Release date changes')
+
+
+def extract_keys(parent: tk.Misc, data: BacklogReleases, sink: TextIO,
+                 on_error: Callable[[str, str], None],
+                 on_info: Callable[[str, str], None]) -> None:
+    """Ask for levels and a file, then write the backlog keys to it."""
+    levels = ask_levels(parent)
+    if levels is None:
+        return
+    path = choose_key_list_output(parent)
+    if path is None:
+        return
+    try:
+        keys = get_keys_in_order(data.backlog, levels)
+        write_key_list(keys, path, stderr_file=sink)
+    except ACTION_ERRORS as error:
+        on_error('Could not extract keys', str(error))
+        return
+    on_info('Wrote keys', f'Wrote {path}')
+
+
+# pylint: disable-next=too-few-public-methods,too-many-instance-attributes
+class BacklogWindow:
+    """A top-level window showing one backlog and its releases."""
+
+    # pylint: disable-next=too-many-arguments,too-many-positional-arguments
+    def __init__(self, root: tk.Misc, data: BacklogReleases, title: str,
+                 presets: Callable[
+                     [], Optional[dict[str, OutputFormatConfig]]],
+                 teams: Callable[[], Optional[AvailableTeams]],
+                 sink: TextIO) -> None:
+        """Build the window, its menu and the two tables.
+
+        Args:
+            root: The parent window the new window belongs to.
+            data: The backlog and releases to show.
+            title: The window title, typically the source file name.
+            presets: Callable returning the current output presets.
+            teams: Callable returning the loaded teams configuration.
+            sink: Stream that receives low-level write diagnostics.
+        """
+        self._data = data
+        self._presets = presets
+        self._teams = teams
+        self._sink = sink
+        self._win = tk.Toplevel(root)
+        self._win.title(title)
+        self._tables: list[tk.Widget] = []
+        self._add_menu()
+        self._build_tables()
+
+    def _report_error(self, title: str, message: str) -> None:
+        """Show an error message over this backlog window."""
+        messagebox.showerror(title, message, parent=self._win)
+
+    def _report_info(self, title: str, message: str) -> None:
+        """Show an informational message over this backlog window."""
+        messagebox.showinfo(title, message, parent=self._win)
+
+    def _build_tables(self) -> None:
+        """Build the backlog and releases tables from the current data."""
+        self._tables.append(
+            self._add_table('Backlog', *backlog_table(self._data),
+                            narrow=False))
+        self._tables.append(
+            self._add_table('Releases', *release_table(self._data),
+                            narrow=True))
+
+    def _refresh_tables(self) -> None:
+        """Rebuild the tables after the backlog data has changed."""
+        for table in self._tables:
+            table.destroy()
+        self._tables = []
+        self._build_tables()
+
+    def _add_menu(self) -> None:
+        """Add the backlog menu with the action, save and close items."""
+        menubar = tk.Menu(self._win)
+        backlog_menu = tk.Menu(menubar, tearoff=False)
+        self._add_actions(backlog_menu)
+        backlog_menu.add_separator()
+        backlog_menu.add_command(label='Save to file…', command=self._save)
+        backlog_menu.add_command(label='Close', command=self._win.destroy)
+        menubar.add_cascade(label='Backlog', menu=backlog_menu)
+        self._win.config(menu=menubar)
+
+    def _add_actions(self, menu: tk.Menu) -> None:
+        """Add the backlog operation items to the menu."""
+        menu.add_command(label='Order by keys…', command=self._order_by_keys)
+        menu.add_command(label='Order by dependencies…',
+                         command=self._order_by_deps)
+        menu.add_command(label='Estimate ready date…',
+                         command=self._estimate_date)
+        menu.add_command(label='Set planned date from estimated',
+                         command=self._set_plan)
+        menu.add_command(label='Adjust release content…',
+                         command=self._adjust_content)
+        menu.add_command(label='Adjust planned release dates…',
+                         command=self._plan_dates)
+        menu.add_command(label='Extract keys…', command=self._extract_keys)
+
+    def _add_table(self, heading: str, columns: list[str],
+                   rows: list[list[ValueFmt]], narrow: bool) -> tk.Widget:
+        """Add one labeled, scrollable table and return its frame.
+
+        The narrow table keeps its few columns at a fixed width and does
+        not take the spare space, so it stays clearly narrower than the
+        backlog table that fills the window.
+        """
+        frame = tk.LabelFrame(self._win, text=heading)
+        tree = self._make_tree(frame, columns, rows, narrow)
+        scroll = ttk.Scrollbar(frame, orient='vertical', command=tree.yview)
+        tree.configure(yscrollcommand=scroll.set)
+        scroll.pack(side='right', fill='y')
+        if narrow:
+            frame.pack(padx=8, pady=6, anchor='w')
+            tree.pack(side='left')
+        else:
+            frame.pack(padx=8, pady=6, fill='both', expand=True)
+            tree.pack(side='left', fill='both', expand=True)
+        return frame
+
+    @staticmethod
+    def _make_tree(frame: tk.Misc, columns: list[str],
+                   rows: list[list[ValueFmt]], narrow: bool) -> ttk.Treeview:
+        """Build the Treeview, keeping a narrow table from stretching."""
+        if narrow:
+            return make_table(frame, columns, rows, width=RELEASE_COLUMN_WIDTH,
+                              stretch=False)
+        return make_table(frame, columns, rows)
+
+    def _save(self) -> None:
+        """Save the backlog through the shared save helper."""
+        save_backlog(self._win, self._data, self._presets(), self._sink,
+                     self._report_error, self._report_info)
+
+    def _order_by_keys(self) -> None:
+        """Order the backlog by leading keys and refresh the tables."""
+        order_by_keys(self._win, self._data, self._sink, self._refresh_tables,
+                      self._report_error, self._report_info)
+
+    def _order_by_deps(self) -> None:
+        """Order the backlog by dependencies and refresh the tables."""
+        order_by_deps(self._win, self._data, self._sink, self._refresh_tables,
+                      self._report_error, self._report_info)
+
+    def _estimate_date(self) -> None:
+        """Estimate the ready dates and refresh the tables."""
+        estimate_date(self._win, self._data, self._teams(), self._sink,
+                      self._refresh_tables, self._report_error,
+                      self._report_info)
+
+    def _set_plan(self) -> None:
+        """Copy the estimated dates to the planned dates and refresh."""
+        set_plan(self._data, self._sink, self._refresh_tables,
+                 self._report_error, self._report_info)
+
+    def _adjust_content(self) -> None:
+        """Adjust the release content to the estimate and refresh."""
+        adjust_content(self._win, self._data, self._sink, self._refresh_tables,
+                       self._report_error, self._report_info)
+
+    def _plan_dates(self) -> None:
+        """Set planned release dates from the estimate and refresh."""
+        plan_dates(self._win, self._data, self._sink, self._refresh_tables,
+                   self._report_error, self._report_info)
+
+    def _extract_keys(self) -> None:
+        """Extract backlog keys at chosen levels to a key list file."""
+        extract_keys(self._win, self._data, self._sink, self._report_error,
+                     self._report_info)

backlogops_gui/gui_wizard.py

@@ -0,0 +1,237 @@
+#! /usr/local/bin/python3
+"""Graphical bridge that drives the synchronous teams wizard.
+
+The teams configuration wizard asks its questions through a
+:class:`WizardUiBridge`, extended here as a :class:`YesNoUiBridge` so
+yes/no questions can offer dedicated buttons. This module answers every
+call by updating one reused, fixed-size window, so the whole wizard session
+happens in a single pop-up that does not jump around the display. A
+cancelled prompt raises :class:`EOFError`, which the wizard documents as
+the way an interrupted input is reported.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import tkinter as tk
+from typing import Callable, Optional, Sequence, TextIO
+from backlogops import NoTextIO, YesNoUiBridge
+
+WIZARD_TITLE = 'Configuration wizard'
+WINDOW_SIZE = '560x460'
+WRAP_LENGTH = 500
+MESSAGE_HEIGHT = 8
+CHOICE_HEIGHT = 10
+CANCEL_TEXT = 'Configuration wizard cancelled by the user.'
+
+
+class _WizardWindow:
+    """One reused window that asks every wizard prompt in turn."""
+
+    def __init__(self, parent: tk.Misc) -> None:
+        """Create the fixed-size window and its lasting message area."""
+        self._result: object = ''
+        self._cancelled = False
+        self._win = tk.Toplevel(parent)
+        self._win.title(WIZARD_TITLE)
+        self._win.geometry(WINDOW_SIZE)
+        self._win.resizable(False, False)
+        if isinstance(parent, tk.Wm):
+            self._win.transient(parent)
+        self._win.protocol('WM_DELETE_WINDOW', self._cancel)
+        self._done = tk.IntVar(self._win, 0)
+        self._messages = self._build_messages()
+        self._content = tk.Frame(self._win)
+        self._content.pack(fill='both', expand=True, padx=12, pady=6)
+        self._win.grab_set()
+
+    def _build_messages(self) -> tk.Text:
+        """Build the read-only area that keeps the wizard messages."""
+        text = tk.Text(self._win, height=MESSAGE_HEIGHT, wrap='word',
+                       state='disabled')
+        text.pack(fill='x', padx=12, pady=(12, 6))
+        return text
+
+    def show(self, message: str) -> None:
+        """Append one lasting message to the message area."""
+        self._messages.configure(state='normal')
+        self._messages.insert('end', message + '\n')
+        self._messages.see('end')
+        self._messages.configure(state='disabled')
+
+    def close(self) -> None:
+        """Destroy the wizard window."""
+        self._win.destroy()
+
+    def ask(self, question: str, re_ask: Optional[str],
+            choices: Optional[Sequence[str]]) -> str | int:
+        """Ask one free-text or choice question and return the answer."""
+        if choices is None:
+            return self._ask_text(question, re_ask)
+        return self._ask_choice(question, re_ask, choices)
+
+    def ask_yes_no(self, question: str, default: bool) -> bool:
+        """Ask one yes/no question with dedicated buttons."""
+        self._begin(question, None)
+        box = tk.Frame(self._content)
+        box.pack(pady=10)
+        yes = tk.Button(box, text='Yes', command=lambda: self._finish(True))
+        no = tk.Button(box, text='No', command=lambda: self._finish(False))
+        yes.pack(side='left', padx=6)
+        no.pack(side='left', padx=6)
+        chosen = yes if default else no
+        chosen.focus_set()
+        self._win.bind('<Return>', lambda event: chosen.invoke())
+        result = self._wait()
+        assert isinstance(result, bool)
+        return result
+
+    def _ask_text(self, question: str, re_ask: Optional[str]) -> str:
+        """Ask one free-text question and return the entered text."""
+        self._begin(question, re_ask)
+        entry = tk.Entry(self._content, width=44)
+        entry.pack(anchor='w', pady=6)
+        entry.focus_set()
+        self._add_buttons(lambda: self._finish(entry.get()), None)
+        self._win.bind('<Return>', lambda event: self._finish(entry.get()))
+        result = self._wait()
+        assert isinstance(result, str)
+        return result
+
+    def _ask_choice(self, question: str, re_ask: Optional[str],
+                    choices: Sequence[str]) -> str | int:
+        """Ask one question with a single-selection list of choices."""
+        self._begin(question, re_ask)
+        listbox = tk.Listbox(self._content, exportselection=False,
+                             height=min(len(choices), CHOICE_HEIGHT))
+        for choice in choices:
+            listbox.insert('end', choice)
+        listbox.pack(fill='x', pady=6)
+        self._add_buttons(lambda: self._pick(listbox),
+                          lambda: self._finish(''))
+        result = self._wait()
+        assert isinstance(result, (str, int))
+        return result
+
+    def _pick(self, listbox: tk.Listbox) -> None:
+        """Finish a choice question with the selected zero-based index."""
+        picks = listbox.curselection()  # type: ignore[no-untyped-call]
+        if picks:
+            self._finish(int(picks[0]))
+
+    def _begin(self, question: str, re_ask: Optional[str]) -> None:
+        """Clear the content area and show the question and any reason."""
+        self._win.unbind('<Return>')
+        for child in self._content.winfo_children():
+            child.destroy()
+        if re_ask is not None:
+            self._add_label(re_ask, 'red')
+        self._add_label(question, 'black')
+
+    def _add_label(self, text: str, color: str) -> None:
+        """Add one wrapped label to the content area."""
+        label = tk.Label(self._content, text=text, fg=color,
+                         wraplength=WRAP_LENGTH, justify='left')
+        label.pack(anchor='w', pady=4)
+
+    def _add_buttons(self, on_ok: Callable[[], None],
+                     on_default: Optional[Callable[[], None]]) -> None:
+        """Add the confirm, optional default, and cancel buttons."""
+        box = tk.Frame(self._content)
+        box.pack(anchor='w', pady=10)
+        ok_button = tk.Button(box, text='OK', command=on_ok)
+        ok_button.pack(side='left')
+        if on_default is not None:
+            default_button = tk.Button(box, text='Use default',
+                                       command=on_default)
+            default_button.pack(side='left', padx=6)
+        cancel_button = tk.Button(box, text='Cancel', command=self._cancel)
+        cancel_button.pack(side='left', padx=6)
+
+    def _wait(self) -> object:
+        """Block until the current prompt is answered or cancelled."""
+        self._win.wait_variable(self._done)
+        if self._cancelled:
+            raise EOFError(CANCEL_TEXT)
+        return self._result
+
+    def _finish(self, value: object) -> None:
+        """Store the answer and release the waiting prompt."""
+        self._result = value
+        self._done.set(self._done.get() + 1)
+
+    def _cancel(self) -> None:
+        """Mark the session cancelled and release the waiting prompt."""
+        self._cancelled = True
+        self._done.set(self._done.get() + 1)
+
+
+class TkWizardBridge(YesNoUiBridge):
+    """Bridge that answers wizard prompts in one reused Tkinter window."""
+
+    # pylint: disable-next=too-many-arguments,too-many-positional-arguments
+    def __init__(self, parent: tk.Misc, log: Optional[TextIO] = None,
+                 ask_fn: Optional[Callable[
+                     [str, Optional[str], Optional[Sequence[str]]],
+                     str | int]] = None,
+                 show_fn: Optional[Callable[[str], None]] = None,
+                 yes_no_fn: Optional[Callable[[str, bool], bool]] = None
+                 ) -> None:
+        """Store the parent window, log sink, and optional test callables.
+
+        Args:
+            parent: The window the wizard window is shown over.
+            log: Stream that receives low-level wizard diagnostics.
+            ask_fn: Replacement for the question prompt, used by tests.
+            show_fn: Replacement for the message display, used by tests.
+            yes_no_fn: Replacement for the yes/no prompt, used by tests.
+        """
+        self._parent = parent
+        self._log = log
+        self._window: Optional[_WizardWindow] = None
+        self._ask = ask_fn
+        self._show = show_fn
+        self._yes_no = yes_no_fn
+
+    def ask(self, question: str, re_ask_reason: Optional[str] = None,
+            choices: Optional[Sequence[str]] = None) -> str | int:
+        """Ask one question and return the user's answer.
+
+        Returns the entered text, the zero-based index of a selected
+        choice, or an empty string when the user requests the default.
+
+        Raises:
+            EOFError: The user cancelled the wizard.
+        """
+        if self._ask is not None:
+            return self._ask(question, re_ask_reason, choices)
+        return self._window_obj().ask(question, re_ask_reason, choices)
+
+    def ask_yes_no(self, question: str, default: bool) -> bool:
+        """Ask one yes/no question with dedicated buttons."""
+        if self._yes_no is not None:
+            return self._yes_no(question, default)
+        return self._window_obj().ask_yes_no(question, default)
+
+    def show(self, message: str) -> None:
+        """Show an informational message to the user."""
+        if self._show is not None:
+            self._show(message)
+            return
+        self._window_obj().show(message)
+
+    def error_file(self) -> TextIO:
+        """Return the stream used for low-level wizard diagnostics."""
+        return self._log if self._log is not None else NoTextIO()
+
+    def close(self) -> None:
+        """Close the wizard window when one was opened."""
+        if self._window is not None:
+            self._window.close()
+            self._window = None
+
+    def _window_obj(self) -> _WizardWindow:
+        """Return the wizard window, creating it on first use."""
+        if self._window is None:
+            self._window = _WizardWindow(self._parent)
+        return self._window