tk-uia 0.6.3__py3-none-any.whl

tk_uia/__init__.py

@@ -0,0 +1,224 @@
+"""tk-uia: make Tkinter widgets visible to Windows accessibility clients.
+
+Tk 8.6 gives every widget an empty accessible name and mostly the wrong control
+type. `enable(root)` annotates each widget through MSAA, which Windows bridges
+to UI Automation. Importing this reaches for neither `tkinter` nor
+`ctypes.windll`, so the platform is untouched until `enable()` runs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+from tk_uia.annotate import (
+    AnnotationRefused,
+    Annotator,
+    InertAnnotator,
+    Installation,
+)
+from tk_uia.describe import Description, Gap, WidgetDescription
+from tk_uia.describe import describe as _describe
+from tk_uia.layout import NamedByTheLayout
+from tk_uia.layout import infer_names_from_layout as _names_the_layout_implies
+from tk_uia.roles import ROLE_FOR_TK_CLASS, Role
+from tk_uia.tkversion import Strategy
+
+if TYPE_CHECKING:
+    import tkinter
+
+__version__ = "0.6.3"
+
+__all__ = [
+    "ROLE_FOR_TK_CLASS",
+    "AnnotationRefused",
+    "Description",
+    "Gap",
+    "NamedByTheLayout",
+    "Role",
+    "Strategy",
+    "WidgetDescription",
+    "__version__",
+    "add_acc_object",
+    "bind_text_variable",
+    "bind_value_variable",
+    "check_screenreader",
+    "describe",
+    "enable",
+    "forget",
+    "infer_names_from_layout",
+    "label_for",
+    "set_acc_action",
+    "set_acc_description",
+    "set_acc_help",
+    "set_acc_name",
+    "set_acc_role",
+    "set_acc_state",
+    "set_acc_value",
+    "set_automation_id",
+]
+
+_installed: Installation | None = None
+
+
+def enable(root: tkinter.Misc, *, roles: Mapping[str, Role] | None = None) -> Strategy:
+    """Annotate this application's widgets, and say which way it went.
+
+    Idempotent: a second call reports what the first one did and installs
+    nothing further. One installation covers every window the application opens.
+    """
+    global _installed
+    if _installed is not None:
+        return _installed.strategy
+    from tk_uia._accprop import AccPropServicesStore
+    from tk_uia._overlay import Win32Overlays
+    from tk_uia._tkstrip import TkTabStrip, is_a_notebook
+    from tk_uia._tkvars import a_variable_the_application_owns
+    from tk_uia.annotate import install
+    from tk_uia.tabs import Notebooks, TabHandles
+
+    store = AccPropServicesStore()
+    notebooks = Notebooks(
+        TabHandles(store, Win32Overlays()),
+        lambda widget: TkTabStrip(widget) if is_a_notebook(widget) else None,
+    )
+    _installed = install(root, store, roles, notebooks, a_variable_the_application_owns)
+    return _installed.strategy
+
+
+def add_acc_object(widget: tkinter.Misc) -> None:
+    """Annotate one widget now, re-reading its class, its `-text` and its tabs.
+
+    Needed after `config(text=...)`, and after a tab is added, removed or
+    renamed: Tk announces neither, so nothing re-annotates without this call.
+    """
+    _annotator().add(widget)
+    _the_installation().tabs.refresh(widget)
+
+
+def set_acc_role(widget: tkinter.Misc, role: Role) -> None:
+    """Say what kind of control this is, overriding the inferred role."""
+    _annotator().set_role(widget, role)
+
+
+def set_acc_name(widget: tkinter.Misc, name: str) -> None:
+    """Say what a screen reader should call this widget.
+
+    Raises `AnnotationRefused` for a toplevel, which `wm title` names instead.
+    """
+    _annotator().set_name(widget, name)
+
+
+def label_for(label: tkinter.Misc, widget: tkinter.Misc) -> None:
+    """Say that this label is the caption for that widget, and name it accordingly.
+
+    `label_for(tk.Label(text="Host:"), entry)` names the entry `'Host'`, and
+    follows the label's `-textvariable` where it declares one. A label showing
+    nothing at all raises `AnnotationRefused`.
+    """
+    _annotator().label_for(label, widget)
+
+
+def infer_names_from_layout(root: tkinter.Misc) -> tuple[NamedByTheLayout, ...]:
+    """Name what the layout of this window says its controls are, and report what it did.
+
+    A guess read off the widgets *around* each control, which is why `enable()`
+    does not do it. Nothing an application named itself is touched.
+    """
+    return _names_the_layout_implies(root, _the_installation())
+
+
+def set_acc_value(widget: tkinter.Misc, value: str) -> None:
+    """Say what a client reads out of this widget, as an edit control's contents."""
+    _annotator().set_value(widget, value)
+
+
+def set_acc_description(widget: tkinter.Misc, description: str) -> None:
+    """Say more about this widget than its name has room for."""
+    _annotator().set_description(widget, description)
+
+
+def set_acc_action(widget: tkinter.Misc, action: str) -> None:
+    """Say what activating this widget would do, as a verb ("Press").
+
+    Advertising it does not make it activatable: `InvokePattern` on a Tk button
+    returns cleanly and presses nothing.
+    """
+    _annotator().set_action(widget, action)
+
+
+def set_acc_help(widget: tkinter.Misc, help_text: str) -> None:
+    """Say what a client should offer as this widget's help text."""
+    _annotator().set_help(widget, help_text)
+
+
+def set_acc_state(widget: tkinter.Misc, state: int) -> None:
+    """Say what state this widget is in, as `oleacc.h`'s `STATE_SYSTEM_*` bits.
+
+    Written once and never tracked: nothing here notices a widget being
+    disabled or re-enabled.
+    """
+    _annotator().set_state(widget, state)
+
+
+def bind_text_variable(widget: tkinter.Misc, variable: tkinter.Variable) -> None:
+    """Keep a widget's accessible name in step with a variable of your choosing.
+
+    Replaces the binding `enable()` made from the widget's own `-textvariable`
+    rather than joining it.
+    """
+    _annotator().bind_text_variable(widget, variable)
+
+
+def bind_value_variable(widget: tkinter.Misc, variable: tkinter.Variable) -> None:
+    """Keep a widget's accessible value in step with a variable of your choosing."""
+    _annotator().bind_value_variable(widget, variable)
+
+
+def set_automation_id(widget: tkinter.Misc, automation_id: int) -> None:
+    """Give this widget a stable id for a test suite to pin a locator to.
+
+    Writes `GWLP_ID`, the control id Win32 puts in `WM_COMMAND.wParam`; a
+    non-zero existing id raises `AnnotationRefused` rather than being overwritten.
+    """
+    _annotator().set_automation_id(widget, automation_id)
+
+
+def forget(widget: tkinter.Misc | str) -> None:
+    """Take every annotation back off a widget, and stop following its variables.
+
+    Takes the widget or its Tk path, since `<Destroy>` carries only the path
+    once the widget object has gone.
+    """
+    _annotator().forget(widget)
+
+
+def describe(root: tkinter.Misc) -> Description:
+    """Say what this application has told Windows about the widgets under `root`.
+
+    Reports what tk-uia believes it wrote, which is not evidence that a client
+    can read it. `print()` it for the report, or read `.widgets` for the same
+    thing as data. Raises `AnnotationRefused` where `enable()` has never run.
+    """
+    return _describe(root, _the_installation())
+
+
+def check_screenreader() -> bool:
+    """Whether Windows believes something is reading the screen aloud."""
+    from tk_uia._accprop import screen_reader_running
+
+    return screen_reader_running()
+
+
+def _annotator() -> Annotator | InertAnnotator:
+    return _the_installation().annotator
+
+
+def _the_installation() -> Installation:
+    if _installed is None:
+        raise AnnotationRefused(
+            "tk_uia.enable(root) has not been called, so there is nothing to "
+            "annotate through; call it once after building the window and "
+            "before saying anything about the widgets in it"
+        )
+    return _installed

