[widget Audit] toga.App

core/src/toga/app.py

@@ -8,7 +8,7 @@
 from collections.abc import Iterator, MutableSet
 from email.message import Message
 from importlib import metadata as importlib_metadata
-from typing import Any, Protocol
+from typing import Any, Iterable, Protocol
 
 from toga.command import CommandSet
 from toga.documents import Document
@@ -74,22 +74,14 @@ class WindowSet(MutableSet):
     def __init__(self, app: App):
         """A collection of windows managed by an app.
 
-        A window is automatically added to the app when it is shown. Alternatively, the
-        window can be explicitly added to the app (without being shown) using
-        ``app.windows.add(toga.Window(...))`` or ``app.windows += toga.Window(...)``.
-        Adding a window to an App's window set automatically sets the
+        A window is automatically added to the app when it is created, and removed when
+        it is closed. Adding a window to an App's window set automatically sets the
         :attr:`~toga.Window.app` property of the Window.
-
-        :param app: The app maintaining the window set.
         """
         self.app = app
         self.elements = set()
 
     def add(self, window: Window) -> None:
-        """Add a window to the window set.
-
-        :param window: The :class:`toga.Window` to add
-        """
         if not isinstance(window, Window):
             raise TypeError("Can only add objects of type toga.Window")
         # Silently not add if duplicate
@@ -98,24 +90,12 @@ def add(self, window: Window) -> None:
             window.app = self.app
 
     def discard(self, window: Window) -> None:
-        """Remove a window from the Window set.
-
-        :param window: The :class:`toga.Window` to remove.
-        """
         if not isinstance(window, Window):
             raise TypeError("Can only discard objects of type toga.Window")
         if window not in self.elements:
             raise ValueError(f"{window!r} is not part of this app")
         self.elements.remove(window)
 
-    def __iadd__(self, window: Window) -> None:
-        self.add(window)
-        return self
-
-    def __isub__(self, other: Window) -> None:
-        self.discard(other)
-        return self
-
     def __iter__(self) -> Iterator:
         return iter(self.elements)
 
@@ -244,6 +224,7 @@ def __init__(
         description: str | None = None,
         startup: AppStartupMethod | None = None,
         on_exit: OnExitHandler | None = None,
+        windows=None,  # DEPRECATED
     ):
         """Create a new App instance.
 
@@ -281,7 +262,22 @@ def __init__(
         :param description: A brief (one line) description of the app. If not provided,
             the metadata key ``Summary`` will be used.
         :param startup: A callable to run before starting the app.
+        :param on_exit: The handler to invoke before the application exits.
+        :param windows: **DEPRECATED** – Windows are now automatically added to the
+            current app. Passing this argument will cause an exception.
         """
+        ######################################################################
+        # 2023-10: Backwards compatibility
+        ######################################################################
+        if windows is not None:
+            raise ValueError(
+                "The `windows` constructor argument of toga.App has been removed. "
+                "Windows are now automatically added to the current app."
+            )
+        ######################################################################
+        # End backwards compatibility
+        ######################################################################
+
         # Initialize empty widgets registry
         self._widgets = WidgetRegistry()
 
@@ -416,7 +412,7 @@ def __init__(
         self._startup_method = startup
 
         self._main_window = None
-        self.windows = WindowSet(self)
+        self._windows = WindowSet(self)
 
         self._full_screen_windows = None
 
@@ -525,6 +521,12 @@ def widgets(self) -> WidgetRegistry:
         """
         return self._widgets
 
+    @property
+    def windows(self) -> Iterable[Window]:
+        """The windows managed by the app. Windows are added to the app when they are
+        created, and removed when they are closed."""
+        return self._windows
+
     @property
     def main_window(self) -> MainWindow:
         """The main window for the app."""

core/src/toga/window.py

@@ -131,7 +131,9 @@ def __init__(
         )
 
         self._app = None
-        App.app.windows += self
+        if App.app is None:
+            raise RuntimeError("Cannot create a Window before creating an App")
+        App.app.windows.add(self)
 
         self._toolbar = CommandSet(on_change=self._impl.create_toolbar)
         self.on_close = on_close
@@ -310,7 +312,7 @@ def close(self) -> None:
         undefined, except for :attr:`closed` which can be used to check if the window
         was closed.
         """
-        self.app.windows -= self
+        self.app.windows.discard(self)
         self._impl.close()
         self._closed = True
 

core/tests/app/test_app.py

@@ -282,15 +282,24 @@ def test_create(
 
 
 @pytest.mark.parametrize(
-    "kwargs, message",
+    "kwargs, exc_type, message",
     [
-        (dict(), "Toga application must have a formal name"),
-        (dict(formal_name="Something"), "Toga application must have an app ID"),
+        (dict(), RuntimeError, "Toga application must have a formal name"),
+        (
+            dict(formal_name="Something"),
+            RuntimeError,
+            "Toga application must have an app ID",
+        ),
+        (
+            dict(windows=()),
+            ValueError,
+            "The `windows` constructor argument of toga.App has been removed",
+        ),
     ],
 )
-def test_bad_app_creation(kwargs, message):
+def test_bad_app_creation(kwargs, exc_type, message):
     """Errors are raised"""
-    with pytest.raises(RuntimeError, match=message):
+    with pytest.raises(exc_type, match=message):
         toga.App(**kwargs)
 
 

core/tests/app/test_windowset.py

@@ -58,38 +58,3 @@ def test_add_discard(app, window1, window2):
         match=r"Can only discard objects of type toga.Window",
     ):
         app.windows.discard(object())
-
-
-def test_add_discard_by_operator(app, window1, window2):
-    """An item can be added to a windowset by inline operators"""
-    # The windowset has 3 windows - the main window, plus 2 extras
-    assert len(app.windows) == 3
-
-    with pytest.raises(
-        TypeError,
-        match=r"Can only add objects of type toga.Window",
-    ):
-        app.windows += object()
-
-    # Explicitly re-add a window that is already in the windowset
-    app.windows += window2
-    assert len(app.windows) == 3
-    assert window2 in app.windows
-    assert window2.app == app
-
-    # Explicitly discard a window that is in the windowset
-    app.windows -= window2
-    assert window2 not in app.windows
-
-    # Duplicate discard - it's no longer a member
-    with pytest.raises(
-        ValueError,
-        match=r"<toga.window.Window object at .*> is not part of this app",
-    ):
-        app.windows -= window2
-
-    with pytest.raises(
-        TypeError,
-        match=r"Can only discard objects of type toga.Window",
-    ):
-        app.windows -= object()

core/tests/test_window.py

@@ -70,6 +70,15 @@ def test_window_created_explicit(app):
     assert window.on_close._raw == on_close_handler
 
 
+def test_window_created_without_app():
+    "A window cannot be created without an active app"
+    toga.App.app = None
+    with pytest.raises(
+        RuntimeError, match="Cannot create a Window before creating an App"
+    ):
+        toga.Window()
+
+
 def test_set_app(window, app):
     """A window's app cannot be reassigned"""
     assert window.app == app

docs/reference/api/app.rst

@@ -80,8 +80,6 @@ Reference
 .. autoclass:: toga.App
     :exclude-members: app
 
-.. autoclass:: toga.app.WindowSet
-
 .. autoprotocol:: toga.app.AppStartupMethod
 .. autoprotocol:: toga.app.BackgroundTask
 .. autoprotocol:: toga.app.OnExitHandler