tk_uia/_accprop.py

@@ -0,0 +1,288 @@
+"""The `oleacc` calls an annotation is actually made of.
+
+Two details here return `S_OK` and do nothing at all when they are wrong, so
+neither is guessed at:
+
+* every `PROPID_ACC_*` GUID is transcribed from `oleacc.h` in the Windows SDK
+  (10.0.22621.0), not recalled. `PROPID_ACC_HELP` in particular is not the value
+  intuition suggests;
+* `MSAAPROPID` is `typedef GUID`, so `idProp` is passed **by value**. Passing a
+  pointer compiles, runs, returns `S_OK`, and annotates nothing.
+
+`ctypes.HRESULT` and `ctypes.WINFUNCTYPE` do not exist off Windows, so every
+prototype is built on first use rather than at import.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+from typing import Any
+
+from tk_uia.annotate import PropId
+
+_S_OK = 0
+_S_FALSE = 1
+_RPC_E_CHANGED_MODE = 0x80010106
+_COINIT_APARTMENTTHREADED = 0x2
+_CLSCTX_INPROC_SERVER = 1
+
+_OBJID_CLIENT = 0xFFFFFFFC
+_CHILDID_SELF = 0
+
+# IAccPropServices, after IUnknown's three: SetPropValue 3, SetPropServer 4,
+# ClearProps 5, then these. Verified by calling them, because a wrong slot with
+# these signatures is an access violation rather than a quiet no-op.
+_SLOT_SET_HWND_PROP = 6
+_SLOT_SET_HWND_PROP_STR = 7
+_SLOT_CLEAR_HWND_PROPS = 9
+
+_VT_I4 = 3
+
+# GWLP_ID: the control id Win32 puts in WM_COMMAND.wParam and WM_DRAWITEM.idCtl.
+_GWLP_ID = -12
+
+_SPI_GETSCREENREADER = 0x0046
+
+_WINDOWS = "win32"
+
+# A plain number rather than `ctypes.HRESULT`, which looks like the honest
+# choice and is the wrong one: ctypes raises an `OSError` of its own on any
+# negative HRESULT *before* the caller sees the value, so `_checked` never runs
+# and the application gets a bare "[WinError -2147024891] Access is denied" with
+# no way to tell which of eleven annotation calls refused. Read as a number, the
+# code reaches `_checked`, which also catches the positive non-`S_OK` answers
+# `ctypes.HRESULT` lets through.
+_HOWEVER_COM_ANSWERED = ctypes.c_long
+
+
+class _Guid(ctypes.Structure):
+    _fields_ = (
+        ("Data1", ctypes.c_ulong),
+        ("Data2", ctypes.c_ushort),
+        ("Data3", ctypes.c_ushort),
+        ("Data4", ctypes.c_ubyte * 8),
+    )
+
+
+class _Variant(ctypes.Structure):
+    """VARIANT, in the only shape used here: 24 bytes, holding a long."""
+
+    _fields_ = (
+        ("vt", ctypes.c_ushort),
+        ("reserved1", ctypes.c_ushort),
+        ("reserved2", ctypes.c_ushort),
+        ("reserved3", ctypes.c_ushort),
+        ("value", ctypes.c_longlong),
+        ("padding", ctypes.c_longlong),
+    )
+
+
+def _guid(first: int, second: int, third: int, *rest: int) -> _Guid:
+    return _Guid(first, second, third, (ctypes.c_ubyte * 8)(*rest))
+
+
+# Transcribed from oleacc.h, 10.0.22621.0.
+_CLSID_ACC_PROP_SERVICES = _guid(
+    0xB5F8350B, 0x0548, 0x48B1, 0xA6, 0xEE, 0x88, 0xBD, 0x00, 0xB4, 0xA5, 0xE7
+)
+_IID_IACC_PROP_SERVICES = _guid(
+    0x6E26E776, 0x04F0, 0x495D, 0x80, 0xE4, 0x33, 0x30, 0x35, 0x2E, 0x31, 0x69
+)
+
+_GUID_FOR_PROP = {
+    PropId.NAME: _guid(
+        0x608D3DF8, 0x8128, 0x4AA7, 0xA4, 0x28, 0xF5, 0x5E, 0x49, 0x26, 0x72, 0x91
+    ),
+    PropId.VALUE: _guid(
+        0x123FE443, 0x211A, 0x4615, 0x95, 0x27, 0xC4, 0x5A, 0x7E, 0x93, 0x71, 0x7A
+    ),
+    PropId.DESCRIPTION: _guid(
+        0x4D48DFE4, 0xBD3F, 0x491F, 0xA6, 0x48, 0x49, 0x2D, 0x6F, 0x20, 0xC5, 0x88
+    ),
+    PropId.ROLE: _guid(
+        0xCB905FF2, 0x7BD1, 0x4C05, 0xB3, 0xC8, 0xE6, 0xC2, 0x41, 0x36, 0x4D, 0x70
+    ),
+    PropId.STATE: _guid(
+        0xA8D4D5B0, 0x0A21, 0x42D0, 0xA5, 0xC0, 0x51, 0x4E, 0x98, 0x4F, 0x45, 0x7B
+    ),
+    PropId.HELP: _guid(
+        0xC831E11F, 0x44DB, 0x4A99, 0x97, 0x68, 0xCB, 0x8F, 0x97, 0x8B, 0x72, 0x31
+    ),
+    PropId.DEFAULT_ACTION: _guid(
+        0x180C072B, 0xC27F, 0x43C7, 0x99, 0x22, 0xF6, 0x35, 0x62, 0xA4, 0x63, 0x2B
+    ),
+}
+
+
+class AccPropServicesStore:
+    """Annotations, written where the MSAA-to-UIA bridge reads them."""
+
+    def __init__(self) -> None:
+        # Nothing is reached for here: `enable()` builds one of these before the
+        # version gate has run, and on a machine with no MSAA it is never used.
+        self._services: ctypes.c_void_p | None = None
+
+    def set_string(self, hwnd: int, prop: PropId, value: str) -> None:
+        services = self._reached()
+        call = _method(services, _SLOT_SET_HWND_PROP_STR, _set_hwnd_prop_str())
+        _checked(
+            call(
+                services,
+                ctypes.c_void_p(hwnd),
+                _OBJID_CLIENT,
+                _CHILDID_SELF,
+                _GUID_FOR_PROP[prop],
+                value,
+            ),
+            f"SetHwndPropStr({prop.name})",
+        )
+
+    def set_number(self, hwnd: int, prop: PropId, value: int) -> None:
+        holder = _Variant()
+        holder.vt = _VT_I4
+        holder.value = value
+        services = self._reached()
+        call = _method(services, _SLOT_SET_HWND_PROP, _set_hwnd_prop())
+        _checked(
+            call(
+                services,
+                ctypes.c_void_p(hwnd),
+                _OBJID_CLIENT,
+                _CHILDID_SELF,
+                _GUID_FOR_PROP[prop],
+                holder,
+            ),
+            f"SetHwndProp({prop.name})",
+        )
+
+    def control_id(self, hwnd: int) -> int:
+        return int(_window_long()(ctypes.c_void_p(hwnd), _GWLP_ID))
+
+    def set_control_id(self, hwnd: int, control_id: int) -> None:
+        _set_window_long()(ctypes.c_void_p(hwnd), _GWLP_ID, control_id)
+
+    def clear(self, hwnd: int) -> None:
+        props = list(_GUID_FOR_PROP.values())
+        everything = (_Guid * len(props))(*props)
+        services = self._reached()
+        call = _method(services, _SLOT_CLEAR_HWND_PROPS, _clear_hwnd_props())
+        _checked(
+            call(
+                services,
+                ctypes.c_void_p(hwnd),
+                _OBJID_CLIENT,
+                _CHILDID_SELF,
+                everything,
+                len(props),
+            ),
+            "ClearHwndProps",
+        )
+
+    def _reached(self) -> ctypes.c_void_p:
+        if self._services is None:
+            self._services = _acc_prop_services()
+        return self._services
+
+
+def screen_reader_running() -> bool:
+    """Whether Windows believes something is reading the screen aloud."""
+    if sys.platform != _WINDOWS:
+        return False
+    listening = ctypes.c_int(0)
+    _user32().SystemParametersInfoW(_SPI_GETSCREENREADER, 0, ctypes.byref(listening), 0)
+    return bool(listening.value)
+
+
+def _acc_prop_services() -> ctypes.c_void_p:
+    ole32 = ctypes.windll.ole32
+    started = ole32.CoInitializeEx(None, _COINIT_APARTMENTTHREADED)
+    # S_FALSE means this thread was already in an apartment and
+    # RPC_E_CHANGED_MODE means it is in a different one. Both are somebody
+    # else's apartment to close, which is why CoUninitialize is never called.
+    if started not in (_S_OK, _S_FALSE) and (started & 0xFFFFFFFF) != (
+        _RPC_E_CHANGED_MODE
+    ):
+        raise OSError(f"CoInitializeEx failed 0x{started & 0xFFFFFFFF:08X}")
+    services = ctypes.c_void_p()
+    _checked(
+        ole32.CoCreateInstance(
+            ctypes.byref(_CLSID_ACC_PROP_SERVICES),
+            None,
+            _CLSCTX_INPROC_SERVER,
+            ctypes.byref(_IID_IACC_PROP_SERVICES),
+            ctypes.byref(services),
+        ),
+        "CoCreateInstance(AccPropServices)",
+    )
+    return services
+
+
+def _method(services: ctypes.c_void_p, slot: int, prototype: Any) -> Any:
+    vtable = ctypes.cast(services, ctypes.POINTER(ctypes.c_void_p))[0]
+    return prototype(ctypes.cast(vtable, ctypes.POINTER(ctypes.c_void_p))[slot])
+
+
+def _checked(result: int, what: str) -> None:
+    if result != _S_OK:
+        raise OSError(f"{what} failed 0x{result & 0xFFFFFFFF:08X}")
+
+
+def _set_hwnd_prop() -> Any:
+    return ctypes.WINFUNCTYPE(
+        _HOWEVER_COM_ANSWERED,
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        _Guid,
+        _Variant,
+    )
+
+
+def _set_hwnd_prop_str() -> Any:
+    return ctypes.WINFUNCTYPE(
+        _HOWEVER_COM_ANSWERED,
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        _Guid,
+        ctypes.c_wchar_p,
+    )
+
+
+def _clear_hwnd_props() -> Any:
+    return ctypes.WINFUNCTYPE(
+        _HOWEVER_COM_ANSWERED,
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.POINTER(_Guid),
+        ctypes.c_int,
+    )
+
+
+def _window_long() -> Any:
+    user32 = _user32()
+    # GetWindowLongPtrW exists only in the 64-bit user32; on 32-bit Python the
+    # non-Ptr name is the whole of the API and is already pointer-sized.
+    read = getattr(user32, "GetWindowLongPtrW", None) or user32.GetWindowLongW
+    read.restype = ctypes.c_ssize_t
+    read.argtypes = (ctypes.c_void_p, ctypes.c_int)
+    return read
+
+
+def _set_window_long() -> Any:
+    user32 = _user32()
+    write = getattr(user32, "SetWindowLongPtrW", None) or user32.SetWindowLongW
+    write.restype = ctypes.c_ssize_t
+    write.argtypes = (ctypes.c_void_p, ctypes.c_int, ctypes.c_ssize_t)
+    return write
+
+
+def _user32() -> Any:
+    # Per call rather than at import: `ctypes.windll` does not exist off
+    # Windows, and this module still has to import there.
+    return ctypes.windll.user32

tk_uia/_overlay.py

@@ -0,0 +1,107 @@
+"""The window handles a notebook's tabs borrow, made with four Win32 calls.
+
+Both window styles are load-bearing. `WS_EX_TRANSPARENT` keeps the window out of
+hit-testing, so the click a client aims at a tab reaches the notebook underneath
+and Tk selects it. `SS_OWNERDRAW` makes the static ask its parent to paint it by
+way of `WM_DRAWITEM`; Tk has never heard of this window and ignores the message,
+so nothing is painted and the tab strip shows through. A plain static would
+paint its background over the tab it is standing in for.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Any
+
+# The generic control class every Windows install has. A class of this
+# package's own would leave a stale atom behind on every reload.
+_A_PLAIN_STATIC = "STATIC"
+
+_WS_CHILD = 0x40000000
+_WS_VISIBLE = 0x10000000
+_SS_OWNERDRAW = 0x0000000D
+_WS_EX_TRANSPARENT = 0x00000020
+
+_NO_MENU = None
+_NO_MODULE = None
+_NO_PARAMETER = None
+_REPAINT_IT = True
+
+
+class Win32Overlays:
+    """Real child windows over a real notebook's real tabs."""
+
+    def create(self, parent: int, left: int, top: int, width: int, height: int) -> int:
+        made = _create_window()(
+            _WS_EX_TRANSPARENT,
+            _A_PLAIN_STATIC,
+            None,
+            _WS_CHILD | _WS_VISIBLE | _SS_OWNERDRAW,
+            left,
+            top,
+            width,
+            height,
+            ctypes.c_void_p(parent),
+            _NO_MENU,
+            _NO_MODULE,
+            _NO_PARAMETER,
+        )
+        if not made:
+            raise OSError(
+                f"could not make a window for a tab of {parent:#x}: "
+                f"CreateWindowExW failed with {ctypes.get_last_error()}"
+            )
+        return int(made)
+
+    def move(self, hwnd: int, left: int, top: int, width: int, height: int) -> None:
+        _move_window()(ctypes.c_void_p(hwnd), left, top, width, height, _REPAINT_IT)
+
+    def destroy(self, hwnd: int) -> None:
+        _destroy_window()(ctypes.c_void_p(hwnd))
+
+
+def _create_window() -> Any:
+    make = _user32().CreateWindowExW
+    make.restype = ctypes.c_void_p
+    make.argtypes = (
+        ctypes.c_uint32,
+        ctypes.c_wchar_p,
+        ctypes.c_wchar_p,
+        ctypes.c_uint32,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+    )
+    return make
+
+
+def _move_window() -> Any:
+    move = _user32().MoveWindow
+    move.restype = ctypes.c_int
+    move.argtypes = (
+        ctypes.c_void_p,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+    )
+    return move
+
+
+def _destroy_window() -> Any:
+    close = _user32().DestroyWindow
+    close.restype = ctypes.c_int
+    close.argtypes = (ctypes.c_void_p,)
+    return close
+
+
+def _user32() -> Any:
+    # Per call rather than at import: `ctypes.WinDLL` cannot be built off
+    # Windows, and this module still has to import there.
+    return ctypes.WinDLL("user32", use_last_error=True)

tk_uia/_tkstrip.py

@@ -0,0 +1,53 @@
+"""A real `ttk.Notebook`, answering the three questions the tab scan asks.
+
+There is no public API for a tab's rectangle. `index @x,y` is the same question
+Tk answers for a real mouse click, so scanning with it is the one measurement
+that cannot disagree with where the tab actually is.
+"""
+
+from __future__ import annotations
+
+import tkinter
+from tkinter import ttk
+
+
+class TkTabStrip:
+    """One notebook's strip, as the scan sees it."""
+
+    def __init__(self, notebook: ttk.Notebook) -> None:
+        self._notebook = notebook
+
+    def settle(self) -> None:
+        """Let Tk finish laying the strip out before anything measures it.
+
+        Idle tasks only, never `update()`, which would drain the event queue and
+        re-enter whatever binding is asking for this.
+        """
+        self._notebook.update_idletasks()
+
+    def tab_at(self, x: int, y: int) -> int | None:
+        try:
+            return int(self._notebook.index(f"@{x},{y}"))
+        except (tkinter.TclError, ValueError):
+            # Tk refuses rather than answers for a point that is not on a tab,
+            # which is most of a notebook. Not an error here: it is the answer.
+            return None
+
+    def text_of(self, index: int) -> str:
+        return str(self._notebook.tab(index, "text"))
+
+    def size(self) -> tuple[int, int]:
+        return (self._notebook.winfo_width(), self._notebook.winfo_height())
+
+
+def is_a_notebook(widget: object) -> bool:
+    """Whether this widget is one whose tabs need handles of their own.
+
+    Asked of Tk, never of Python's type system. `isinstance` against
+    `ttk.Notebook` breaks the moment a host re-imports `tkinter.ttk` and makes
+    a second, distinct class: IDLE's `idlelib/run.py` does exactly that, and
+    every notebook it builds failed the check while carrying the right class
+    name all along.
+    """
+    winfo_class = getattr(widget, "winfo_class", None)
+    return winfo_class is not None and winfo_class() == "TNotebook"